[sr-dev] git:master: tm: add doxygen documentation for sip_msg.[c, h] files
Henning Westerholt
henning.westerholt at 1und1.de
Mon Jul 4 09:45:51 CEST 2011
Module: sip-router
Branch: master
Commit: 1db5459e967bbe34133718a6184266c45c4e868b
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=1db5459e967bbe34133718a6184266c45c4e868b
Author: Henning Westerholt <henning.westerholt at 1und1.de>
Committer: Henning Westerholt <henning.westerholt at 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);
More information about the sr-dev
mailing list