Browse code

Documentation and doxygen updates

oej authored on 25/10/2009 19:49:25
Showing 10 changed files
... ...
@@ -31,6 +31,13 @@
31 31
  *  2006-07-23  created by andrei
32 32
  */
33 33
 
34
+/**
35
+ * @file
36
+ * @brief SIP-router core :: resolver related functions
37
+ * @ingroup core
38
+ * Module: @ref core
39
+ */
40
+
34 41
 #ifndef __dns_wrappers_h
35 42
 #define __dns_wrappers_h
36 43
 
... ...
@@ -10,11 +10,6 @@
10 10
  * the Free Software Foundation; either version 2 of the License, or
11 11
  * (at your option) any later version
12 12
  *
13
- * For a license to use the ser software under conditions
14
- * other than those described here, or to purchase support for this
15
- * software, please contact iptel.org by e-mail at the following addresses:
16
- *    info@iptel.org
17
- *
18 13
  * ser is distributed in the hope that it will be useful,
19 14
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 15
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
... ...
@@ -25,6 +20,13 @@
25 20
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
26 21
  */
27 22
 
23
+/**
24
+ * @file
25
+ * @brief SIP-router core :: debug printing
26
+ * @ingroup core
27
+ * Module: @ref core
28
+ */
29
+
28 30
 #ifndef dprint_h
29 31
 #define dprint_h
30 32
 
... ...
@@ -82,7 +84,7 @@
82 84
 #define L_INFO   	2
83 85
 #define L_DBG    	3
84 86
 
85
-/* This is the facility value used to indicate that the caller of the macro
87
+/** @brief This is the facility value used to indicate that the caller of the macro
86 88
  * did not override the facility. Value 0 (the defaul) is LOG_KERN on Linux
87 89
  */
88 90
 #define DEFAULT_FACILITY 0
... ...
@@ -92,15 +94,15 @@
92 94
 	(log_level_info[(level) - (L_ALERT)].syslog_level)
93 95
 
94 96
 
95
-/* my_pid(), process_no are from pt.h but we cannot #include it here
97
+/** @brief my_pid(), process_no are from pt.h but we cannot #include it here
96 98
    because of circular dependencies */
97 99
 extern int process_no;
98 100
 extern int my_pid();
99 101
 
100
-/* non-zero if logging to stderr instead to the syslog */
102
+/** @brief non-zero if logging to stderr instead to the syslog */
101 103
 extern int log_stderr;
102 104
 
103
-/* maps log levels to their string name and corresponding syslog level */
105
+/** @brief maps log levels to their string name and corresponding syslog level */
104 106
 
105 107
 struct log_level_info {
106 108
  	char *name;
... ...
@@ -112,7 +114,7 @@ extern struct log_level_info log_level_info[];
112 114
 extern char *log_name;
113 115
 
114 116
 #ifndef NO_SIG_DEBUG
115
-/* protection against "simultaneous" printing from signal handlers */
117
+/** @brief protection against "simultaneous" printing from signal handlers */
116 118
 extern volatile int dprint_crit; 
117 119
 #endif
118 120
 
... ...
@@ -120,7 +122,7 @@ int str2facility(char *s);
120 122
 int log_facility_fixup(void *handle, str *gname, str *name, void **val);
121 123
 
122 124
 
123
-/*
125
+/** @brief
124 126
  * General logging macros
125 127
  *
126 128
  * 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);
255 257
 #endif /* NO_LOG */
256 258
 
257 259
 
258
-/*
260
+/** @name SimpleLog
259 261
  * Simplier, prefered logging macros for constant log level
260 262
  */
263
+/*@ { */
261 264
 #ifdef __SUNPRO_C
262 265
 #	define ALERT(...)  LOG(L_ALERT,  __VA_ARGS__)
263 266
 #	define BUG(...)    LOG(L_BUG,   __VA_ARGS__)
... ...
@@ -272,6 +275,7 @@ int log_facility_fixup(void *handle, str *gname, str *name, void **val);
272 275
 #	else
273 276
 #		define DBG(...)    LOG(L_DBG, __VA_ARGS__)
274 277
 #	endif		
278
+/*@ } */
275 279
 
276 280
 /* obsolete, do not use */
277 281
 #	define DEBUG(...) DBG(__VA_ARGS__)
... ...
@@ -10,11 +10,6 @@
10 10
  * the Free Software Foundation; either version 2 of the License, or
11 11
  * (at your option) any later version
12 12
  *
13
- * For a license to use the ser software under conditions
14
- * other than those described here, or to purchase support for this
15
- * software, please contact iptel.org by e-mail at the following addresses:
16
- *    info@iptel.org
17
- *
18 13
  * ser is distributed in the hope that it will be useful,
19 14
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 15
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
... ...
@@ -25,6 +20,13 @@
25 20
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
26 21
  */
27 22
 
23
+/*!
24
+ * \file
25
+ * \brief SIP-router core :: Destination set handling
26
+ * \ingroup core
27
+ * Module: \ref core
28
+ */
29
+
28 30
 #ifndef _DSET_H
29 31
 #define _DSET_H
30 32
 
... ...
@@ -36,20 +38,18 @@ struct sip_msg;
36 38
 
37 39
 extern unsigned int nr_branches;
38 40
 
39
-
40
-
41
-/*
41
+/*! \brief
42 42
  * Add a new branch to current transaction 
43 43
  */
44 44
 int append_branch(struct sip_msg* msg, str* uri, str* dst_uri, str* path,
45 45
 					 qvalue_t q, unsigned int flags,
46 46
 					 struct socket_info* force_socket);
47 47
 
48
-/* kamailio compatible version */
48
+/*! \brief kamailio compatible version */
49 49
 #define km_append_branch(msg, uri, dst_uri, path, q, flags, force_socket) \
50 50
 	append_branch(msg, uri, dst_uri, path, q, flags, force_socket)
51 51
 
52
-/** ser compatible append_branch version.
52
+/*! \brief ser compatible append_branch version.
53 53
  *  append_branch version compatible with ser: no path or branch flags support
54 54
  *  and no str parameters.
55 55
  */
... ...
@@ -69,18 +69,18 @@ static inline int ser_append_branch(struct sip_msg* msg,
69 69
 
70 70
 
71 71
 
72
-/*
72
+/*! \brief
73 73
  * Iterate through the list of transaction branches 
74 74
  */
75 75
 void init_branch_iterator(void);
76 76
 
77
-/* 
77
+/*! \brief
78 78
  * Return branch iterator position 
79 79
  */
80 80
 int get_branch_iterator(void);
81 81
 
82 82
 
83
-/** Get the next branch in the current transaction.
83
+/*! \brief Get the next branch in the current transaction.
84 84
  * @return pointer to the uri of the next branch (which the length written in
85 85
  *  *len) or 0 if there are no more branches.
86 86
  */
... ...
@@ -94,26 +94,26 @@ char* get_branch( unsigned int i, int* len, qvalue_t* q, str* dst_uri,
94 94
 
95 95
 
96 96
 
97
-/*
97
+/*! \brief
98 98
  * Empty the array of branches
99 99
  */
100 100
 void clear_branches(void);
101 101
 
102 102
 
103
-/*
103
+/*! \brief
104 104
  * Create a Contact header field from the
105 105
  * list of current branches
106 106
  */
107 107
 char* print_dset(struct sip_msg* msg, int* len);
108 108
 
109 109
 
110
-/* 
110
+/*! \brief
111 111
  * Set the q value of the Request-URI
112 112
  */
113 113
 void set_ruri_q(qvalue_t q);
114 114
 
115 115
 
116
-/* 
116
+/*! \brief
117 117
  * Get the q value of the Request-URI
118 118
  */
119 119
 qvalue_t get_ruri_q(void);
... ...
@@ -121,7 +121,7 @@ qvalue_t get_ruri_q(void);
121 121
 int get_request_uri(struct sip_msg* _m, str* _u);
122 122
 int rewrite_uri(struct sip_msg* _m, str* _s);
123 123
 
124
-/**
124
+/*! \brief
125 125
  * Set a per-branch flag to 1.
126 126
  *
127 127
  * 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);
131 131
  */
132 132
 int setbflag(unsigned int branch, flag_t flag);
133 133
 
134
-/**
134
+/*! \brief
135 135
  * Reset a per-branch flag value to 0.
136 136
  *
137 137
  * This function resets the value of one particular branch flag to 0.
... ...
@@ -141,7 +141,7 @@ int setbflag(unsigned int branch, flag_t flag);
141 141
  */
142 142
 int resetbflag(unsigned int branch, flag_t flag);
143 143
 
144
-/**
144
+/*! \brief
145 145
  * Determine if a branch flag is set.
146 146
  *
147 147
  * This function tests the value of one particular per-branch flag.
... ...
@@ -151,7 +151,7 @@ int resetbflag(unsigned int branch, flag_t flag);
151 151
  */
152 152
 int isbflagset(unsigned int branch, flag_t flag);
153 153
 
154
-/**
154
+/*! \brief
155 155
  * Get the value of all branch flags for a branch
156 156
  *
157 157
  * This function returns the value of all branch flags
... ...
@@ -162,7 +162,7 @@ int isbflagset(unsigned int branch, flag_t flag);
162 162
  */
163 163
 int getbflagsval(unsigned int branch, flag_t* res);
164 164
 
165
-/**
165
+/*! \brief
166 166
  * Set the value of all branch flags at once for a given branch.
167 167
  *
168 168
  * This function sets the value of all branch flags for a given
... ...
@@ -1,8 +1,6 @@
1 1
 /*
2 2
  * $Id$
3 3
  *
4
- * resolver related functions
5
- *
6 4
  * Copyright (C) 2006 iptelorg GmbH
7 5
  *
8 6
  * This file is part of ser, a free SIP server.
... ...
@@ -12,11 +10,6 @@
12 10
  * the Free Software Foundation; either version 2 of the License, or
13 11
  * (at your option) any later version
14 12
  *
15
- * For a license to use the ser software under conditions
16
- * other than those described here, or to purchase support for this
17
- * software, please contact iptel.org by e-mail at the following addresses:
18
- *    info@iptel.org
19
- *
20 13
  * ser is distributed in the hope that it will be useful,
21 14
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
22 15
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
... ...
@@ -26,6 +19,14 @@
26 19
  * along with this program; if not, write to the Free Software
27 20
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
28 21
  */
22
+
23
+/**
24
+ * @file
25
+ * @brief SIP-router core :: Destination blacklists
26
+ * @ingroup core
27
+ * Module: @ref core
28
+ */
29
+
29 30
 /* History:
30 31
  * --------
31 32
  *  2006-07-29  created by andrei
... ...
@@ -40,25 +41,28 @@
40 41
 #include "timer_ticks.h"
41 42
 #include "cfg_core.h"
42 43
 
43
-#define DEFAULT_BLST_TIMEOUT		60  /* 1 min. */
44
-#define DEFAULT_BLST_MAX_MEM		250 /* 250 KB */
44
+#define DEFAULT_BLST_TIMEOUT		60  /**< 1 min. */
45
+#define DEFAULT_BLST_MAX_MEM		250 /**< 250 KB */
46
+
47
+/** @name flags: */
48
+/*@{ */
45 49
 
46
-/* flags: */
47
-#define BLST_IS_IPV6		1		/* set if the address is ipv6 */
48
-#define BLST_ERR_SEND		(1<<1)	/* set if  send is denied/failed */
49
-#define BLST_ERR_CONNECT	(1<<2)	/* set if connect failed (tcp/tls) */
50
-#define BLST_ICMP_RCVD		(1<<3)	/* set if icmp error */
51
-#define BLST_ERR_TIMEOUT	(1<<4)	/* set if sip timeout */
52
-#define BLST_503			(1<<5)	/* set for 503 replies */
53
-#define BLST_ADM_PROHIBITED	(1<<6)	/* administratively prohibited */
54
-#define BLST_PERMANENT		(1<<7)  /* never deleted, never expires */
50
+#define BLST_IS_IPV6		1		/**< set if the address is ipv6 */
51
+#define BLST_ERR_SEND		(1<<1)	/**< set if  send is denied/failed */
52
+#define BLST_ERR_CONNECT	(1<<2)	/**< set if connect failed (tcp/tls) */
53
+#define BLST_ICMP_RCVD		(1<<3)	/**< set if icmp error */
54
+#define BLST_ERR_TIMEOUT	(1<<4)	/**< set if sip timeout */
55
+#define BLST_503			(1<<5)	/**< set for 503 replies */
56
+#define BLST_ADM_PROHIBITED	(1<<6)	/**< administratively prohibited */
57
+#define BLST_PERMANENT		(1<<7)  /**< never deleted, never expires */
58
+/*@} */
55 59
 
56 60
 /* uncomment the define above to enable blacklist callbacks support */
57 61
 /*#define DST_BLACKLIST_HOOKS*/
58 62
 
59
-#define DST_BLACKLIST_CONTINUE 0 /* add: do nothing/ignore, search: ignore */
60
-#define DST_BLACKLIST_ACCEPT 1   /* add: force accept, search: force match */
61
-#define DST_BLACKLIST_DENY  -1   /* add: deny, search: force no match */
63
+#define DST_BLACKLIST_CONTINUE 0 /**< add: do nothing/ignore, search: ignore */
64
+#define DST_BLACKLIST_ACCEPT 1   /**< add: force accept, search: force match */
65
+#define DST_BLACKLIST_DENY  -1   /**< add: deny, search: force no match */
62 66
 
63 67
 #define DST_BLACKLIST_ADD_CB 1
64 68
 #define DST_BLACKLIST_SEARCH_CB 2
... ...
@@ -85,22 +89,22 @@ int init_dst_blacklist_stats(int iproc_num);
85 89
 void destroy_dst_blacklist();
86 90
 
87 91
 
88
-/* like dst_blacklist_add, but the timeout can be also set */
92
+/** @brief like dst_blacklist_add, but the timeout can be also set */
89 93
 int dst_blacklist_add_to(unsigned char err_flags, struct dest_info* si,
90 94
 						struct sip_msg* msg, ticks_t timeout);
91
-/* like above, but using a differnt way of passing the target */
95
+/** @brief like above, but using a differnt way of passing the target */
92 96
 int dst_blacklist_su_to(unsigned char err_flags, unsigned char proto,
93 97
 							union sockaddr_union* dst,
94 98
 							struct sip_msg* msg, ticks_t timeout);
95 99
 
96
-/** adds a dst to the blacklist with default timeout.
100
+/** @brief adds a dst to the blacklist with default timeout.
97 101
  * @see dst_blacklist_add_to for more details.
98 102
  */
99 103
 #define dst_blacklist_add(err_flags, si, msg) \
100 104
 	dst_blacklist_add_to((err_flags), (si), (msg), \
101 105
 		S_TO_TICKS(cfg_get(core, core_cfg, blst_timeout)))
102 106
 
103
-/** adds a dst to the blacklist with default timeout.
107
+/** @brief adds a dst to the blacklist with default timeout.
104 108
  * @see dst_blacklist_su_to for more details.
105 109
  */
106 110
 #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,
108 112
 		S_TO_TICKS(cfg_get(core, core_cfg, blst_timeout)))
109 113
 
110 114
 int dst_is_blacklisted(struct dest_info* si, struct sip_msg* msg);
111
-/* delete an entry from the blacklist */
115
+
116
+/** @brief  delete an entry from the blacklist */
112 117
 int dst_blacklist_del(struct dest_info* si, struct sip_msg* msg);
113 118
 
114
-/* deletes all the entries from the blacklist except the permanent ones
119
+/** @brief deletes all the entries from the blacklist except the permanent ones
115 120
  * (which are marked with BLST_PERMANENT)
116 121
  */
117 122
 void dst_blst_flush(void);
118 123
 
119 124
 int use_dst_blacklist_fixup(void *handle, str *gname, str *name, void **val);
120
-/* KByte to Byte conversion */
125
+
126
+/** @brief KByte to Byte conversion */
121 127
 int blst_max_mem_fixup(void *handle, str *gname, str *name, void **val);
122 128
 
123 129
 #endif
... ...
@@ -15,27 +15,25 @@
15 15
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18
-/*
18
+
19
+/** @file
19 20
  *  endianness compile and runtime  tests
20 21
  * 
21 22
  * History:
22 23
  * --------
23 24
  *  2008-06-13  created by andrei
24
- */
25
-
26
-/*
25
+ *
27 26
  * Defines:
28
- *    __IS_LITTLE_ENDIAN if the system is little endian and
29
- *    __IS_BIG_ENDIAN    if it's big endian
27
+ *  -  __IS_LITTLE_ENDIAN if the system is little endian and
28
+ *  -  __IS_BIG_ENDIAN    if it's big endian
30 29
  * Function/macros:
31
- *     is_big_endian()  - runtime test for big endian
32
- *     is_little_endian() - runtime test for little endian
33
- *     endianness_sanity_check() - returns 0 if the compile time
30
+ *  -   is_big_endian()  - runtime test for big endian
31
+ *  -   is_little_endian() - runtime test for little endian
32
+ *  -   endianness_sanity_check() - returns 0 if the compile time
34 33
  *                                  detected endianness corresponds to
35 34
  *                                  the runtime detected one and -1 on 
36 35
  *                                  error (recommended action: bail out)
37
- */
38
-/*
36
+ *
39 37
  * Implementation notes:
40 38
  * Endian macro names/tests for different OSes:
41 39
  * linux:  __BYTE_ORDER == __LITTLE_ENDIAN | __BIG_ENDIAN
... ...
@@ -10,11 +10,6 @@
10 10
  * the Free Software Foundation; either version 2 of the License, or
11 11
  * (at your option) any later version
12 12
  *
13
- * For a license to use the ser software under conditions
14
- * other than those described here, or to purchase support for this
15
- * software, please contact iptel.org by e-mail at the following addresses:
16
- *    info@iptel.org
17
- *
18 13
  * ser is distributed in the hope that it will be useful,
19 14
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 15
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
... ...
@@ -16,11 +16,6 @@
16 16
  * the Free Software Foundation; either version 2 of the License, or
17 17
  * (at your option) any later version
18 18
  *
19
- * For a license to use the ser software under conditions
20
- * other than those described here, or to purchase support for this
21
- * software, please contact iptel.org by e-mail at the following addresses:
22
- *    info@iptel.org
23
- *
24 19
  * ser is distributed in the hope that it will be useful,
25 20
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
26 21
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
... ...
@@ -46,8 +41,9 @@
46 41
 
47 42
 
48 43
 
49
-/* used to delete attached via lumps from msg; msg can
50
-   be either an original pkg msg, whose Via lump I want
44
+/** @brief used to delete attached via lumps from msg;
45
+
46
+   msg can be either an original pkg msg, whose Via lump I want
51 47
    to delete before generating next branch, or a shmem-stored
52 48
    message processed during on_reply -- then I want to
53 49
    delete the Via lump for the same reason
... ...
@@ -1,4 +1,3 @@
1
-
2 1
 Presence User Agent Module
3 2
 
4 3
 Anca-Maria Vamanu
... ...
@@ -11,45 +10,44 @@ Anca-Maria Vamanu
11 10
 
12 11
    Copyright � 2006 voice-system.ro
13 12
    Revision History
14
-   Revision $Revision$ $Date: 2008-08-06 12:08:33 +0200
15
-   (Wed, 06 Aug 2008) $
16
-     _________________________________________________________
13
+   Revision $Revision$ $Date$
14
+     __________________________________________________________________
17 15
 
18 16
    Table of Contents
19 17
 
20 18
    1. Admin Guide
21 19
 
22
-        1.1. Overview
23
-        1.2. Dependencies
20
+        1. Overview
21
+        2. Dependencies
24 22
 
25
-              1.2.1. Kamailio Modules
26
-              1.2.2. External Libraries or Applications
23
+              2.1. Kamailio Modules
24
+              2.2. External Libraries or Applications
27 25
 
28
-        1.3. Exported Parameters
26
+        3. Exported Parameters
29 27
 
30
-              1.3.1. hash_size (int)
31
-              1.3.2. db_url (str)
32
-              1.3.3. db_table (str)
33
-              1.3.4. min_expires (int)
34
-              1.3.5. default_expires (int)
35
-              1.3.6. update_period (int)
36
-              1.3.7. outbound_proxy (str)
37
-              1.3.8. dlginfo_increase_version (int)
28
+              3.1. hash_size (int)
29
+              3.2. db_url (str)
30
+              3.3. db_table (str)
31
+              3.4. min_expires (int)
32
+              3.5. default_expires (int)
33
+              3.6. update_period (int)
34
+              3.7. outbound_proxy (str)
35
+              3.8. dlginfo_increase_version (int)
38 36
 
39
-        1.4. Exported Functions
37
+        4. Exported Functions
40 38
 
41
-              1.4.1. pua_update_contact() 
39
+              4.1. pua_update_contact()
42 40
 
43
-        1.5. Installation
41
+        5. Installation
44 42
 
45 43
    2. Developer Guide
46 44
 
47
-        2.1. bind_pua(pua_api_t* api) 
48
-        2.2. send_publish 
49
-        2.3. send_subscribe 
50
-        2.4. is_dialog 
51
-        2.5. register_puacb 
52
-        2.6. add_event 
45
+        1. bind_pua(pua_api_t* api)
46
+        2. send_publish
47
+        3. send_subscribe
48
+        4. is_dialog
49
+        5. register_puacb
50
+        6. add_event
53 51
 
54 52
    List of Examples
55 53
 
... ...
@@ -69,156 +67,195 @@ Anca-Maria Vamanu
69 67
 
70 68
 Chapter 1. Admin Guide
71 69
 
72
-1.1. Overview
70
+   Table of Contents
71
+
72
+   1. Overview
73
+   2. Dependencies
74
+
75
+        2.1. Kamailio Modules
76
+        2.2. External Libraries or Applications
77
+
78
+   3. Exported Parameters
79
+
80
+        3.1. hash_size (int)
81
+        3.2. db_url (str)
82
+        3.3. db_table (str)
83
+        3.4. min_expires (int)
84
+        3.5. default_expires (int)
85
+        3.6. update_period (int)
86
+        3.7. outbound_proxy (str)
87
+        3.8. dlginfo_increase_version (int)
88
+
89
+   4. Exported Functions
90
+
91
+        4.1. pua_update_contact()
92
+
93
+   5. Installation
94
+
95
+1. Overview
96
+
97
+   This module offer the functionality of a presence user agent client,
98
+   sending Subscribe and Publish messages. It's a core part of Kamailio's
99
+   SIP presence package, implementing SIMPLE and various shared line
100
+   appearance implementations.
73 101
 
74
-   This module offer the functionality of a presence user agent
75
-   client, sending Subscribe and Publish messages.
102
+   It can be used with the following modules: pua_mi and pua_usrloc,
103
+   pua_bla and pua_xmpp. The <emphasize>pua_mi</emphasize> offer the
104
+   possibility to publish any kind of information or subscribing to a
105
+   resource through the manager interface. The
106
+   <emphasize>pua_usrloc</emphasize> module calls a function exported by
107
+   pua modules to publish elementary presence information, such as basic
108
+   status "open" or "closed", for clients that do not implement
109
+   client-to-server presence. Through <emphasize>pua_bla</emphasize> ,
110
+   BRIDGED LINE APPEARANCE features are added to openser. The
111
+   <emphasize>pua_xmpp</emphasize> module represents a gateway between SIP
112
+   and XMPP, so that jabber and SIP clients can exchange presence
113
+   information.
76 114
 
77
-   Now it can be used with the following modules: pua_mi and
78
-   pua_usrloc, pua_bla and pua_xmpp. The pua_mi offer the
79
-   possibility to publish any kind of information or subscribing
80
-   to a resource through fifo. The pua_usrloc module calls a
81
-   function exported by pua modules to publish elementary
82
-   presence information, such as basic status "open" or "closed",
83
-   for clients that do not implement client-to-server presence.
84
-   Through pua_bla , BRIDGED LINE APPEARANCE features are added
85
-   to openser. The pua_xmpp module represents a gateway between
86
-   SIP and XMPP, so that jabber and SIP clients can exchange
87
-   presence information.
115
+   The module use a cache to store the presentity list and writes to
116
+   database on timer to be able to recover upon restart. The presence is
117
+   kept in-memory during run-time.
88 118
 
89
-   The module use cache to store presentity list and writes to
90
-   database on timer to be able to recover upon restart.
119
+2. Dependencies
91 120
 
92
-1.2. Dependencies
121
+   2.1. Kamailio Modules
122
+   2.2. External Libraries or Applications
93 123
 
94
-1.2.1. Kamailio Modules
124
+2.1. Kamailio Modules
95 125
 
96 126
    The following modules must be loaded before this module:
97 127
      * a database modules.
98 128
      * tm.
99 129
 
100
-1.2.2. External Libraries or Applications
130
+2.2. External Libraries or Applications
101 131
 
102
-   The following libraries or applications must be installed
103
-   before running Kamailio with this module loaded:
132
+   The following libraries or applications must be installed before
133
+   running Kamailio with this module loaded:
104 134
      * libxml.
105 135
 
106
-1.3. Exported Parameters
136
+3. Exported Parameters
107 137
 
108
-1.3.1. hash_size (int)
138
+   3.1. hash_size (int)
139
+   3.2. db_url (str)
140
+   3.3. db_table (str)
141
+   3.4. min_expires (int)
142
+   3.5. default_expires (int)
143
+   3.6. update_period (int)
144
+   3.7. outbound_proxy (str)
145
+   3.8. dlginfo_increase_version (int)
109 146
 
110
-   The size of the hash table used for storing Subscribe and
111
-   Publish information. This parameter will be used as the power
112
-   of 2 when computing table size.
147
+3.1. hash_size (int)
113 148
 
114
-   Default value is "9". 
149
+   The size of the hash table used for storing Subscribe and Publish
150
+   information. This parameter will be used as the power of 2 when
151
+   computing table size.
152
+
153
+   Default value is "9".
115 154
 
116 155
    Example 1.1. Set hash_size parameter
117 156
 ...
118 157
 modparam("pua", "hash_size", 11)
119 158
 ...
120 159
 
121
-1.3.2. db_url (str)
160
+3.2. db_url (str)
122 161
 
123 162
    Database url.
124 163
 
125
-   Default value is
126
-   ">mysql://openser:openserrw@localhost/openser". 
164
+   Default value is ">mysql://openser:openserrw@localhost/openser".
127 165
 
128 166
    Example 1.2. Set db_url parameter
129 167
 ...
130 168
 modparam("pua", "db_url" "dbdriver://username:password@dbhost/dbname")
131 169
 ...
132 170
 
133
-1.3.3. db_table (str)
171
+3.3. db_table (str)
134 172
 
135 173
    The name of the database table.
136 174
 
137
-   Default value is "pua". 
175
+   Default value is "pua".
138 176
 
139 177
    Example 1.3. Set db_table parameter
140 178
 ...
141 179
 modparam("pua", "db_table", "pua")
142 180
 ...
143 181
 
144
-1.3.4. min_expires (int)
182
+3.4. min_expires (int)
145 183
 
146 184
    The inferior expires limit for both Publish and Subscribe.
147 185
 
148
-   Default value is "0". 
186
+   Default value is "0".
149 187
 
150 188
    Example 1.4. Set min_expires parameter
151 189
 ...
152 190
 modparam("pua", "min_expires", 0)
153 191
 ...
154 192
 
155
-1.3.5. default_expires (int)
193
+3.5. default_expires (int)
156 194
 
157 195
    The default expires value used in case this information is not
158 196
    provisioned.
159 197
 
160
-   Default value is "3600". 
198
+   Default value is "3600".
161 199
 
162 200
    Example 1.5. Set default_expires parameter
163 201
 ...
164 202
 modparam("pua", "default_expires", 3600)
165 203
 ...
166 204
 
167
-1.3.6. update_period (int)
205
+3.6. update_period (int)
168 206
 
169
-   The interval at which the information in database and hash
170
-   table should be updated. In the case of the hash table
171
-   updating is deleting expired messages.
207
+   The interval at which the information in database and hash table should
208
+   be updated. In the case of the hash table updating means deleting
209
+   expired messages.
172 210
 
173
-   Default value is "100". 
211
+   Default value is "100".
174 212
 
175 213
    Example 1.6. Set update_period parameter
176 214
 ...
177 215
 modparam("pua", "update_period", 100)
178 216
 ...
179 217
 
180
-1.3.7. outbound_proxy (str)
218
+3.7. outbound_proxy (str)
181 219
 
182
-   SIP URI of outbound proxy to be used when sending PUBLISH
183
-   requests.
220
+   SIP URI of outbound proxy to be used when sending PUBLISH requests.
184 221
 
185
-   By default, no outbound proxy has been defined. 
222
+   By default, no outbound proxy has been defined.
186 223
 
187 224
    Example 1.7. Set outbound_proxy parameter
188 225
 ...
189 226
 modparam("pua", "outbound_proxy", "sip:outbound.example.com")
190 227
 ...
191 228
 
192
-1.3.8. dlginfo_increase_version (int)
229
+3.8. dlginfo_increase_version (int)
193 230
 
194
-   When sending PUBLISHs for Event: dialog, the body contains an
195
-   XML document according to RFC 4235. This XML document contains
196
-   a version attribut to easily detect changes in the dialog
197
-   state. By setting this parameter, the pua module parses the
198
-   XML document and sets the version attribute to the proper
199
-   value. If the receiver of the PUBLISH does not care about the
200
-   version parameter (e.g. like Kamailio presence_dialoginfo
201
-   module) it makes no sense to waste CPU resources for parsing
202
-   the XML body and the parameter should be set to 0.
231
+   When sending PUBLISHs for Event: dialog, the body contains an XML
232
+   document according to RFC 4235. This XML document contains a version
233
+   attribute to easily detect changes in the dialog state. By setting this
234
+   parameter, the pua module parses the XML document and sets the version
235
+   attribute to the proper value. If the receiver of the PUBLISH does not
236
+   care about the version parameter (e.g. like Kamailio
237
+   presence_dialoginfo module) it makes no sense to waste CPU resources
238
+   for parsing the XML body and the parameter should be set to 0.
203 239
 
204
-   Default value is "0". 
240
+   Default value is "0".
205 241
 
206 242
    Example 1.8. Set dlginfo_increase_version parameter
207 243
 ...
208 244
 modparam("pua", "dlginfo_increase_version", 1)
209 245
 ...
210 246
 
211
-1.4. Exported Functions
247
+4. Exported Functions
248
+
249
+   4.1. pua_update_contact()
212 250
 
213
-1.4.1.  pua_update_contact()
251
+4.1. pua_update_contact()
214 252
 
215
-   The remote target can be updated by the Contact of a
216
-   subsequent in dialog request. In the PUA watcher case (sending
217
-   a SUBSCRIBE messages), this means that the remote target for
218
-   the following Subscribe messages can be updated at any time by
219
-   the contact of a Notify message. If this function is called on
220
-   request route on receiving a Notify message, it will try to
221
-   update the stored remote target.
253
+   The remote target can be updated by the Contact of a subsequent in
254
+   dialog request. In the PUA watcher case (sending a SUBSCRIBE messages),
255
+   this means that the remote target for the following Subscribe messages
256
+   can be updated at any time by the contact of a Notify message. If this
257
+   function is called on request route on receiving a Notify message, it
258
+   will try to update the stored remote target.
222 259
 
223 260
    This function can be used from REQUEST_ROUTE.
224 261
 
... ...
@@ -232,24 +269,32 @@ if(method=="NOTIFY")
232 269
     pua_update_contact();
233 270
 ...
234 271
 
235
-1.5. Installation
272
+5. Installation
236 273
 
237
-   The module requires 1 table in Kamailio database: pua. The SQL
238
-   syntax to create it can be found in presence_xml-create.sql
239
-   script in the database directories in the kamailio/scripts
240
-   folder. You can also find the complete database documentation
241
-   on the project webpage,
274
+   The module requires one table in the Kamailio database: pua. The SQL
275
+   syntax to create it can be found in presence_xml-create.sql script in
276
+   the database directories in the kamailio/scripts folder. You can also
277
+   find the complete database documentation on the project webpage,
242 278
    http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
243 279
 
244 280
 Chapter 2. Developer Guide
245 281
 
246
-   The module provides the following functions that can be used
247
-   in other Kamailio modules.
282
+   Table of Contents
283
+
284
+   1. bind_pua(pua_api_t* api)
285
+   2. send_publish
286
+   3. send_subscribe
287
+   4. is_dialog
288
+   5. register_puacb
289
+   6. add_event
290
+
291
+   The module provides the following functions that can be used by other
292
+   Kamailio modules.
248 293
 
249
-2.1.  bind_pua(pua_api_t* api)
294
+1. bind_pua(pua_api_t* api)
250 295
 
251
-   This function binds the pua modules and fills the structure
252
-   with the two exported function.
296
+   This function binds the pua modules and fills the structure with the
297
+   two exported functions.
253 298
 
254 299
    Example 2.1. pua_api structure
255 300
 ...
... ...
@@ -262,15 +307,15 @@ typedef struct pua_api {
262 307
 } pua_api_t;
263 308
 ...
264 309
 
265
-2.2.  send_publish
310
+2. send_publish
266 311
 
267 312
    Field type:
268 313
 ...
269 314
 typedef int (*send_publish_t)(publ_info_t* publ);
270 315
 ...
271 316
 
272
-   This function receives as a parameter a structure with Publish
273
-   required information and sends a Publish message.
317
+   This function receives as a parameter a structure with Publish required
318
+   information and sends a Publish message.
274 319
 
275 320
    The structure received as a parameter:
276 321
 ...
... ...
@@ -281,13 +326,11 @@ typedef struct publ_info
281 326
   str* pres_uri;      /*  the presentity uri */
282 327
   str* body;          /*  the body of the Publish message;
283 328
                           can be NULL in case of an update expires*/
284
-
285 329
   int  expires;       /*  the expires value that will be used in
286 330
                           Publish Expires header*/
287 331
   int flag;           /*  it can be : INSERT_TYPE or UPDATE_TYPE
288 332
                           if missing it will be established according
289 333
                           to the result of the search in hash table*/
290
-
291 334
   int source_flag;    /*  flag identifying the resource ;
292 335
                           supported values: UL_PUBLISH, MI_PUBLISH,
293 336
                           BLA_PUBLISH, XMPP_PUBLISH*/
... ...
@@ -305,7 +348,6 @@ typedef struct publ_info
305 348
                           the reply for the sent request */
306 349
   void* cbparam;      /*  extra parameter for tha callback function */
307 350
 
308
-
309 351
 }publ_info_t;
310 352
 ...
311 353
 
... ...
@@ -314,15 +356,15 @@ typedef struct publ_info
314 356
 typedef int (publrpl_cb_t)(struct sip_msg* reply, void*  extra_param);
315 357
 ...
316 358
 
317
-2.3.  send_subscribe
359
+3. send_subscribe
318 360
 
319 361
    Field type:
320 362
 ...
321 363
 typedef int (*send_subscribe_t)(subs_info_t* subs);
322 364
 ...
323 365
 
324
-   This function receives as a parameter a structure with
325
-   Subscribe required information and sends a Subscribe message.
366
+   This function receives as a parameter a structure with Subscribe
367
+   required information and sends a Subscribe message.
326 368
 
327 369
    The structure received as a parameter:
328 370
 ...
... ...
@@ -353,15 +395,15 @@ typedef struct subs_info
353 395
 }subs_info_t;
354 396
 ...
355 397
 
356
-2.4.  is_dialog
398
+4. is_dialog
357 399
 
358 400
    Field type:
359 401
 ...
360 402
 typedef int  (*query_dialog_t)(ua_pres_t* presentity);
361 403
 ...
362 404
 
363
-   This function checks is the parameter corresponds to a stored
364
-   Subscribe initiated dialog.
405
+   This function checks is the parameter corresponds to a stored Subscribe
406
+   initiated dialog.
365 407
 
366 408
    Example 2.2. pua_is_dialog usage example
367 409
 ...
... ...
@@ -372,20 +414,19 @@ typedef int  (*query_dialog_t)(ua_pres_t* presentity);
372 414
         }
373 415
 ...
374 416
 
375
-2.5.  register_puacb
417
+5. register_puacb
376 418
 
377 419
    Field type:
378 420
 ...
379 421
 typedef int (*register_puacb_t)(int types, pua_cb f, void* param );
380 422
 ...
381 423
 
382
-   This function registers a callback to be called on receiving
383
-   the reply message for a sent Subscribe request. The type
384
-   parameter should be set the same as the source_flag for that
385
-   request. The function registered as callback for pua should be
386
-   of type pua_cb , which is: typedef void (pua_cb)(ua_pres_t*
387
-   hentity, struct msg_start * fl); The parameters are the dialog
388
-   structure for that request and the first line of the reply
424
+   This function registers a callback to be called on receiving the reply
425
+   message for a sent Subscribe request. The type parameter should be set
426
+   the same as the source_flag for that request. The function registered
427
+   as callback for pua should be of type pua_cb , which is: typedef void
428
+   (pua_cb)(ua_pres_t* hentity, struct msg_start * fl); The parameters are
429
+   the dialog structure for that request and the first line of the reply
389 430
    message.
390 431
 
391 432
    Example 2.3. register_puacb usage example
... ...
@@ -397,7 +438,7 @@ typedef int (*register_puacb_t)(int types, pua_cb f, void* param );
397 438
         }
398 439
 ...
399 440
 
400
-2.6.  add_event
441
+6. add_event
401 442
 
402 443
    Field type:
403 444
 ...
... ...
@@ -405,7 +446,6 @@ typedef int (*add_pua_event_t)(int ev_flag, char* name,
405 446
    char* content_type,evs_process_body_t* process_body);
406 447
 
407 448
 - ev_flag     : an event flag defined as a macro in pua module
408
-
409 449
 - name        : the event name to be used in Event request headers
410 450
 - content_type: the default content_type for Publish body for
411 451
                 that event (NULL if winfo event)
... ...
@@ -414,8 +454,8 @@ typedef int (*add_pua_event_t)(int ev_flag, char* name,
414 454
                 (NULL if winfo event)
415 455
 ...
416 456
 
417
-   This function allows registering new events to the pua module.
418
-   Now there are 4 events supported by the pua module: presence,
457
+   This function allows registering new events to the pua module. Now
458
+   there are 4 events supported by the pua module: presence,
419 459
    presence;winfo, message-summary, dialog;sla. These events are
420 460
    registered from within the pua module.
421 461
 
... ...
@@ -426,7 +466,6 @@ typedef int (evs_process_body_t)(struct publ_info* publ,
426 466
 - publ      : the structure received as a parameter in send_publish
427 467
               function ( initial body found in publ->body)
428 468
 - final_body: the pointer where the result(final_body) should be stored
429
-
430 469
 - ver       : a counter for the sent Publish requests
431 470
               (used for winfo events)
432 471
 - tuple     : a unique identifier for the resource;
... ...
@@ -437,8 +476,7 @@ typedef int (evs_process_body_t)(struct publ_info* publ,
437 476
 
438 477
    Example 2.4. add_event usage example
439 478
 ...
440
-        if(pua.add_event((PRESENCE_EVENT, "presence", "application/pidf
441
-+xml",
479
+        if(pua.add_event((PRESENCE_EVENT, "presence", "application/pidf+xml",
442 480
                                 pres_process_body) & 0)
443 481
         {
444 482
                 LM_ERR("Could not register new event\n");
... ...
@@ -17,23 +17,26 @@
17 17
 	<title>Overview</title>
18 18
 	<para>
19 19
 		This module offer the functionality of a presence user agent client,
20
-		sending Subscribe and Publish messages. 
20
+		sending Subscribe and Publish messages. It's a core part of &kamailio;'s 
21
+		SIP presence package, implementing SIMPLE and various shared line appearance
22
+		implementations.
21 23
 	</para>
22 24
 	<para>
23
-		 Now it can be used with the following modules: pua_mi and pua_usrloc,
25
+		 It can be used with the following modules: pua_mi and pua_usrloc,
24 26
 		 pua_bla and pua_xmpp.
25
-		 The pua_mi offer the possibility to publish any kind of information
26
-		 or subscribing to a resource through fifo. The pua_usrloc module calls
27
-		 a function exported by pua modules to publish elementary presence
28
-		 information, such as basic status "open" or "closed", for clients that
29
-		 do not implement client-to-server presence.
30
-		 Through pua_bla , BRIDGED LINE APPEARANCE features are added to openser.
31
-		 The pua_xmpp module represents a gateway between SIP and XMPP, so that 
27
+		 The <emphasize>pua_mi</emphasize> offer the possibility to publish any kind of information
28
+		 or subscribing to a resource through the manager interface.
29
+		 The <emphasize>pua_usrloc</emphasize> module calls a function exported by pua modules to publish
30
+		 elementary presence information, such as basic status "open" or "closed",
31
+		 for clients that do not implement client-to-server presence.
32
+		 Through <emphasize>pua_bla</emphasize> , BRIDGED LINE APPEARANCE features are added to openser.
33
+		 The <emphasize>pua_xmpp</emphasize> module represents a gateway between SIP and XMPP, so that 
32 34
 		 jabber and SIP clients can exchange presence information. 
33 35
 	</para>
34 36
 	<para>
35
-		The module use cache to store presentity list and writes to database
36
-		on timer to be able to recover upon restart.
37
+		The module use a cache to store the presentity list and writes to database
38
+		on timer to be able to recover upon restart. The presence is kept in-memory
39
+		during run-time.
37 40
 	</para>
38 41
 	</section>
39 42
 		<section>
... ...
@@ -78,8 +81,8 @@
78 81
 		<para>
79 82
 		The size of the hash table used for storing Subscribe and 
80 83
 		Publish information. 
81
-        This parameter will be used as the power of 2 when computing table size.
82
-        </para>
84
+        	This parameter will be used as the power of 2 when computing table size.
85
+        	</para>
83 86
 		<para>
84 87
 		<emphasis>Default value is <quote>9</quote>.	
85 88
 		</emphasis>
... ...
@@ -169,7 +172,7 @@ modparam("pua", "default_expires", 3600)
169 172
 		<title><varname>update_period</varname> (int)</title>
170 173
 		<para>
171 174
 		The interval at which the information in database and hash table
172
-		should be updated. In the case of the hash table updating is 
175
+		should be updated. In the case of the hash table updating means 
173 176
 		deleting expired messages.
174 177
 		</para>
175 178
 		<para>
... ...
@@ -209,7 +212,7 @@ modparam("pua", "outbound_proxy", "sip:outbound.example.com")
209 212
 		<para>
210 213
 		When sending PUBLISHs for Event: dialog, the body contains an
211 214
 		XML document according to RFC 4235. This XML document contains a 
212
-		version attribut to easily detect changes in the dialog state.
215
+		version attribute to easily detect changes in the dialog state.
213 216
 		By setting this parameter, the pua module parses the XML document and
214 217
 		sets the version attribute to the proper value. If the receiver of
215 218
 		the PUBLISH does not care about the version parameter (e.g. like
... ...
@@ -232,7 +235,7 @@ modparam("pua", "dlginfo_increase_version", 1)
232 235
 	</section>
233 236
 	</section>
234 237
 
235
-<section>
238
+	<section>
236 239
 	<title>Exported Functions</title>
237 240
 		
238 241
 	<section>
... ...
@@ -282,7 +285,7 @@ if(method=="NOTIFY")
282 285
 <section>
283 286
 	<title>Installation</title>
284 287
 	<para>
285
-	The module requires 1 table in &kamailio; database: pua. The SQL 
288
+	The module requires one table in the &kamailio; database: pua. The SQL 
286 289
 	syntax to create it can be found in presence_xml-create.sql     
287 290
 	script in the database directories in the kamailio/scripts folder.
288 291
 	You can also find the complete database documentation on the
... ...
@@ -14,7 +14,7 @@
14 14
     <title>&develguide;</title>
15 15
     <para>
16 16
 		The module provides the following functions that can be used
17
-		in other &kamailio; modules.
17
+		by other &kamailio; modules.
18 18
    </para>
19 19
  		<section>
20 20
 				<title>
... ...
@@ -22,7 +22,7 @@
22 22
 				</title>
23 23
 			<para>
24 24
 				This function binds the pua modules and fills the structure 
25
-				with the two exported function.
25
+				with the two exported functions.
26 26
 			</para>
27 27
 		<example>
28 28
 		<title><function>pua_api</function> structure</title>