Browse code

pua: Fixing documentation typos, adding reginfo

Olle E. Johansson authored on 21/10/2012 17:13:50
Showing 3 changed files
... ...
@@ -8,7 +8,7 @@ Edited by
8 8
 
9 9
 Anca-Maria Vamanu
10 10
 
11
-   Copyright © 2006 Voice Sistem SRL
11
+   Copyright � 2006 Voice Sistem SRL
12 12
      __________________________________________________________________
13 13
 
14 14
    Table of Contents
... ...
@@ -113,20 +113,22 @@ Chapter 1. Admin Guide
113 113
 1. Overview
114 114
 
115 115
    This module offer the functionality of a presence user agent client,
116
-   sending Subscribe and Publish messages. It's a core part of Kamailio's
117
-   SIP presence package, implementing SIMPLE and various shared line
118
-   appearance implementations.
119
-
120
-   It can be used with the following modules: pua_mi and pua_usrloc,
121
-   pua_bla and pua_xmpp. The pua_mi offer the possibility to publish any
122
-   kind of information or subscribing to a resource through the manager
123
-   interface. The pua_usrloc module calls a function exported by pua
124
-   modules to publish elementary presence information, such as basic
125
-   status "open" or "closed", for clients that do not implement
126
-   client-to-server presence. Through pua_bla , BRIDGED LINE APPEARANCE
127
-   features are added to openser. The pua_xmpp module represents a gateway
128
-   between SIP and XMPP, so that jabber and SIP clients can exchange
129
-   presence information.
116
+   sending SUBSCRIBE and PUBLISH SIP messages. It's a core part of
117
+   Kamailio's SIP presence package, implementing SIMPLE and various shared
118
+   line appearance implementations.
119
+
120
+   It can be used with the following modules: pua_mi, pua_usrloc, pua_bla,
121
+   pua_dialoginfo, pua_reginfo and pua_xmpp. The pua_mi module offer the
122
+   possibility to publish any kind of information or subscribing to a
123
+   resource through the manager interface. The pua_usrloc module calls a
124
+   function exported by pua modules to publish elementary presence
125
+   information, such as basic status "open" or "closed", for clients that
126
+   do not implement client-to-server presence. Through pua_bla , BRIDGED
127
+   LINE APPEARANCE features are added to Kamailio The pua_xmpp module
128
+   represents a gateway between SIP and XMPP, so that jabber and SIP
129
+   clients can exchange presence information. The pua_reginfo modules
130
+   presents registration information from the usrloc module using the
131
+   reginfo event package.
130 132
 
131 133
    The module supports 2 modes of operation. In the first a cache is used
132 134
    to store the presentity list and writes to database on timer to be able
... ...
@@ -169,11 +171,11 @@ Chapter 1. Admin Guide
169 171
 
170 172
 3.1. hash_size (int)
171 173
 
172
-   The size of the hash table used for storing Subscribe and Publish
174
+   The size of the hash table used for storing SUBSCRIBE and PUBLISH
173 175
    information. This parameter will be used as the power of 2 when
174 176
    computing table size.
175 177
 
176
-   Default value is “9”.
178
+   Default value is "9".
177 179
 
178 180
    Example 1.1. Set hash_size parameter
179 181
 ...
... ...
@@ -184,7 +186,7 @@ modparam("pua", "hash_size", 11)
184 186
 
185 187
    Database url.
186 188
 
187
-   Default value is “>mysql://openser:openserrw@localhost/openser”.
189
+   Default value is ">mysql://openser:openserrw@localhost/openser".
188 190
 
189 191
    Example 1.2. Set db_url parameter
190 192
 ...
... ...
@@ -195,7 +197,7 @@ modparam("pua", "db_url" "dbdriver://username:password@dbhost/dbname")
195 197
 
196 198
    The name of the database table.
197 199
 
198
-   Default value is “pua”.
200
+   Default value is "pua".
199 201
 
200 202
    Example 1.3. Set db_table parameter
201 203
 ...
... ...
@@ -206,7 +208,7 @@ modparam("pua", "db_table", "pua")
206 208
 
207 209
    The inferior expires limit for both Publish and Subscribe.
208 210
 
209
-   Default value is “0”.
211
+   Default value is "0".
210 212
 
211 213
    Example 1.4. Set min_expires parameter
212 214
 ...
... ...
@@ -218,7 +220,7 @@ modparam("pua", "min_expires", 0)
218 220
    The default expires value used in case this information is not
219 221
    provisioned.
220 222
 
221
-   Default value is “3600”.
223
+   Default value is "3600".
222 224
 
223 225
    Example 1.5. Set default_expires parameter
224 226
 ...
... ...
@@ -232,7 +234,7 @@ modparam("pua", "default_expires", 3600)
232 234
    expired messages. Setting a value less than or equal to zero, disables
233 235
    updates.
234 236
 
235
-   Default value is “100”.
237
+   Default value is "100".
236 238
 
237 239
    Example 1.6. Set update_period parameter
238 240
 ...
... ...
@@ -252,16 +254,16 @@ modparam("pua", "outbound_proxy", "sip:outbound.example.com")
252 254
 
253 255
 3.8. dlginfo_increase_version (int)
254 256
 
255
-   When sending PUBLISHs for Event: dialog, the body contains an XML
256
-   document according to RFC 4235. This XML document contains a version
257
-   attribute to easily detect changes in the dialog state. By setting this
258
-   parameter, the pua module parses the XML document and sets the version
259
-   attribute to the proper value. If the receiver of the PUBLISH does not
260
-   care about the version parameter (e.g. like Kamailio
257
+   When sending PUBLISH messages for Event: dialog, the body contains an
258
+   XML document according to RFC 4235. This XML document contains a
259
+   version attribute to easily detect changes in the dialog state. By
260
+   setting this parameter, the pua module parses the XML document and sets
261
+   the version attribute to the proper value. If the receiver of the
262
+   PUBLISH does not care about the version parameter (e.g. like Kamailio
261 263
    presence_dialoginfo module) it makes no sense to waste CPU resources
262 264
    for parsing the XML body and the parameter should be set to 0.
263 265
 
264
-   Default value is “0”.
266
+   Default value is "0".
265 267
 
266 268
    Example 1.8. Set dlginfo_increase_version parameter
267 269
 ...
... ...
@@ -270,8 +272,8 @@ modparam("pua", "dlginfo_increase_version", 1)
270 272
 
271 273
 3.9. reginfo_increase_version (int)
272 274
 
273
-   When sending PUBLISHs for Event: reg, the body contains an XML document
274
-   according to RFC 4235(?). This XML document contains a version
275
+   When sending PUBLISH messages for Event: reg, the body contains an XML
276
+   document according to RFC 4235(?). This XML document contains a version
275 277
    attribute to easily detect changes in the registration state. By
276 278
    setting this parameter, the pua module parses the XML document and sets
277 279
    the version attribute to the proper value. If the receiver of the
... ...
@@ -279,7 +281,7 @@ modparam("pua", "dlginfo_increase_version", 1)
279 281
    presence_reginfo module) it makes no sense to waste CPU resources for
280 282
    parsing the XML body and the parameter should be set to 0.
281 283
 
282
-   Default value is “0”.
284
+   Default value is "0".
283 285
 
284 286
    Example 1.9. Set reginfo_increase_version parameter
285 287
 ...
... ...
@@ -293,7 +295,7 @@ modparam("pua", "reginfo_increase_version", 1)
293 295
    in a database, allowing scalability at the expense of speed. Mode 1 is
294 296
    reserved.
295 297
 
296
-   Default value is “0”.
298
+   Default value is "0".
297 299
 
298 300
    Example 1.10. Set db_mode parameter
299 301
 ...
... ...
@@ -310,7 +312,7 @@ modparam("pua", "db_mode", 0)
310 312
    anyway. Set this parameter to 0 to disable checking of remote contact
311 313
    for SUBSCRIBE dialog matching.
312 314
 
313
-   Default value is “1”.
315
+   Default value is "1".
314 316
 
315 317
    Example 1.11. Set check_remote_contact parameter
316 318
 ...
... ...
@@ -332,7 +334,7 @@ modparam("pua", "fetch_rows", 1000)
332 334
 
333 335
    4.1. pua_update_contact()
334 336
 
335
-4.1.  pua_update_contact()
337
+4.1. pua_update_contact()
336 338
 
337 339
    The remote target can be updated by the Contact of a subsequent in
338 340
    dialog request. In the PUA watcher case (sending a SUBSCRIBE messages),
... ...
@@ -357,7 +359,7 @@ if(method=="NOTIFY")
357 359
 
358 360
    5.1. pua_cleanup
359 361
 
360
-5.1.  pua_cleanup
362
+5.1. pua_cleanup
361 363
 
362 364
    Manually triggers the cleanup functions for the pua table. Useful if
363 365
    you have set update_period to zero or less.
... ...
@@ -392,7 +394,7 @@ Chapter 2. Developer Guide
392 394
    The module provides the following functions that can be used by other
393 395
    Kamailio modules.
394 396
 
395
-1.  bind_pua(pua_api_t* api)
397
+1. bind_pua(pua_api_t* api)
396 398
 
397 399
    This function binds the pua modules and fills the structure with the
398 400
    two exported functions.
... ...
@@ -408,7 +410,7 @@ typedef struct pua_api {
408 410
 } pua_api_t;
409 411
 ...
410 412
 
411
-2.  send_publish
413
+2. send_publish
412 414
 
413 415
    Field type:
414 416
 ...
... ...
@@ -448,7 +450,7 @@ typedef struct publ_info
448 450
 }publ_info_t;
449 451
 ...
450 452
 
451
-3.  send_subscribe
453
+3. send_subscribe
452 454
 
453 455
    Field type:
454 456
 ...
... ...
@@ -487,7 +489,7 @@ typedef struct subs_info
487 489
 }subs_info_t;
488 490
 ...
489 491
 
490
-4.  is_dialog
492
+4. is_dialog
491 493
 
492 494
    Field type:
493 495
 ...
... ...
@@ -506,7 +508,7 @@ typedef int  (*query_dialog_t)(ua_pres_t* presentity);
506 508
         }
507 509
 ...
508 510
 
509
-5.  register_puacb
511
+5. register_puacb
510 512
 
511 513
    Field type:
512 514
 ...
... ...
@@ -535,7 +537,7 @@ typedef int (*register_puacb_t)(int types, pua_cb f, void* param );
535 537
 typedef int (pua_cb)(ua_pres_t* hentity, struct sip_msg*);
536 538
 ...
537 539
 
538
-6.  add_event
540
+6. add_event
539 541
 
540 542
    Field type:
541 543
 ...
... ...
@@ -553,8 +555,8 @@ typedef int (*add_pua_event_t)(int ev_flag, char* name,
553 555
 
554 556
    This function allows registering new events to the pua module. Now
555 557
    there are 4 events supported by the pua module: presence,
556
-   presence;winfo, message-summary, dialog;sla. These events are
557
-   registered from within the pua module.
558
+   presence;winfo, message-summary, dialog;sla, application/reginfo+xml.
559
+   These events are registered from within the pua module.
558 560
 
559 561
    Filed type for process_body:
560 562
 ...
... ...
@@ -17,21 +17,23 @@
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. It's a core part of &kamailio;'s 
20
+		sending SUBSCRIBE and PUBLISH SIP  messages. It's a core part of &kamailio;'s 
21 21
 		SIP presence package, implementing SIMPLE and various shared line appearance
22 22
 		implementations.
23 23
 	</para>
24 24
 	<para>
25
-		 It can be used with the following modules: pua_mi and pua_usrloc,
26
-		 pua_bla and pua_xmpp.
27
-		 The <emphasis>pua_mi</emphasis> offer the possibility to publish any kind of information
25
+		 It can be used with the following modules: pua_mi, pua_usrloc,
26
+		 pua_bla, pua_dialoginfo, pua_reginfo and pua_xmpp.
27
+		 The <emphasis>pua_mi</emphasis> module offer the possibility to publish any kind of information
28 28
 		 or subscribing to a resource through the manager interface.
29 29
 		 The <emphasis>pua_usrloc</emphasis> module calls a function exported by pua modules to publish
30 30
 		 elementary presence information, such as basic status "open" or "closed",
31 31
 		 for clients that do not implement client-to-server presence.
32
-		 Through <emphasis>pua_bla</emphasis> , BRIDGED LINE APPEARANCE features are added to openser.
32
+		 Through <emphasis>pua_bla</emphasis> , BRIDGED LINE APPEARANCE features are added to &kamailio;
33 33
 		 The <emphasis>pua_xmpp</emphasis> module represents a gateway between SIP and XMPP, so that 
34 34
 		 jabber and SIP clients can exchange presence information. 
35
+		 The <emphasis>pua_reginfo</emphasis> modules presents registration information from the usrloc module
36
+		 using the reginfo event package.
35 37
 	</para>
36 38
 	<para>
37 39
 		The module supports 2 modes of operation. In the first a cache is used to store
... ...
@@ -81,8 +83,8 @@
81 83
 	<section>
82 84
 		<title><varname>hash_size</varname> (int)</title>
83 85
 		<para>
84
-		The size of the hash table used for storing Subscribe and 
85
-		Publish information. 
86
+		The size of the hash table used for storing SUBSCRIBE and 
87
+		PUBLISH information. 
86 88
         	This parameter will be used as the power of 2 when computing table size.
87 89
         	</para>
88 90
 		<para>
... ...
@@ -213,7 +215,7 @@ modparam("pua", "outbound_proxy", "sip:outbound.example.com")
213 215
 	<section>
214 216
 		<title><varname>dlginfo_increase_version</varname> (int)</title>
215 217
 		<para>
216
-		When sending PUBLISHs for Event: dialog, the body contains an
218
+		When sending PUBLISH messages for Event: dialog, the body contains an
217 219
 		XML document according to RFC 4235. This XML document contains a 
218 220
 		version attribute to easily detect changes in the dialog state.
219 221
 		By setting this parameter, the pua module parses the XML document and
... ...
@@ -239,7 +241,7 @@ modparam("pua", "dlginfo_increase_version", 1)
239 241
 	<section>
240 242
 		<title><varname>reginfo_increase_version</varname> (int)</title>
241 243
 		<para>
242
-		When sending PUBLISHs for Event: reg, the body contains an
244
+		When sending PUBLISH messages for Event: reg, the body contains an
243 245
 		XML document according to RFC 4235(?). This XML document contains a 
244 246
 		version attribute to easily detect changes in the registration state.
245 247
 		By setting this parameter, the pua module parses the XML document and
... ...
@@ -240,8 +240,8 @@ typedef int (*add_pua_event_t)(int ev_flag, char* name,
240 240
 		<para>
241 241
 			This function allows registering new events to the pua module.
242 242
 			Now there are 4 events supported by the pua module: presence, 
243
-			presence;winfo, message-summary, dialog;sla. These events are registered
244
-			from within the pua module.
243
+			presence;winfo, message-summary, dialog;sla, application/reginfo+xml. 
244
+			These events are registered from within the pua module.
245 245
         </para>
246 246
 		<para>
247 247
 			Filed type for process_body: