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