Documentation and doxygen updates

dns_wrappers.h

@@ -31,6 +31,13 @@
  *  2006-07-23  created by andrei
  */
 
+/**
+ * @file
+ * @brief SIP-router core :: resolver related functions
+ * @ingroup core
+ * Module: @ref core
+ */
+
 #ifndef __dns_wrappers_h
 #define __dns_wrappers_h
 

dprint.h

@@ -10,11 +10,6 @@
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * For a license to use the ser software under conditions
- * other than those described here, or to purchase support for this
- * software, please contact iptel.org by e-mail at the following addresses:
- *    [email protected]
- *
  * ser is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@@ -25,6 +20,13 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/**
+ * @file
+ * @brief SIP-router core :: debug printing
+ * @ingroup core
+ * Module: @ref core
+ */
+
 #ifndef dprint_h
 #define dprint_h
 
@@ -82,7 +84,7 @@
 #define L_INFO   	2
 #define L_DBG    	3
 
-/* This is the facility value used to indicate that the caller of the macro
+/** @brief This is the facility value used to indicate that the caller of the macro
  * did not override the facility. Value 0 (the defaul) is LOG_KERN on Linux
  */
 #define DEFAULT_FACILITY 0
@@ -92,15 +94,15 @@
 	(log_level_info[(level) - (L_ALERT)].syslog_level)
 
 
-/* my_pid(), process_no are from pt.h but we cannot #include it here
+/** @brief my_pid(), process_no are from pt.h but we cannot #include it here
    because of circular dependencies */
 extern int process_no;
 extern int my_pid();
 
-/* non-zero if logging to stderr instead to the syslog */
+/** @brief non-zero if logging to stderr instead to the syslog */
 extern int log_stderr;
 
-/* maps log levels to their string name and corresponding syslog level */
+/** @brief maps log levels to their string name and corresponding syslog level */
 
 struct log_level_info {
  	char *name;
@@ -112,7 +114,7 @@ extern struct log_level_info log_level_info[];
 extern char *log_name;
 
 #ifndef NO_SIG_DEBUG
-/* protection against "simultaneous" printing from signal handlers */
+/** @brief protection against "simultaneous" printing from signal handlers */
 extern volatile int dprint_crit; 
 #endif
 
@@ -120,7 +122,7 @@ int str2facility(char *s);
 int log_facility_fixup(void *handle, str *gname, str *name, void **val);
 
 
-/*
+/** @brief
  * General logging macros
  *
  * LOG_(level, prefix, fmt, ...) prints "printf"-formatted log message to
@@ -255,9 +257,10 @@ int log_facility_fixup(void *handle, str *gname, str *name, void **val);
 #endif /* NO_LOG */
 
 
-/*
+/** @name SimpleLog
  * Simplier, prefered logging macros for constant log level
  */
+/*@ { */
 #ifdef __SUNPRO_C
 #	define ALERT(...)  LOG(L_ALERT,  __VA_ARGS__)
 #	define BUG(...)    LOG(L_BUG,   __VA_ARGS__)
@@ -272,6 +275,7 @@ int log_facility_fixup(void *handle, str *gname, str *name, void **val);
 #	else
 #		define DBG(...)    LOG(L_DBG, __VA_ARGS__)
 #	endif		
+/*@ } */
 
 /* obsolete, do not use */
 #	define DEBUG(...) DBG(__VA_ARGS__)

dset.h

@@ -10,11 +10,6 @@
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * For a license to use the ser software under conditions
- * other than those described here, or to purchase support for this
- * software, please contact iptel.org by e-mail at the following addresses:
- *    [email protected]
- *
  * ser is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@@ -25,6 +20,13 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*!
+ * \file
+ * \brief SIP-router core :: Destination set handling
+ * \ingroup core
+ * Module: \ref core
+ */
+
 #ifndef _DSET_H
 #define _DSET_H
 
@@ -36,20 +38,18 @@ struct sip_msg;
 
 extern unsigned int nr_branches;
 
-
-
-/*
+/*! \brief
  * Add a new branch to current transaction 
  */
 int append_branch(struct sip_msg* msg, str* uri, str* dst_uri, str* path,
 					 qvalue_t q, unsigned int flags,
 					 struct socket_info* force_socket);
 
-/* kamailio compatible version */
+/*! \brief kamailio compatible version */
 #define km_append_branch(msg, uri, dst_uri, path, q, flags, force_socket) \
 	append_branch(msg, uri, dst_uri, path, q, flags, force_socket)
 
-/** ser compatible append_branch version.
+/*! \brief ser compatible append_branch version.
  *  append_branch version compatible with ser: no path or branch flags support
  *  and no str parameters.
  */
@@ -69,18 +69,18 @@ static inline int ser_append_branch(struct sip_msg* msg,
 
 
 
-/*
+/*! \brief
  * Iterate through the list of transaction branches 
  */
 void init_branch_iterator(void);
 
-/* 
+/*! \brief
  * Return branch iterator position 
  */
 int get_branch_iterator(void);
 
 
-/** Get the next branch in the current transaction.
+/*! \brief Get the next branch in the current transaction.
  * @return pointer to the uri of the next branch (which the length written in
  *  *len) or 0 if there are no more branches.
  */
@@ -94,26 +94,26 @@ char* get_branch( unsigned int i, int* len, qvalue_t* q, str* dst_uri,
 
 
 
-/*
+/*! \brief
  * Empty the array of branches
  */
 void clear_branches(void);
 
 
-/*
+/*! \brief
  * Create a Contact header field from the
  * list of current branches
  */
 char* print_dset(struct sip_msg* msg, int* len);
 
 
-/* 
+/*! \brief
  * Set the q value of the Request-URI
  */
 void set_ruri_q(qvalue_t q);
 
 
-/* 
+/*! \brief
  * Get the q value of the Request-URI
  */
 qvalue_t get_ruri_q(void);
@@ -121,7 +121,7 @@ qvalue_t get_ruri_q(void);
 int get_request_uri(struct sip_msg* _m, str* _u);
 int rewrite_uri(struct sip_msg* _m, str* _s);
 
-/**
+/*! \brief
  * Set a per-branch flag to 1.
  *
  * This function sets the value of one particular branch flag to 1.
@@ -131,7 +131,7 @@ int rewrite_uri(struct sip_msg* _m, str* _s);
  */
 int setbflag(unsigned int branch, flag_t flag);
 
-/**
+/*! \brief
  * Reset a per-branch flag value to 0.
  *
  * This function resets the value of one particular branch flag to 0.
@@ -141,7 +141,7 @@ int setbflag(unsigned int branch, flag_t flag);
  */
 int resetbflag(unsigned int branch, flag_t flag);
 
-/**
+/*! \brief
  * Determine if a branch flag is set.
  *
  * This function tests the value of one particular per-branch flag.
@@ -151,7 +151,7 @@ int resetbflag(unsigned int branch, flag_t flag);
  */
 int isbflagset(unsigned int branch, flag_t flag);
 
-/**
+/*! \brief
  * Get the value of all branch flags for a branch
  *
  * This function returns the value of all branch flags
@@ -162,7 +162,7 @@ int isbflagset(unsigned int branch, flag_t flag);
  */
 int getbflagsval(unsigned int branch, flag_t* res);
 
-/**
+/*! \brief
  * Set the value of all branch flags at once for a given branch.
  *
  * This function sets the value of all branch flags for a given

dst_blacklist.h

@@ -1,8 +1,6 @@
 /*
  * $Id$
  *
- * resolver related functions
- *
  * Copyright (C) 2006 iptelorg GmbH
  *
  * This file is part of ser, a free SIP server.
@@ -12,11 +10,6 @@
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * For a license to use the ser software under conditions
- * other than those described here, or to purchase support for this
- * software, please contact iptel.org by e-mail at the following addresses:
- *    [email protected]
- *
  * ser is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@@ -26,6 +19,14 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
+
+/**
+ * @file
+ * @brief SIP-router core :: Destination blacklists
+ * @ingroup core
+ * Module: @ref core
+ */
+
 /* History:
  * --------
  *  2006-07-29  created by andrei
@@ -40,25 +41,28 @@
 #include "timer_ticks.h"
 #include "cfg_core.h"
 
-#define DEFAULT_BLST_TIMEOUT		60  /* 1 min. */
-#define DEFAULT_BLST_MAX_MEM		250 /* 250 KB */
+#define DEFAULT_BLST_TIMEOUT		60  /**< 1 min. */
+#define DEFAULT_BLST_MAX_MEM		250 /**< 250 KB */
+
+/** @name flags: */
+/*@{ */
 
-/* flags: */
-#define BLST_IS_IPV6		1		/* set if the address is ipv6 */
-#define BLST_ERR_SEND		(1<<1)	/* set if  send is denied/failed */
-#define BLST_ERR_CONNECT	(1<<2)	/* set if connect failed (tcp/tls) */
-#define BLST_ICMP_RCVD		(1<<3)	/* set if icmp error */
-#define BLST_ERR_TIMEOUT	(1<<4)	/* set if sip timeout */
-#define BLST_503			(1<<5)	/* set for 503 replies */
-#define BLST_ADM_PROHIBITED	(1<<6)	/* administratively prohibited */
-#define BLST_PERMANENT		(1<<7)  /* never deleted, never expires */
+#define BLST_IS_IPV6		1		/**< set if the address is ipv6 */
+#define BLST_ERR_SEND		(1<<1)	/**< set if  send is denied/failed */
+#define BLST_ERR_CONNECT	(1<<2)	/**< set if connect failed (tcp/tls) */
+#define BLST_ICMP_RCVD		(1<<3)	/**< set if icmp error */
+#define BLST_ERR_TIMEOUT	(1<<4)	/**< set if sip timeout */
+#define BLST_503			(1<<5)	/**< set for 503 replies */
+#define BLST_ADM_PROHIBITED	(1<<6)	/**< administratively prohibited */
+#define BLST_PERMANENT		(1<<7)  /**< never deleted, never expires */
+/*@} */
 
 /* uncomment the define above to enable blacklist callbacks support */
 /*#define DST_BLACKLIST_HOOKS*/
 
-#define DST_BLACKLIST_CONTINUE 0 /* add: do nothing/ignore, search: ignore */
-#define DST_BLACKLIST_ACCEPT 1   /* add: force accept, search: force match */
-#define DST_BLACKLIST_DENY  -1   /* add: deny, search: force no match */
+#define DST_BLACKLIST_CONTINUE 0 /**< add: do nothing/ignore, search: ignore */
+#define DST_BLACKLIST_ACCEPT 1   /**< add: force accept, search: force match */
+#define DST_BLACKLIST_DENY  -1   /**< add: deny, search: force no match */
 
 #define DST_BLACKLIST_ADD_CB 1
 #define DST_BLACKLIST_SEARCH_CB 2
@@ -85,22 +89,22 @@ int init_dst_blacklist_stats(int iproc_num);
 void destroy_dst_blacklist();
 
 
-/* like dst_blacklist_add, but the timeout can be also set */
+/** @brief like dst_blacklist_add, but the timeout can be also set */
 int dst_blacklist_add_to(unsigned char err_flags, struct dest_info* si,
 						struct sip_msg* msg, ticks_t timeout);
-/* like above, but using a differnt way of passing the target */
+/** @brief like above, but using a differnt way of passing the target */
 int dst_blacklist_su_to(unsigned char err_flags, unsigned char proto,
 							union sockaddr_union* dst,
 							struct sip_msg* msg, ticks_t timeout);
 
-/** adds a dst to the blacklist with default timeout.
+/** @brief adds a dst to the blacklist with default timeout.
  * @see dst_blacklist_add_to for more details.
  */
 #define dst_blacklist_add(err_flags, si, msg) \
 	dst_blacklist_add_to((err_flags), (si), (msg), \
 		S_TO_TICKS(cfg_get(core, core_cfg, blst_timeout)))
 
-/** adds a dst to the blacklist with default timeout.
+/** @brief adds a dst to the blacklist with default timeout.
  * @see dst_blacklist_su_to for more details.
  */
 #define dst_blacklist_su(err_flags, proto, dst, msg) \
@@ -108,16 +112,18 @@ int dst_blacklist_su_to(unsigned char err_flags, unsigned char proto,
 		S_TO_TICKS(cfg_get(core, core_cfg, blst_timeout)))
 
 int dst_is_blacklisted(struct dest_info* si, struct sip_msg* msg);
-/* delete an entry from the blacklist */
+
+/** @brief  delete an entry from the blacklist */
 int dst_blacklist_del(struct dest_info* si, struct sip_msg* msg);
 
-/* deletes all the entries from the blacklist except the permanent ones
+/** @brief deletes all the entries from the blacklist except the permanent ones
  * (which are marked with BLST_PERMANENT)
  */
 void dst_blst_flush(void);
 
 int use_dst_blacklist_fixup(void *handle, str *gname, str *name, void **val);
-/* KByte to Byte conversion */
+
+/** @brief KByte to Byte conversion */
 int blst_max_mem_fixup(void *handle, str *gname, str *name, void **val);
 
 #endif

endianness.h

@@ -15,27 +15,25 @@
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
-/*
+
+/** @file
  *  endianness compile and runtime  tests
  * 
  * History:
  * --------
  *  2008-06-13  created by andrei
- */
-
-/*
+ *
  * Defines:
- *    __IS_LITTLE_ENDIAN if the system is little endian and
- *    __IS_BIG_ENDIAN    if it's big endian
+ *  -  __IS_LITTLE_ENDIAN if the system is little endian and
+ *  -  __IS_BIG_ENDIAN    if it's big endian
  * Function/macros:
- *     is_big_endian()  - runtime test for big endian
- *     is_little_endian() - runtime test for little endian
- *     endianness_sanity_check() - returns 0 if the compile time
+ *  -   is_big_endian()  - runtime test for big endian
+ *  -   is_little_endian() - runtime test for little endian
+ *  -   endianness_sanity_check() - returns 0 if the compile time
  *                                  detected endianness corresponds to
  *                                  the runtime detected one and -1 on 
  *                                  error (recommended action: bail out)
- */
-/*
+ *
  * Implementation notes:
  * Endian macro names/tests for different OSes:
  * linux:  __BYTE_ORDER == __LITTLE_ENDIAN | __BIG_ENDIAN

error.h

@@ -10,11 +10,6 @@
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * For a license to use the ser software under conditions
- * other than those described here, or to purchase support for this
- * software, please contact iptel.org by e-mail at the following addresses:
- *    [email protected]
- *
  * ser is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

fix_lumps.h

@@ -16,11 +16,6 @@
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * For a license to use the ser software under conditions
- * other than those described here, or to purchase support for this
- * software, please contact iptel.org by e-mail at the following addresses:
- *    [email protected]
- *
  * ser is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@@ -46,8 +41,9 @@
 
 
 
-/* used to delete attached via lumps from msg; msg can
-   be either an original pkg msg, whose Via lump I want
+/** @brief used to delete attached via lumps from msg;
+
+   msg can be either an original pkg msg, whose Via lump I want
    to delete before generating next branch, or a shmem-stored
    message processed during on_reply -- then I want to
    delete the Via lump for the same reason

modules_k/pua/README

@@ -1,4 +1,3 @@
-
 Presence User Agent Module
 
 Anca-Maria Vamanu
@@ -11,45 +10,44 @@ Anca-Maria Vamanu
 
    Copyright © 2006 voice-system.ro
    Revision History
-   Revision $Revision$ $Date: 2008-08-06 12:08:33 +0200
-   (Wed, 06 Aug 2008) $
-     _________________________________________________________
+   Revision $Revision$ $Date$
+     __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
-        1.1. Overview
-        1.2. Dependencies
+        1. Overview
+        2. Dependencies
 
-              1.2.1. Kamailio Modules
-              1.2.2. External Libraries or Applications
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
 
-        1.3. Exported Parameters
+        3. Exported Parameters
 
-              1.3.1. hash_size (int)
-              1.3.2. db_url (str)
-              1.3.3. db_table (str)
-              1.3.4. min_expires (int)
-              1.3.5. default_expires (int)
-              1.3.6. update_period (int)
-              1.3.7. outbound_proxy (str)
-              1.3.8. dlginfo_increase_version (int)
+              3.1. hash_size (int)
+              3.2. db_url (str)
+              3.3. db_table (str)
+              3.4. min_expires (int)
+              3.5. default_expires (int)
+              3.6. update_period (int)
+              3.7. outbound_proxy (str)
+              3.8. dlginfo_increase_version (int)
 
-        1.4. Exported Functions
+        4. Exported Functions
 
-              1.4.1. pua_update_contact() 
+              4.1. pua_update_contact()
 
-        1.5. Installation
+        5. Installation
 
    2. Developer Guide
 
-        2.1. bind_pua(pua_api_t* api) 
-        2.2. send_publish 
-        2.3. send_subscribe 
-        2.4. is_dialog 
-        2.5. register_puacb 
-        2.6. add_event 
+        1. bind_pua(pua_api_t* api)
+        2. send_publish
+        3. send_subscribe
+        4. is_dialog
+        5. register_puacb
+        6. add_event
 
    List of Examples
 
@@ -69,156 +67,195 @@ Anca-Maria Vamanu
 
 Chapter 1. Admin Guide
 
-1.1. Overview
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Exported Parameters
+
+        3.1. hash_size (int)
+        3.2. db_url (str)
+        3.3. db_table (str)
+        3.4. min_expires (int)
+        3.5. default_expires (int)
+        3.6. update_period (int)
+        3.7. outbound_proxy (str)
+        3.8. dlginfo_increase_version (int)
+
+   4. Exported Functions
+
+        4.1. pua_update_contact()
+
+   5. Installation
+
+1. Overview
+
+   This module offer the functionality of a presence user agent client,
+   sending Subscribe and Publish messages. It's a core part of Kamailio's
+   SIP presence package, implementing SIMPLE and various shared line
+   appearance implementations.
 
-   This module offer the functionality of a presence user agent
-   client, sending Subscribe and Publish messages.
+   It can be used with the following modules: pua_mi and pua_usrloc,
+   pua_bla and pua_xmpp. The <emphasize>pua_mi</emphasize> offer the
+   possibility to publish any kind of information or subscribing to a
+   resource through the manager interface. The
+   <emphasize>pua_usrloc</emphasize> module calls a function exported by
+   pua modules to publish elementary presence information, such as basic
+   status "open" or "closed", for clients that do not implement
+   client-to-server presence. Through <emphasize>pua_bla</emphasize> ,
+   BRIDGED LINE APPEARANCE features are added to openser. The
+   <emphasize>pua_xmpp</emphasize> module represents a gateway between SIP
+   and XMPP, so that jabber and SIP clients can exchange presence
+   information.
 
-   Now it can be used with the following modules: pua_mi and
-   pua_usrloc, pua_bla and pua_xmpp. The pua_mi offer the
-   possibility to publish any kind of information or subscribing
-   to a resource through fifo. The pua_usrloc module calls a
-   function exported by pua modules to publish elementary
-   presence information, such as basic status "open" or "closed",
-   for clients that do not implement client-to-server presence.
-   Through pua_bla , BRIDGED LINE APPEARANCE features are added
-   to openser. The pua_xmpp module represents a gateway between
-   SIP and XMPP, so that jabber and SIP clients can exchange
-   presence information.
+   The module use a cache to store the presentity list and writes to
+   database on timer to be able to recover upon restart. The presence is
+   kept in-memory during run-time.
 
-   The module use cache to store presentity list and writes to
-   database on timer to be able to recover upon restart.
+2. Dependencies
 
-1.2. Dependencies
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
 
-1.2.1. Kamailio Modules
+2.1. Kamailio Modules
 
    The following modules must be loaded before this module:
      * a database modules.
      * tm.
 
-1.2.2. External Libraries or Applications
+2.2. External Libraries or Applications
 
-   The following libraries or applications must be installed
-   before running Kamailio with this module loaded:
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
      * libxml.
 
-1.3. Exported Parameters
+3. Exported Parameters
 
-1.3.1. hash_size (int)
+   3.1. hash_size (int)
+   3.2. db_url (str)
+   3.3. db_table (str)
+   3.4. min_expires (int)
+   3.5. default_expires (int)
+   3.6. update_period (int)
+   3.7. outbound_proxy (str)
+   3.8. dlginfo_increase_version (int)
 
-   The size of the hash table used for storing Subscribe and
-   Publish information. This parameter will be used as the power
-   of 2 when computing table size.
+3.1. hash_size (int)
 
-   Default value is "9". 
+   The size of the hash table used for storing Subscribe and Publish
+   information. This parameter will be used as the power of 2 when
+   computing table size.
+
+   Default value is "9".
 
    Example 1.1. Set hash_size parameter
 ...
 modparam("pua", "hash_size", 11)
 ...
 
-1.3.2. db_url (str)
+3.2. db_url (str)
 
    Database url.
 
-   Default value is
-   ">mysql://openser:openserrw@localhost/openser". 
+   Default value is ">mysql://openser:openserrw@localhost/openser".
 
    Example 1.2. Set db_url parameter
 ...
 modparam("pua", "db_url" "dbdriver://username:password@dbhost/dbname")
 ...
 
-1.3.3. db_table (str)
+3.3. db_table (str)
 
    The name of the database table.
 
-   Default value is "pua". 
+   Default value is "pua".
 
    Example 1.3. Set db_table parameter
 ...
 modparam("pua", "db_table", "pua")
 ...
 
-1.3.4. min_expires (int)
+3.4. min_expires (int)
 
    The inferior expires limit for both Publish and Subscribe.
 
-   Default value is "0". 
+   Default value is "0".
 
    Example 1.4. Set min_expires parameter
 ...
 modparam("pua", "min_expires", 0)
 ...
 
-1.3.5. default_expires (int)
+3.5. default_expires (int)
 
    The default expires value used in case this information is not
    provisioned.
 
-   Default value is "3600". 
+   Default value is "3600".
 
    Example 1.5. Set default_expires parameter
 ...
 modparam("pua", "default_expires", 3600)
 ...
 
-1.3.6. update_period (int)
+3.6. update_period (int)
 
-   The interval at which the information in database and hash
-   table should be updated. In the case of the hash table
-   updating is deleting expired messages.
+   The interval at which the information in database and hash table should
+   be updated. In the case of the hash table updating means deleting
+   expired messages.
 
-   Default value is "100". 
+   Default value is "100".
 
    Example 1.6. Set update_period parameter
 ...
 modparam("pua", "update_period", 100)
 ...
 
-1.3.7. outbound_proxy (str)
+3.7. outbound_proxy (str)
 
-   SIP URI of outbound proxy to be used when sending PUBLISH
-   requests.
+   SIP URI of outbound proxy to be used when sending PUBLISH requests.
 
-   By default, no outbound proxy has been defined. 
+   By default, no outbound proxy has been defined.
 
    Example 1.7. Set outbound_proxy parameter
 ...
 modparam("pua", "outbound_proxy", "sip:outbound.example.com")
 ...
 
-1.3.8. dlginfo_increase_version (int)
+3.8. dlginfo_increase_version (int)
 
-   When sending PUBLISHs for Event: dialog, the body contains an
-   XML document according to RFC 4235. This XML document contains
-   a version attribut to easily detect changes in the dialog
-   state. By setting this parameter, the pua module parses the
-   XML document and sets the version attribute to the proper
-   value. If the receiver of the PUBLISH does not care about the
-   version parameter (e.g. like Kamailio presence_dialoginfo
-   module) it makes no sense to waste CPU resources for parsing
-   the XML body and the parameter should be set to 0.
+   When sending PUBLISHs for Event: dialog, the body contains an XML
+   document according to RFC 4235. This XML document contains a version
+   attribute to easily detect changes in the dialog state. By setting this
+   parameter, the pua module parses the XML document and sets the version
+   attribute to the proper value. If the receiver of the PUBLISH does not
+   care about the version parameter (e.g. like Kamailio
+   presence_dialoginfo module) it makes no sense to waste CPU resources
+   for parsing the XML body and the parameter should be set to 0.
 
-   Default value is "0". 
+   Default value is "0".
 
    Example 1.8. Set dlginfo_increase_version parameter
 ...
 modparam("pua", "dlginfo_increase_version", 1)
 ...
 
-1.4. Exported Functions
+4. Exported Functions
+
+   4.1. pua_update_contact()
 
-1.4.1.  pua_update_contact()
+4.1. pua_update_contact()
 
-   The remote target can be updated by the Contact of a
-   subsequent in dialog request. In the PUA watcher case (sending
-   a SUBSCRIBE messages), this means that the remote target for
-   the following Subscribe messages can be updated at any time by
-   the contact of a Notify message. If this function is called on
-   request route on receiving a Notify message, it will try to
-   update the stored remote target.
+   The remote target can be updated by the Contact of a subsequent in
+   dialog request. In the PUA watcher case (sending a SUBSCRIBE messages),
+   this means that the remote target for the following Subscribe messages
+   can be updated at any time by the contact of a Notify message. If this
+   function is called on request route on receiving a Notify message, it
+   will try to update the stored remote target.
 
    This function can be used from REQUEST_ROUTE.
 
@@ -232,24 +269,32 @@ if(method=="NOTIFY")
     pua_update_contact();
 ...
 
-1.5. Installation
+5. Installation
 
-   The module requires 1 table in Kamailio database: pua. The SQL
-   syntax to create it can be found in presence_xml-create.sql
-   script in the database directories in the kamailio/scripts
-   folder. You can also find the complete database documentation
-   on the project webpage,
+   The module requires one table in the Kamailio database: pua. The SQL
+   syntax to create it can be found in presence_xml-create.sql script in
+   the database directories in the kamailio/scripts folder. You can also
+   find the complete database documentation on the project webpage,
    http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
 
 Chapter 2. Developer Guide
 
-   The module provides the following functions that can be used
-   in other Kamailio modules.
+   Table of Contents
+
+   1. bind_pua(pua_api_t* api)
+   2. send_publish
+   3. send_subscribe
+   4. is_dialog
+   5. register_puacb
+   6. add_event
+
+   The module provides the following functions that can be used by other
+   Kamailio modules.
 
-2.1.  bind_pua(pua_api_t* api)
+1. bind_pua(pua_api_t* api)
 
-   This function binds the pua modules and fills the structure
-   with the two exported function.
+   This function binds the pua modules and fills the structure with the
+   two exported functions.
 
    Example 2.1. pua_api structure
 ...
@@ -262,15 +307,15 @@ typedef struct pua_api {
 } pua_api_t;
 ...
 
-2.2.  send_publish
+2. send_publish
 
    Field type:
 ...
 typedef int (*send_publish_t)(publ_info_t* publ);
 ...
 
-   This function receives as a parameter a structure with Publish
-   required information and sends a Publish message.
+   This function receives as a parameter a structure with Publish required
+   information and sends a Publish message.
 
    The structure received as a parameter:
 ...
@@ -281,13 +326,11 @@ typedef struct publ_info
   str* pres_uri;      /*  the presentity uri */
   str* body;          /*  the body of the Publish message;
                           can be NULL in case of an update expires*/
-
   int  expires;       /*  the expires value that will be used in
                           Publish Expires header*/
   int flag;           /*  it can be : INSERT_TYPE or UPDATE_TYPE
                           if missing it will be established according
                           to the result of the search in hash table*/
-
   int source_flag;    /*  flag identifying the resource ;
                           supported values: UL_PUBLISH, MI_PUBLISH,
                           BLA_PUBLISH, XMPP_PUBLISH*/
@@ -305,7 +348,6 @@ typedef struct publ_info
                           the reply for the sent request */
   void* cbparam;      /*  extra parameter for tha callback function */
 
-
 }publ_info_t;
 ...
 
@@ -314,15 +356,15 @@ typedef struct publ_info
 typedef int (publrpl_cb_t)(struct sip_msg* reply, void*  extra_param);
 ...
 
-2.3.  send_subscribe
+3. send_subscribe
 
    Field type:
 ...
 typedef int (*send_subscribe_t)(subs_info_t* subs);
 ...
 
-   This function receives as a parameter a structure with
-   Subscribe required information and sends a Subscribe message.
+   This function receives as a parameter a structure with Subscribe
+   required information and sends a Subscribe message.
 
    The structure received as a parameter:
 ...
@@ -353,15 +395,15 @@ typedef struct subs_info
 }subs_info_t;
 ...
 
-2.4.  is_dialog
+4. is_dialog
 
    Field type:
 ...
 typedef int  (*query_dialog_t)(ua_pres_t* presentity);
 ...
 
-   This function checks is the parameter corresponds to a stored
-   Subscribe initiated dialog.
+   This function checks is the parameter corresponds to a stored Subscribe
+   initiated dialog.
 
    Example 2.2. pua_is_dialog usage example
 ...
@@ -372,20 +414,19 @@ typedef int  (*query_dialog_t)(ua_pres_t* presentity);
         }
 ...
 
-2.5.  register_puacb
+5. register_puacb
 
    Field type:
 ...
 typedef int (*register_puacb_t)(int types, pua_cb f, void* param );
 ...
 
-   This function registers a callback to be called on receiving
-   the reply message for a sent Subscribe request. The type
-   parameter should be set the same as the source_flag for that
-   request. The function registered as callback for pua should be
-   of type pua_cb , which is: typedef void (pua_cb)(ua_pres_t*
-   hentity, struct msg_start * fl); The parameters are the dialog
-   structure for that request and the first line of the reply
+   This function registers a callback to be called on receiving the reply
+   message for a sent Subscribe request. The type parameter should be set
+   the same as the source_flag for that request. The function registered
+   as callback for pua should be of type pua_cb , which is: typedef void
+   (pua_cb)(ua_pres_t* hentity, struct msg_start * fl); The parameters are
+   the dialog structure for that request and the first line of the reply
    message.
 
    Example 2.3. register_puacb usage example
@@ -397,7 +438,7 @@ typedef int (*register_puacb_t)(int types, pua_cb f, void* param );
         }
 ...
 
-2.6.  add_event
+6. add_event
 
    Field type:
 ...
@@ -405,7 +446,6 @@ typedef int (*add_pua_event_t)(int ev_flag, char* name,
    char* content_type,evs_process_body_t* process_body);
 
 - ev_flag     : an event flag defined as a macro in pua module
-
 - name        : the event name to be used in Event request headers
 - content_type: the default content_type for Publish body for
                 that event (NULL if winfo event)
@@ -414,8 +454,8 @@ typedef int (*add_pua_event_t)(int ev_flag, char* name,
                 (NULL if winfo event)
 ...
 
-   This function allows registering new events to the pua module.
-   Now there are 4 events supported by the pua module: presence,
+   This function allows registering new events to the pua module. Now
+   there are 4 events supported by the pua module: presence,
    presence;winfo, message-summary, dialog;sla. These events are
    registered from within the pua module.
 
@@ -426,7 +466,6 @@ typedef int (evs_process_body_t)(struct publ_info* publ,
 - publ      : the structure received as a parameter in send_publish
               function ( initial body found in publ->body)
 - final_body: the pointer where the result(final_body) should be stored
-
 - ver       : a counter for the sent Publish requests
               (used for winfo events)
 - tuple     : a unique identifier for the resource;
@@ -437,8 +476,7 @@ typedef int (evs_process_body_t)(struct publ_info* publ,
 
    Example 2.4. add_event usage example
 ...
-        if(pua.add_event((PRESENCE_EVENT, "presence", "application/pidf
-+xml",
+        if(pua.add_event((PRESENCE_EVENT, "presence", "application/pidf+xml",
                                 pres_process_body) & 0)
         {
                 LM_ERR("Could not register new event\n");

modules_k/pua/doc/pua_admin.xml

@@ -17,23 +17,26 @@
 	<title>Overview</title>
 	<para>
 		This module offer the functionality of a presence user agent client,
-		sending Subscribe and Publish messages. 
+		sending Subscribe and Publish messages. It's a core part of &kamailio;'s 
+		SIP presence package, implementing SIMPLE and various shared line appearance
+		implementations.
 	</para>
 	<para>
-		 Now it can be used with the following modules: pua_mi and pua_usrloc,
+		 It can be used with the following modules: pua_mi and pua_usrloc,
 		 pua_bla and pua_xmpp.
-		 The pua_mi offer the possibility to publish any kind of information
-		 or subscribing to a resource through fifo. The pua_usrloc module calls
-		 a function exported by pua modules to publish elementary presence
-		 information, such as basic status "open" or "closed", for clients that
-		 do not implement client-to-server presence.
-		 Through pua_bla , BRIDGED LINE APPEARANCE features are added to openser.
-		 The pua_xmpp module represents a gateway between SIP and XMPP, so that 
+		 The <emphasize>pua_mi</emphasize> offer the possibility to publish any kind of information
+		 or subscribing to a resource through the manager interface.
+		 The <emphasize>pua_usrloc</emphasize> module calls a function exported by pua modules to publish
+		 elementary presence information, such as basic status "open" or "closed",
+		 for clients that do not implement client-to-server presence.
+		 Through <emphasize>pua_bla</emphasize> , BRIDGED LINE APPEARANCE features are added to openser.
+		 The <emphasize>pua_xmpp</emphasize> module represents a gateway between SIP and XMPP, so that 
 		 jabber and SIP clients can exchange presence information. 
 	</para>
 	<para>
-		The module use cache to store presentity list and writes to database
-		on timer to be able to recover upon restart.
+		The module use a cache to store the presentity list and writes to database
+		on timer to be able to recover upon restart. The presence is kept in-memory
+		during run-time.
 	</para>
 	</section>
 		<section>
@@ -78,8 +81,8 @@
 		<para>
 		The size of the hash table used for storing Subscribe and 
 		Publish information. 
-        This parameter will be used as the power of 2 when computing table size.
-        </para>
+        	This parameter will be used as the power of 2 when computing table size.
+        	</para>
 		<para>
 		<emphasis>Default value is <quote>9</quote>.	
 		</emphasis>
@@ -169,7 +172,7 @@ modparam("pua", "default_expires", 3600)
 		<title><varname>update_period</varname> (int)</title>
 		<para>
 		The interval at which the information in database and hash table
-		should be updated. In the case of the hash table updating is 
+		should be updated. In the case of the hash table updating means 
 		deleting expired messages.
 		</para>
 		<para>
@@ -209,7 +212,7 @@ modparam("pua", "outbound_proxy", "sip:outbound.example.com")
 		<para>
 		When sending PUBLISHs for Event: dialog, the body contains an
 		XML document according to RFC 4235. This XML document contains a 
-		version attribut to easily detect changes in the dialog state.
+		version attribute to easily detect changes in the dialog state.
 		By setting this parameter, the pua module parses the XML document and
 		sets the version attribute to the proper value. If the receiver of
 		the PUBLISH does not care about the version parameter (e.g. like
@@ -232,7 +235,7 @@ modparam("pua", "dlginfo_increase_version", 1)
 	</section>
 	</section>
 
-<section>
+	<section>
 	<title>Exported Functions</title>
 		
 	<section>
@@ -282,7 +285,7 @@ if(method=="NOTIFY")
 <section>
 	<title>Installation</title>
 	<para>
-	The module requires 1 table in &kamailio; database: pua. The SQL 
+	The module requires one table in the &kamailio; database: pua. The SQL 
 	syntax to create it can be found in presence_xml-create.sql     
 	script in the database directories in the kamailio/scripts folder.
 	You can also find the complete database documentation on the

modules_k/pua/doc/pua_devel.xml

@@ -14,7 +14,7 @@
     <title>&develguide;</title>
     <para>
 		The module provides the following functions that can be used
-		in other &kamailio; modules.
+		by other &kamailio; modules.
    </para>
  		<section>
 				<title>
@@ -22,7 +22,7 @@
 				</title>
 			<para>
 				This function binds the pua modules and fills the structure 
-				with the two exported function.
+				with the two exported functions.
 			</para>
 		<example>
 		<title><function>pua_api</function> structure</title>