Updates to the pua-usrloc documentation

modules_k/pua_usrloc/README

@@ -10,28 +10,27 @@ Anca-Maria Vamanu
 
    Copyright © 2006 voice-system.ro
    Revision History
-   Revision $Revision$ $Date: 2008-08-06 12:08:33 +0200
-                              (Mi, 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. default_domain (str)
-              1.3.2. entity_prefix (str)
+              3.1. default_domain (str)
+              3.2. entity_prefix (str)
 
-        1.4. Exported Functions
+        4. Exported Functions
 
-              1.4.1. pua_set_publish()
+              4.1. pua_set_publish()
 
    List of Examples
 
@@ -41,37 +40,60 @@ 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. default_domain (str)
+        3.2. entity_prefix (str)
+
+   4. Exported Functions
 
-   The pua_usrloc is the connector between usrloc and pua modules.
-   It creates the environment to send PUBLISH requests for user
-   location records, on specific events (e.g., when new record is
-   added in usrloc, a PUBLISH with status open (online) is issued;
-   when expires, it sends closed (offline)).
+        4.1. pua_set_publish()
 
-   Using this module, phones which have no support for presence
-   can be seen as online/offline.
+1. Overview
 
-1.2. Dependencies
+   The pua_usrloc module is the connector between the usrloc and pua
+   modules. It creates the environment to send PUBLISH requests for user
+   location records, on specific events (e.g., when new record is added in
+   usrloc, a PUBLISH with status open (online) is issued; when expires, it
+   sends closed (offline)).
 
-1.2.1. Kamailio Modules
+   Using this module, phones which have no support for presence can be
+   seen as online/offline.
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
 
    The following modules must be loaded before this module:
      * usrloc.
      * pua.
 
-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. default_domain (str)
+   3.1. default_domain (str)
+   3.2. entity_prefix (str)
 
-   The default domain to use when constructing the presentity uri
-   if it is missing from recorded aor.
+3.1. default_domain (str)
+
+   The default domain to use when constructing the presentity URI if it is
+   missing from recorded AOR.
 
    Default value is "NULL".
 
@@ -80,10 +102,10 @@ Chapter 1. Admin Guide
 modparam("pua_usrloc", "default_domain", "kamailio.org")
 ...
 
-1.3.2. entity_prefix (str)
+3.2. entity_prefix (str)
 
-   The prefix when construstructing entity attribute to be added
-   to presence node in xml pidf. (ex: pres:user@domain ).
+   The prefix when construstructing entity attribute to be added to
+   presence node in XML PIDF. (ex: pres:user@domain ).
 
    Default value is "NULL".
 
@@ -92,13 +114,15 @@ modparam("pua_usrloc", "default_domain", "kamailio.org")
 modparam("pua_usrloc", "entity_prefix", "pres")
 ...
 
-1.4. Exported Functions
+4. Exported Functions
+
+   4.1. pua_set_publish()
 
-1.4.1.  pua_set_publish()
+4.1. pua_set_publish()
 
-   The function is used to mark REGISTER requests that have to
-   issue a PUBLISH. The PUBLISH is issued when REGISTER is saved
-   in location table.
+   The function is used to mark REGISTER requests that have to issue a
+   PUBLISH. The PUBLISH is issued when REGISTER is saved in location
+   table.
 
    Example 1.3. pua_set_publish usage
 ...

modules_k/pua_usrloc/doc/pua_usrloc_admin.xml

@@ -16,7 +16,7 @@
 	<section>
 	<title>Overview</title>
 	<para>
-		 The pua_usrloc is the connector between usrloc and pua modules.
+		 The pua_usrloc module is the connector between the usrloc and pua modules.
 		 It creates the environment to send PUBLISH requests for user
 		 location records, on specific events (e.g., when new record is
 		 added in usrloc, a PUBLISH with status open (online) is issued;
@@ -68,7 +68,7 @@
 		<title><varname>default_domain</varname> (str)</title>
 		<para>
 		The default domain to use when constructing the presentity
-		uri if it is missing from recorded aor. 
+		URI if it is missing from recorded AOR. 
 		</para>
 		<para>
 		<emphasis>Default value is <quote>NULL</quote>.	
@@ -87,7 +87,7 @@ modparam("pua_usrloc", "default_domain", "kamailio.org")
 		<title><varname>entity_prefix</varname> (str)</title>
 		<para>
 		The prefix when construstructing entity attribute to be added to
-		presence node in xml pidf.
+		presence node in XML PIDF.
 		(ex: pres:user@domain ).
 		</para>
 		<para>

modules_k/pua_usrloc/pua_usrloc.c

@@ -26,6 +26,14 @@
  *  2006-11-29  initial version (anca)
  */
 
+/*!
+ * \file
+ * \brief SIP-router Presence :: Usrloc module
+ * \ingroup core
+ * Module: \ref core
+ */
+
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -54,7 +62,7 @@ int pua_ul_publish= 0;
 pua_api_t pua;
 str pres_prefix= {0, 0};
 
-/* Structure containing pointers to usrloc functions */
+/*! \brief Structure containing pointers to usrloc functions */
 usrloc_api_t ul;
 
 /** module functions */
@@ -79,21 +87,21 @@ static param_export_t params[]={
 };
 
 struct module_exports exports= {
-	"pua_usrloc",				/* module name */
-	DEFAULT_DLFLAGS,			/* dlopen flags */
-	cmds,						/* exported functions */
-	params,						/* exported parameters */
-	0,							/* exported statistics */
-	0,							/* exported MI functions */
-	0,							/* exported pseudo-variables */
-	0,							/* extra processes */
-	mod_init,					/* module initialization function */
-	0,							/* response handling function */
-	0,							/* destroy function */
-	0							/* per-child init function */
+	"pua_usrloc",				/*!< module name */
+	DEFAULT_DLFLAGS,			/*!< dlopen flags */
+	cmds,						/*!< exported functions */
+	params,						/*!< exported parameters */
+	0,							/*!< exported statistics */
+	0,							/*!< exported MI functions */
+	0,							/*!< exported pseudo-variables */
+	0,							/*!< extra processes */
+	mod_init,					/*!< module initialization function */
+	0,							/*!< response handling function */
+	0,							/*!< destroy function */
+	0							/*!< per-child init function */
 };
 	
-/**
+/*! \brief
  * init module function
  */
 static int mod_init(void)

modules_k/pua_usrloc/pua_usrloc.h

@@ -22,6 +22,14 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*!
+ * \file
+ * \brief SIP-router Presence :: Usrloc module
+ * \ingroup core
+ * Module: \ref core
+ */
+
+
 #ifndef _PUA_UL_
 #define _PUA_UL_
 #include "../pua/pua_bind.h"

modules_k/pua_usrloc/ul_publish.c

@@ -22,6 +22,14 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*!
+ * \file
+ * \brief SIP-router Presence :: Usrloc module
+ * \ingroup core
+ * Module: \ref core
+ */
+
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -116,13 +124,13 @@ str* build_pidf(ucontact_t* c)
 	if(doc==0)
 		return NULL;
 
-    root_node = xmlNewNode(NULL, BAD_CAST "presence");
+    	root_node = xmlNewNode(NULL, BAD_CAST "presence");
 	if(root_node==0)
 		goto error;
     
 	xmlDocSetRootElement(doc, root_node);
 
-    xmlNewProp(root_node, BAD_CAST "xmlns",
+    	xmlNewProp(root_node, BAD_CAST "xmlns",
 			BAD_CAST "urn:ietf:params:xml:ns:pidf");
 	xmlNewProp(root_node, BAD_CAST "xmlns:dm",
 			BAD_CAST "urn:ietf:params:xml:ns:pidf:data-model");
@@ -167,9 +175,9 @@ str* build_pidf(ucontact_t* c)
 
 	LM_DBG("new_body:\n%.*s\n",body->len, body->s);
 
-    /*free the document */
+    	/*free the document */
 	xmlFreeDoc(doc);
-    xmlCleanupParser();
+    	xmlCleanupParser();
 
 	return body;
 
@@ -204,17 +212,21 @@ void ul_publish(ucontact_t* c, int type, void* param)
 		return;
 	}	
 
-	if(type & UL_CONTACT_DELETE)
+	if(type & UL_CONTACT_DELETE) {
 		LM_DBG("\nDELETE type\n");
-	else
-		if(type & UL_CONTACT_INSERT)
+	} else {
+		if(type & UL_CONTACT_INSERT) {
 			LM_DBG("\nINSERT type\n");
-		else
-			if(type & UL_CONTACT_UPDATE)
+		} else {
+			if(type & UL_CONTACT_UPDATE) {
 				LM_DBG("\nUPDATE type\n");
-			else
-				if(type & UL_CONTACT_EXPIRE)
+			} else {
+				if(type & UL_CONTACT_EXPIRE) {
 					LM_DBG("\nEXPIRE type\n");
+				}
+			}
+		}
+	}
 
 	if(type & UL_CONTACT_INSERT)
 	{