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