tm: add doxygen documentation for sip_msg.[c,h] files
authorHenning Westerholt <henning.westerholt@1und1.de>
Sun, 3 Jul 2011 22:40:21 +0000 (00:40 +0200)
committerHenning Westerholt <henning.westerholt@1und1.de>
Sun, 3 Jul 2011 22:40:21 +0000 (00:40 +0200)
modules/tm/sip_msg.c
modules/tm/sip_msg.h

index f968acd..0eac3a4 100644 (file)
@@ -1,17 +1,4 @@
 /*
- * $Id$
- *
- * cloning a message into shared memory (TM keeps a snapshot
- * of messages in memory); note that many operations, which
- * allocate pkg memory (such as parsing) cannot be used with
- * a cloned message -- it would result in linking pkg structures
- * to shmem msg and eventually in a memory error
- *
- * the cloned message is stored in a single memory fragment to
- * save too many shm_mallocs -- these are expensive as they
- * not only take lookup in fragment table but also a shmem lock
- * operation (the same for shm_free)
- *
  * Copyright (C) 2001-2003 FhG Fokus
  *
  * This file is part of ser, a free SIP server.
  *              later than the SIP msg. (Miklos)
  * 2009-07-22  moved most of the functions to core sip_msg_clone.c  (andrei)*/
 
+/**
+ * @file
+ * @brief TM :: Message cloning functionality
+ * 
+ * Cloning a message into shared memory (TM keeps a snapshot
+ * of messages in memory); note that many operations, which
+ * allocate pkg memory (such as parsing) cannot be used with
+ * a cloned message -- it would result in linking pkg structures
+ * to shmem msg and eventually in a memory error.
+ * 
+ * The cloned message is stored in a single memory fragment to
+ * save too many shm_mallocs -- these are expensive as they
+ * not only take lookup in fragment table but also a shmem lock
+ * operation (the same for shm_free)
+ * 
+ * Allow postponing the cloning of SIP msg:
+ * t_newtran() copies the requests to shm mem without the lumps,
+ * and t_forward_nonack() clones the lumps later when it is called
+ * the first time.
+ * @ingroup tm
+ */
+
 #include "defs.h"
 
 
 #include "../../sip_msg_clone.h"
 #include "../../fix_lumps.h"
 
-/* Warning: Cloner does not clone all hdr_field headers (From, To, etc.). Pointers will reference pkg memory. Dereferencing will crash ser!!! */
 
+/**
+ * @brief Clone a SIP message
+ * @warning Cloner does not clone all hdr_field headers (From, To, etc.). Pointers will reference pkg memory. Dereferencing will crash ser!
+ * @param org_msg Original SIP message
+ * @param sip_msg_len Length of the SIP message
+ * @return Cloned SIP message, or NULL on error
+ */
 struct sip_msg*  sip_msg_cloner( struct sip_msg *org_msg, int *sip_msg_len )
 {
        /* take care of the lumps only for replies if the msg cloning is 
@@ -79,12 +94,19 @@ struct sip_msg*  sip_msg_cloner( struct sip_msg *org_msg, int *sip_msg_len )
        return sip_msg_shm_clone(org_msg, sip_msg_len, 0);
 }
 
-/* indicates wheter we have already cloned the msg lumps or not */
+/**
+ * @brief Indicates wheter we have already cloned the msg lumps or not
+ */
 unsigned char lumps_are_cloned = 0;
 
 
 
-/* wrapper function for msg_lump_cloner() with some additional sanity checks */
+/**
+ * @brief Wrapper function for msg_lump_cloner() with some additional sanity checks
+ * @param shm_msg SIP message in shared memory
+ * @param pgk_msg SIP message in private memory
+ * @return 0 on success, -1 on error
+ */
 int save_msg_lumps( struct sip_msg *shm_msg, struct sip_msg *pkg_msg)
 {
        int ret;
index f006cde..1742207 100644 (file)
@@ -1,6 +1,4 @@
 /*
- * $Id$
- *
  * Copyright (C) 2001-2003 FhG Fokus
  *
  * This file is part of ser, a free SIP server.
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
-
+/**
+ * @file
+ * @brief TM :: Message cloning functionality
+ * 
+ * Cloning a message into shared memory (TM keeps a snapshot
+ * of messages in memory); note that many operations, which
+ * allocate pkg memory (such as parsing) cannot be used with
+ * a cloned message -- it would result in linking pkg structures
+ * to shmem msg and eventually in a memory error.
+ * 
+ * The cloned message is stored in a single memory fragment to
+ * save too many shm_mallocs -- these are expensive as they
+ * not only take lookup in fragment table but also a shmem lock
+ * operation (the same for shm_free)
+ * 
+ * Allow postponing the cloning of SIP msg:
+ * t_newtran() copies the requests to shm mem without the lumps,
+ * and t_forward_nonack() clones the lumps later when it is called
+ * the first time.
+ * @ingroup tm
+ */
 
 #ifndef _SIP_MSG_H
 #define _SIP_MSG_H
 #include "../../parser/msg_parser.h"
 #include "../../mem/shm_mem.h"
 
-/* Allow postponing the cloning of SIP msg:
- * t_newtran() copies the requests to shm mem without the lumps,
- * and t_forward_nonack() clones the lumps later when it is called
- * the first time.
- * Replies use only one memory block.
- */
 
 #include "../../atomic_ops.h" /* membar_depends() */
 
-/* msg is a reply: one memory block was allocated
+/**
+ * @brief Helper function to free a SIP message
+ * 
+ * msg is a reply: one memory block was allocated
+ * 
  * msg is a request: two memory blocks were allocated:
- *     - one for the sip_msg struct
- *     - another one for the lumps which is linked to
- *             add_rm, body_lumps, or reply_lump. 
+ * - one for the sip_msg struct
+ * - another one for the lumps which is linked to add_rm, body_lumps,
+ *   or reply_lump
  */
 #define  _sip_msg_free(_free_func, _p_msg) \
                do{ \
                }while(0)
 
 
+/**
+ * @brief Free a SIP message safely, with locking
+ */
 #define  sip_msg_free(_p_msg) _sip_msg_free(shm_free, _p_msg)
+/**
+ * @brief Free a SIP message unsafely, without locking
+ */
 #define  sip_msg_free_unsafe(_p_msg) _sip_msg_free(shm_free_unsafe, _p_msg)
 
-
+/**
+ * @brief Clone a SIP message
+ * @warning Cloner does not clone all hdr_field headers (From, To, etc.). Pointers will reference pkg memory. Dereferencing will crash ser!
+ * @param org_msg Original SIP message
+ * @param sip_msg_len Length of the SIP message
+ * @return Cloned SIP message, or NULL on error
+ */
 struct sip_msg*  sip_msg_cloner( struct sip_msg *org_msg, int *sip_msg_len );
 
+/**
+ * @brief Indicates wheter we have already cloned the msg lumps or not
+ */
 extern unsigned char lumps_are_cloned;
 
+/**
+ * @brief Wrapper function for msg_lump_cloner() with some additional sanity checks
+ * @param shm_msg SIP message in shared memory
+ * @param pgk_msg SIP message in private memory
+ * @return 0 on success, -1 on error
+ */
 int save_msg_lumps( struct sip_msg *shm_msg, struct sip_msg *pkg_msg);