[sr-dev] git:master: tm: add doxygen documentation for sip_msg.[c, h] files

Module: sip-router Branch: master Commit: 1db5459e967bbe34133718a6184266c45c4e868b URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=1db5459… Author: Henning Westerholt <henning.westerholt(a)1und1.de> Committer: Henning Westerholt <henning.westerholt(a)1und1.de> Date: Mon Jul 4 00:40:21 2011 +0200 tm: add doxygen documentation for sip_msg.[c,h] files --- modules/tm/sip_msg.c | 54 +++++++++++++++++++++++++++++------------ modules/tm/sip_msg.h | 65 +++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 89 insertions(+), 30 deletions(-) diff --git a/modules/tm/sip_msg.c b/modules/tm/sip_msg.c index f968acd..0eac3a4 100644 --- a/modules/tm/sip_msg.c +++ b/modules/tm/sip_msg.c @@ -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. @@ -54,6 +41,28 @@ * 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" @@ -66,8 +75,14 @@ #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; diff --git a/modules/tm/sip_msg.h b/modules/tm/sip_msg.h index f006cde..1742207 100644 --- a/modules/tm/sip_msg.h +++ b/modules/tm/sip_msg.h @@ -1,6 +1,4 @@ /* - * $Id$ - * * Copyright (C) 2001-2003 FhG Fokus * * This file is part of ser, a free SIP server. @@ -25,7 +23,27 @@ * 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 @@ -36,20 +54,18 @@ #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{ \ @@ -69,14 +85,35 @@ }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);