modules: readme files regenerated - pua ... [skip ci]
[sip-router] / src / modules / pua / README
1 Presence User Agent Module
2
3 Anca-Maria Vamanu
4
5    Voice Sistem SRL
6
7 Edited by
8
9 Anca-Maria Vamanu
10
11    Copyright © 2006 Voice Sistem SRL
12      __________________________________________________________________
13
14    Table of Contents
15
16    1. Admin Guide
17
18         1. Overview
19         2. Dependencies
20
21               2.1. Kamailio Modules
22               2.2. External Libraries or Applications
23
24         3. Parameters
25
26               3.1. hash_size (int)
27               3.2. db_url (str)
28               3.3. db_table (str)
29               3.4. min_expires (int)
30               3.5. default_expires (int)
31               3.6. update_period (int)
32               3.7. outbound_proxy (str)
33               3.8. dlginfo_increase_version (int)
34               3.9. reginfo_increase_version (int)
35               3.10. db_mode (int)
36               3.11. db_table_lock_write (integer)
37               3.12. check_remote_contact (int)
38               3.13. fetch_rows (integer)
39
40         4. Functions
41
42               4.1. pua_update_contact()
43
44         5. RPC Commands
45
46               5.1. pua.cleanup
47
48         6. Installation
49
50    2. Developer Guide
51
52         1. bind_pua(pua_api_t* api)
53         2. send_publish
54         3. send_subscribe
55         4. is_dialog
56         5. register_puacb
57         6. add_event
58
59    List of Examples
60
61    1.1. Set hash_size parameter
62    1.2. Set db_url parameter
63    1.3. Set db_table parameter
64    1.4. Set min_expires parameter
65    1.5. Set default_expires parameter
66    1.6. Set update_period parameter
67    1.7. Set outbound_proxy parameter
68    1.8. Set dlginfo_increase_version parameter
69    1.9. Set reginfo_increase_version parameter
70    1.10. Set db_mode parameter
71    1.11. Set db_table_lock_write parameter
72    1.12. Set check_remote_contact parameter
73    1.13. Set fetch_rows parameter
74    1.14. pua_update_contact usage
75    2.1. pua_api structure
76    2.2. pua_is_dialog usage example
77    2.3. register_puacb usage example
78    2.4. add_event usage example
79
80 Chapter 1. Admin Guide
81
82    Table of Contents
83
84    1. Overview
85    2. Dependencies
86
87         2.1. Kamailio Modules
88         2.2. External Libraries or Applications
89
90    3. Parameters
91
92         3.1. hash_size (int)
93         3.2. db_url (str)
94         3.3. db_table (str)
95         3.4. min_expires (int)
96         3.5. default_expires (int)
97         3.6. update_period (int)
98         3.7. outbound_proxy (str)
99         3.8. dlginfo_increase_version (int)
100         3.9. reginfo_increase_version (int)
101         3.10. db_mode (int)
102         3.11. db_table_lock_write (integer)
103         3.12. check_remote_contact (int)
104         3.13. fetch_rows (integer)
105
106    4. Functions
107
108         4.1. pua_update_contact()
109
110    5. RPC Commands
111
112         5.1. pua.cleanup
113
114    6. Installation
115
116 1. Overview
117
118    This module offer the functionality of a presence user agent client,
119    sending SUBSCRIBE and PUBLISH SIP messages. It's a core part of
120    Kamailio's SIP presence package, implementing SIMPLE and various shared
121    line appearance implementations.
122
123    It can be used with the following modules: pua_rpc, pua_usrloc,
124    pua_bla, pua_dialoginfo, pua_reginfo and pua_xmpp. The pua_rpc module
125    offer the possibility to publish any kind of information via the RPC
126    transport. The pua_usrloc module calls a function exported by pua
127    modules to publish elementary presence information, such as basic
128    status "open" or "closed", for clients that do not implement
129    client-to-server presence. Through pua_bla , BRIDGED LINE APPEARANCE
130    features are added to Kamailio The pua_xmpp module represents a gateway
131    between SIP and XMPP, so that jabber and SIP clients can exchange
132    presence information. The pua_reginfo modules presents registration
133    information from the usrloc module using the reginfo event package.
134
135    The module supports 2 modes of operation. In the first a cache is used
136    to store the presentity list and writes to database on timer to be able
137    to recover upon restart. The presence is kept in-memory during
138    run-time. The second is a database only mode where the presentity list
139    is stored purely in a database, allowing both scalability and
140    resilience.
141
142 2. Dependencies
143
144    2.1. Kamailio Modules
145    2.2. External Libraries or Applications
146
147 2.1. Kamailio Modules
148
149    The following modules must be loaded before this module:
150      * a database modules.
151      * tm.
152
153 2.2. External Libraries or Applications
154
155    The following libraries or applications must be installed before
156    running Kamailio with this module loaded:
157      * libxml.
158
159 3. Parameters
160
161    3.1. hash_size (int)
162    3.2. db_url (str)
163    3.3. db_table (str)
164    3.4. min_expires (int)
165    3.5. default_expires (int)
166    3.6. update_period (int)
167    3.7. outbound_proxy (str)
168    3.8. dlginfo_increase_version (int)
169    3.9. reginfo_increase_version (int)
170    3.10. db_mode (int)
171    3.11. db_table_lock_write (integer)
172    3.12. check_remote_contact (int)
173    3.13. fetch_rows (integer)
174
175 3.1. hash_size (int)
176
177    The size of the hash table used for storing SUBSCRIBE and PUBLISH
178    information. This parameter will be used as the power of 2 when
179    computing table size.
180
181    Default value is “9”.
182
183    Example 1.1. Set hash_size parameter
184 ...
185 modparam("pua", "hash_size", 11)
186 ...
187
188 3.2. db_url (str)
189
190    Database url.
191
192    Default value is “>mysql://kamailio:kamailiorw@localhost/kamailio”.
193
194    Example 1.2. Set db_url parameter
195 ...
196 modparam("pua", "db_url" "dbdriver://username:password@dbhost/dbname")
197 ...
198
199 3.3. db_table (str)
200
201    The name of the database table.
202
203    Default value is “pua”.
204
205    Example 1.3. Set db_table parameter
206 ...
207 modparam("pua", "db_table", "pua")
208 ...
209
210 3.4. min_expires (int)
211
212    The inferior expires limit for both Publish and Subscribe.
213
214    Default value is “0”.
215
216    Example 1.4. Set min_expires parameter
217 ...
218 modparam("pua", "min_expires", 0)
219 ...
220
221 3.5. default_expires (int)
222
223    The default expires value used in case this information is not
224    provisioned.
225
226    Default value is “3600”.
227
228    Example 1.5. Set default_expires parameter
229 ...
230 modparam("pua", "default_expires", 3600)
231 ...
232
233 3.6. update_period (int)
234
235    The interval at which the information in database and hash table should
236    be updated. In the case of the hash table updating means deleting
237    expired messages. Setting a value less than or equal to zero, disables
238    updates.
239
240    Default value is “100”.
241
242    Example 1.6. Set update_period parameter
243 ...
244 modparam("pua", "update_period", 100)
245 ...
246
247 3.7. outbound_proxy (str)
248
249    SIP URI of outbound proxy to be used when sending PUBLISH requests if
250    no outbound proxy is given in outbound_proxy field of struct publ_info.
251
252    By default, no outbound proxy has been defined.
253
254    Example 1.7. Set outbound_proxy parameter
255 ...
256 modparam("pua", "outbound_proxy", "sip:outbound.example.com")
257 ...
258
259 3.8. dlginfo_increase_version (int)
260
261    When sending PUBLISH messages for Event: dialog, the body contains an
262    XML document according to RFC 4235. This XML document contains a
263    version attribute to easily detect changes in the dialog state. By
264    setting this parameter, the pua module parses the XML document and sets
265    the version attribute to the proper value. If the receiver of the
266    PUBLISH does not care about the version parameter (e.g. like Kamailio
267    presence_dialoginfo module) it makes no sense to waste CPU resources
268    for parsing the XML body and the parameter should be set to 0.
269
270    Default value is “0”.
271
272    Example 1.8. Set dlginfo_increase_version parameter
273 ...
274 modparam("pua", "dlginfo_increase_version", 1)
275 ...
276
277 3.9. reginfo_increase_version (int)
278
279    When sending PUBLISH messages for Event: reg, the body contains an XML
280    document according to RFC 4235(?). This XML document contains a version
281    attribute to easily detect changes in the registration state. By
282    setting this parameter, the pua module parses the XML document and sets
283    the version attribute to the proper value. If the receiver of the
284    PUBLISH does not care about the version parameter (e.g. like Kamailio
285    presence_reginfo module) it makes no sense to waste CPU resources for
286    parsing the XML body and the parameter should be set to 0.
287
288    Default value is “0”.
289
290    Example 1.9. Set reginfo_increase_version parameter
291 ...
292 modparam("pua", "reginfo_increase_version", 1)
293 ...
294
295 3.10. db_mode (int)
296
297    The module supports 2 modes of operation, high speed memory based
298    storage (mode 0), and database only (mode 2) where all data is stored
299    in a database, allowing scalability at the expense of speed. Mode 1 is
300    reserved.
301
302    Default value is “0”.
303
304    Example 1.10. Set db_mode parameter
305 ...
306 modparam("pua", "db_mode", 0)
307 ...
308
309 3.11. db_table_lock_write (integer)
310
311    Enable (=1) or disable (=0) the Locks for table during an transaction.
312    Locking only the "current" table causes problems with a MySQL-Databases
313    in "DB-Only" mode.
314
315    Default value is 1 (Write Lock for the Tables).
316
317    Example 1.11. Set db_table_lock_write parameter
318 ...
319 modparam("pua", "db_table_lock_write", 0)
320 ...
321
322 3.12. check_remote_contact (int)
323
324    When sending a SUBSCRIBE check that the remote contact matches the one
325    in the stored dialog or not. If the remote contact is checked and does
326    not match the one in the stored dialog then the dialog is not matched.
327    Checking the remote contact can cause problems when using modules like
328    RLS and should not be required in order to properly match the dialog
329    anyway. Set this parameter to 0 to disable checking of remote contact
330    for SUBSCRIBE dialog matching.
331
332    Default value is “1”.
333
334    Example 1.12. Set check_remote_contact parameter
335 ...
336 modparam("pua", "check_remote_contact", 0)
337 ...
338
339 3.13. fetch_rows (integer)
340
341    Number of rows to be loaded in one step from database.
342
343    Default value is 500.
344
345    Example 1.13. Set fetch_rows parameter
346 ...
347 modparam("pua", "fetch_rows", 1000)
348 ...
349
350 4. Functions
351
352    4.1. pua_update_contact()
353
354 4.1.  pua_update_contact()
355
356    The remote target can be updated by the Contact of a subsequent in
357    dialog request. In the PUA watcher case (sending a SUBSCRIBE messages),
358    this means that the remote target for the following Subscribe messages
359    can be updated at any time by the contact of a Notify message. If this
360    function is called on request route on receiving a Notify message, it
361    will try to update the stored remote target.
362
363    This function can be used from REQUEST_ROUTE.
364
365    Return code:
366      * 1 - if success.
367      * -1 - if error.
368
369    Example 1.14. pua_update_contact usage
370 ...
371 if(method=="NOTIFY")
372     pua_update_contact();
373 ...
374
375 5. RPC Commands
376
377    5.1. pua.cleanup
378
379 5.1.  pua.cleanup
380
381    Manually triggers the cleanup functions for the pua table. Useful if
382    you have set update_period to zero or less.
383
384    Name: pua.cleanup
385
386    Parameters: none
387
388    RPC Command Format:
389 ...
390 kamcmd pua.cleanup
391 ...
392
393 6. Installation
394
395    The module requires one table in the Kamailio database: pua. The SQL
396    syntax to create it can be found in presence_xml-create.sql script in
397    the database directories in the kamailio/scripts folder. You can also
398    find the complete database documentation on the project webpage,
399    http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
400
401 Chapter 2. Developer Guide
402
403    Table of Contents
404
405    1. bind_pua(pua_api_t* api)
406    2. send_publish
407    3. send_subscribe
408    4. is_dialog
409    5. register_puacb
410    6. add_event
411
412    The module provides the following functions that can be used by other
413    Kamailio modules.
414
415 1.  bind_pua(pua_api_t* api)
416
417    This function binds the pua modules and fills the structure with the
418    two exported functions.
419
420    Example 2.1. pua_api structure
421 ...
422 typedef struct pua_api {
423         send_subscribe_t send_subscribe;
424         send_publish_t send_publish;
425         query_dialog_t is_dialog;
426         register_puacb_t register_puacb;
427         add_pua_event_t add_event;
428 } pua_api_t;
429 ...
430
431 2.  send_publish
432
433    Field type:
434 ...
435 typedef int (*send_publish_t)(publ_info_t* publ);
436 ...
437
438    This function receives as a parameter a structure with Publish required
439    information and sends a Publish message.
440
441    The structure received as a parameter:
442 ...
443 typedef struct publ_info
444
445   str id;             /*  (optional )a value unique for one combination
446                           of pres_uri and flag */
447   str* pres_uri;      /*  the presentity uri */
448   str* body;          /*  the body of the Publish message;
449                           can be NULL in case of an update expires*/
450   int  expires;       /*  the expires value that will be used in
451                           Publish Expires header*/
452   int flag;           /*  it can be : INSERT_TYPE or UPDATE_TYPE
453                           if missing it will be established according
454                           to the result of the search in hash table*/
455   int source_flag;    /*  flag identifying the resource ;
456                           supported values: UL_PUBLISH, MI_PUBLISH,
457                           BLA_PUBLISH, XMPP_PUBLISH*/
458   int event;          /*  the event flag;
459                           supported values: PRESENCE_EVENT, BLA_EVENT,
460                           MWI_EVENT */
461   str content_type;   /*  the content_type of the body if present
462                           (optional if the same as the default value
463                           for that event)*/
464   str* etag;          /*  (optional) the value of the etag the request
465                           should match */
466   str* outbound_proxy;/*  outbound_proxy to use when sending the
467                           Publish request */
468   str* extra_headers  /*  (optional) extra_headers that should be added
469                           to Publish msg*/
470 }publ_info_t;
471 ...
472
473 3.  send_subscribe
474
475    Field type:
476 ...
477 typedef int (*send_subscribe_t)(subs_info_t* subs);
478 ...
479
480    This function receives as a parameter a structure with Subscribe
481    required information and sends a Subscribe message.
482
483    The structure received as a parameter:
484 ...
485 typedef struct subs_info
486
487   str id;              /*  an id value unique for one combination
488                            of pres_uri and flag */
489   str* pres_uri;       /*  the presentity uri */
490   str* watcher_uri;    /*  the watcher uri */
491   str* contact;        /*  the uri that will be used in
492                            Contact header*/
493   str* remote_target;  /*  the uri that will be used as R-URI
494                            for the Subscribe message(not compulsory;
495                            if not set the value of the pres_uri field
496                            is used) */
497   str* outbound_proxy; /*  the outbound_proxy to use when sending the
498                            Subscribe request*/
499   int event;           /*  the event flag; supported value:
500                            PRESENCE_EVENT, BLA_EVENT, PWINFO_EVENT*/
501   int expires;         /*  the expires value that will be used in
502                            Subscribe Expires header */
503   int flag;            /*  it can be : INSERT_TYPE or UPDATE_TYPE
504                            not compulsory */
505   int source_flag;     /*  flag identifying the resource ;
506                            supported values:  MI_SUBSCRIBE,
507                            BLA_SUBSCRIBE, XMPP_SUBSCRIBE,
508                            XMPP_INITIAL_SUBS */
509 }subs_info_t;
510 ...
511
512 4.  is_dialog
513
514    Field type:
515 ...
516 typedef int  (*query_dialog_t)(ua_pres_t* presentity);
517 ...
518
519    This function checks is the parameter corresponds to a stored Subscribe
520    initiated dialog.
521
522    Example 2.2. pua_is_dialog usage example
523 ...
524         if(pua_is_dialog(dialog) < 0)
525         {
526                 LM_ERR("querying dialog\n");
527                 goto error;
528         }
529 ...
530
531 5.  register_puacb
532
533    Field type:
534 ...
535 typedef int (*register_puacb_t)(int types, pua_cb f, void* param );
536 ...
537
538    This function registers a callback to be called on receiving the reply
539    message for a sent Publish or Subscribe request. The type parameter
540    should be set the same as the source_flag for that request. The
541    function registered as callback for pua should be of type pua_cb ,
542    which is: typedef void (pua_cb)(ua_pres_t* hentity, struct msg_start *
543    fl); The parameters are the dialog structure for that request and the
544    first line of the reply message.
545
546    Example 2.3. register_puacb usage example
547 ...
548         if(pua.register_puacb(XMPP_SUBSCRIBE, Sipreply2Xmpp, NULL) & 0)
549         {
550                 LM_ERR("Could not register callback\n");
551                 return -1;
552         }
553 ...
554
555    The callback function type:
556 ...
557 typedef int (pua_cb)(ua_pres_t* hentity, struct sip_msg*);
558 ...
559
560 6.  add_event
561
562    Field type:
563 ...
564 typedef int (*add_pua_event_t)(int ev_flag, char* name,
565    char* content_type,evs_process_body_t* process_body);
566
567 - ev_flag     : an event flag defined as a macro in pua module
568 - name        : the event name to be used in Event request headers
569 - content_type: the default content_type for Publish body for
570                 that event (NULL if winfo event)
571 - process_body: function that processes the received body before
572                 using it to construct the PUBLISH request
573                 (NULL if winfo event)
574 ...
575
576    This function allows registering new events to the pua module. Now
577    there are 4 events supported by the pua module: presence,
578    presence;winfo, message-summary, dialog;sla, application/reginfo+xml.
579    These events are registered from within the pua module.
580
581    Filed type for process_body:
582 ...
583 typedef int (evs_process_body_t)(struct publ_info* publ,
584   str** final_body, int ver, str* tuple);
585 - publ      : the structure received as a parameter in send_publish
586               function ( initial body found in publ->body)
587 - final_body: the pointer where the result(final_body) should be stored
588 - ver       : a counter for the sent Publish requests
589               (used for winfo events)
590 - tuple     : a unique identifier for the resource;
591               if an initial Publish it should be returned as a result
592               and it will be stored  for that record, otherwise it will
593               be given as a parameter;
594 ...
595
596    Example 2.4. add_event usage example
597 ...
598         if(pua.add_event((PRESENCE_EVENT, "presence", "application/pidf+xml",
599                                 pres_process_body) & 0)
600         {
601                 LM_ERR("Could not register new event\n");
602                 return -1;
603         }
604 ...