presence: rename recently added parameter to the 'standard' db_mode that others uses
[sip-router] / modules_k / presence / README
1 Presence Module
2
3 Anca-Maria Vamanu
4
5    Voice Sistem SRL
6
7 Juha Heinanen
8
9    TutPro Inc.
10
11 Edited by
12
13 Anca-Maria Vamanu
14
15 Edited by
16
17 Juha Heinanen
18
19    Copyright © 2006 Voice Sistem SRL
20
21    Copyright © 2009 Juha Heinanen
22      __________________________________________________________________
23
24    Table of Contents
25
26    1. Admin Guide
27
28         1. Overview
29         2. Dependencies
30
31               2.1. Kamailio Modules
32               2.2. External Libraries or Applications
33
34         3. Exported Parameters
35
36               3.1. db_url(str)
37               3.2. presentity_table(str)
38               3.3. active_watchers_table(str)
39               3.4. watchers_table(str)
40               3.5. clean_period (int)
41               3.6. db_update_period (int)
42               3.7. to_tag_pref (str)
43               3.8. expires_offset (int)
44               3.9. max_expires (int)
45               3.10. server_address (str)
46               3.11. fallback2db (int)
47               3.12. db_mode (int)
48               3.13. subs_htable_size (int)
49               3.14. pres_htable_size (int)
50               3.15. enable_sphere_check (int)
51               3.16. timeout_rm_subs (int)
52
53         4. Exported Functions
54
55               4.1. handle_publish(char* sender_uri)
56               4.2. handle_subscribe()
57               4.3. pres_auth_status(watcher_uri, presentity_uri)
58               4.4. pres_refresh_watchers(uri, event, type)
59               4.5. pres_update_watchers(uri, event)
60
61         5. Exported MI Functions
62
63               5.1. refreshWatchers
64               5.2. cleanup
65
66         6. Installation
67
68    2. Developer Guide
69
70         1. bind_presence(presence_api_t* api)
71         2. add_event
72         3. get_rules_doc
73         4. get_auth_status
74         5. apply_auth_nbody
75         6. agg_nbody
76         7. free_body
77         8. aux_body_processing
78         9. aux_free_body
79         10. evs_publ_handl
80         11. evs_subs_handl
81         12. contains_event
82         13. get_event_list
83         14. update_watchers_status
84         15. get_sphere
85
86    List of Examples
87
88    1.1. Set db_url parameter
89    1.2. Set presentity_table parameter
90    1.3. Set active_watchers_table parameter
91    1.4. Set watchers_table parameter
92    1.5. Set clean_period parameter
93    1.6. Set db_update_period parameter
94    1.7. Set to_tag_pref parameter
95    1.8. Set expires_offset parameter
96    1.9. Set max_expires parameter
97    1.10. Set server_address parameter
98    1.11. Set fallback2db parameter
99    1.12. Set db_mode parameter
100    1.13. Set subs_htable_size parameter
101    1.14. Set pres_htable_size parameter
102    1.15. Set enable_sphere_check parameter
103    1.16. Set timeout_rm_subs parameter
104    1.17. handle_publish usage
105    1.18. handle_subscribe usage
106    1.19. pres_auth_status usage
107    1.20. pres_refresh_watchers usage
108    1.21. pres_update_watchers usage
109    2.1. presence_api_t structure
110
111 Chapter 1. Admin Guide
112
113    Table of Contents
114
115    1. Overview
116    2. Dependencies
117
118         2.1. Kamailio Modules
119         2.2. External Libraries or Applications
120
121    3. Exported Parameters
122
123         3.1. db_url(str)
124         3.2. presentity_table(str)
125         3.3. active_watchers_table(str)
126         3.4. watchers_table(str)
127         3.5. clean_period (int)
128         3.6. db_update_period (int)
129         3.7. to_tag_pref (str)
130         3.8. expires_offset (int)
131         3.9. max_expires (int)
132         3.10. server_address (str)
133         3.11. fallback2db (int)
134         3.12. db_mode (int)
135         3.13. subs_htable_size (int)
136         3.14. pres_htable_size (int)
137         3.15. enable_sphere_check (int)
138         3.16. timeout_rm_subs (int)
139
140    4. Exported Functions
141
142         4.1. handle_publish(char* sender_uri)
143         4.2. handle_subscribe()
144         4.3. pres_auth_status(watcher_uri, presentity_uri)
145         4.4. pres_refresh_watchers(uri, event, type)
146         4.5. pres_update_watchers(uri, event)
147
148    5. Exported MI Functions
149
150         5.1. refreshWatchers
151         5.2. cleanup
152
153    6. Installation
154
155 1. Overview
156
157    The Presence module implements the core functionality of SIP event
158    notification. It handles PUBLISH and SUBSCRIBE messages and generates
159    NOTIFY messages in a general, event independent way. It is extensible
160    and allows registering events to it from other Kamailio modules.
161    Supported SIP event packages are presence, presence.winfo, dialog;sla
162    from the presence_xml module and message-summary from the presence_mwi
163    module.
164
165    The module uses database storage and memory caching (to improve
166    performance). The SIP SUBSCRIBE dialog information is stored in memory
167    and is periodically updated in the database, while for PUBLISH only the
168    presence or absence of stored info for a certain resource is maintained
169    in memory to avoid unnecessary, costly database operations. It is
170    possible to disable in-memory caching by configuring a fallback to
171    database mode (by setting the module parameter "fallback2db"). In this
172    mode, in case a searched record is not found in cache, the search is
173    continued in database. This is useful for an architecture in which
174    processing and memory load might be divided on several Kamailio
175    instances, maybe on different servers using the same database. This
176    parameter remains only for legacy purposes. As a new feature for the
177    presence engine, it is possible to have three database modes, which one
178    can configure through the db_mode parameter. Setting db_mode to 0, 1, 2
179    respective will cause the subscribers to be retrieved from memory only,
180    from memory and to fallback to database mode in case a record is not
181    found in memory, and from database only.
182
183    The module implements several API functions, that can be used by other
184    modules. In fact, it can be used only as a resource module, or
185    "library". This mode of operation is enabled if the db_url parameter is
186    not set to any value.
187
188    The Kamailio Presence module implements the specifications in: RFC3265,
189    RFC3856, RFC3857, RFC3858.
190
191 2. Dependencies
192
193    2.1. Kamailio Modules
194    2.2. External Libraries or Applications
195
196 2.1. Kamailio Modules
197
198    The following modules must be loaded before this module:
199      * a database module.
200      * sl.
201      * tm.
202
203 2.2. External Libraries or Applications
204
205      * libxml.
206
207 3. Exported Parameters
208
209    3.1. db_url(str)
210    3.2. presentity_table(str)
211    3.3. active_watchers_table(str)
212    3.4. watchers_table(str)
213    3.5. clean_period (int)
214    3.6. db_update_period (int)
215    3.7. to_tag_pref (str)
216    3.8. expires_offset (int)
217    3.9. max_expires (int)
218    3.10. server_address (str)
219    3.11. fallback2db (int)
220    3.12. db_mode (int)
221    3.13. subs_htable_size (int)
222    3.14. pres_htable_size (int)
223    3.15. enable_sphere_check (int)
224    3.16. timeout_rm_subs (int)
225
226 3.1. db_url(str)
227
228    The database url.
229
230    If set, the module is a fully operational presence server. Otherwise,
231    it is used as a 'library', for its exported functions.
232
233    Default value is “NULL”.
234
235    Example 1.1. Set db_url parameter
236 ...
237 modparam("presence", "db_url",
238         "mysql://openser:openserrw@localhost/openser")
239 ...
240
241 3.2. presentity_table(str)
242
243    The name of the db table where PUBLISH presence information is stored.
244
245    Default value is “presentity”.
246
247    Example 1.2. Set presentity_table parameter
248 ...
249 modparam("presence", "presentity_table", "presentity")
250 ...
251
252 3.3. active_watchers_table(str)
253
254    The name of the db table where active subscription information is
255    stored.
256
257    Default value is “active_watchers”.
258
259    Example 1.3. Set active_watchers_table parameter
260 ...
261 modparam("presence", "active_watchers_table", "active_watchers")
262 ...
263
264 3.4. watchers_table(str)
265
266    The name of the db table where subscription states are stored.
267
268    Default value is “watchers”.
269
270    Example 1.4. Set watchers_table parameter
271 ...
272 modparam("presence", "watchers_table", "watchers")
273 ...
274
275 3.5. clean_period (int)
276
277    The period in seconds between checks if there are expired messages
278    stored in database.
279
280    Default value is “100”. A zero or negative value disables this
281    activity.
282
283    Example 1.5. Set clean_period parameter
284 ...
285 modparam("presence", "clean_period", 100)
286 ...
287
288 3.6. db_update_period (int)
289
290    The period at which to synchronize cached subscriber info with the
291    database.
292
293    Default value is “100”. A zero or negative value disables
294    synchronization.
295
296    Example 1.6. Set db_update_period parameter
297 ...
298 modparam("presence", "db_update_period", 100)
299 ...
300
301 3.7. to_tag_pref (str)
302
303    The prefix used when generating to_tag when sending replies for
304    SUBSCRIBE requests.
305
306    Default value is “10”.
307
308    Example 1.7. Set to_tag_pref parameter
309 ...
310 modparam("presence", "to_tag_pref", 'pres')
311 ...
312
313 3.8. expires_offset (int)
314
315    The value in seconds that should be subtracted from the expires value
316    when sending a 200OK for a publish. It is used for forcing the client
317    to send an update before the old publish expires.
318
319    Default value is “0”.
320
321    Example 1.8. Set expires_offset parameter
322 ...
323 modparam("presence", "expires_offset", 10)
324 ...
325
326 3.9. max_expires (int)
327
328    The the maximum admissible expires value for PUBLISH/SUBSCRIBE message
329    (in seconds).
330
331    Default value is “3600”.
332
333    Example 1.9. Set max_expires parameter
334 ...
335 modparam("presence", "max_expires", 3600)
336 ...
337
338 3.10. server_address (str)
339
340    The presence server address which will become the value of Contact
341    header filed for 200 OK replies to SUBSCRIBE and PUBLISH and in NOTIFY
342    messages.
343
344    Example 1.10. Set server_address parameter
345 ...
346 modparam("presence", "server_address", "sip:10.10.10.10:5060")
347 ...
348
349 3.11. fallback2db (int)
350
351    Setting this parameter enables a fallback to db mode of operation. In
352    this mode, in case a searched record is not found in cache, the search
353    is continued in database. Useful for an architecture in which
354    processing and memory load might be divided on more servers using the
355    same database.
356
357    Example 1.11. Set fallback2db parameter
358 ...
359 modparam("presence", "fallback2db", 1)
360 ...
361
362 3.12. db_mode (int)
363
364    This parameter sets the mode in which records are retrieved. Setting
365    this parameter to 0 or 1 is equivalent to setting fallback2db to 0 or
366    1, respectiv. The db_mode parameter can also take a third value, 2, in
367    which records are retrieved from database only. So, the three database
368    modes in which the presence engine can operate are: memory only,
369    fallback to database, and database only.
370
371    Example 1.12. Set db_mode parameter
372 ...
373 modparam("presence", "db_mode", 2)
374 ...
375
376 3.13. subs_htable_size (int)
377
378    The size of the in-memory hash table to store subscription dialogs.
379    This parameter will be used as the power of 2 when computing table
380    size.
381
382    Default value is “9 (512)”.
383
384    Example 1.13. Set subs_htable_size parameter
385 ...
386 modparam("presence", "subs_htable_size", 11)
387 ...
388
389 3.14. pres_htable_size (int)
390
391    The size of the in-memory hash table to store publish records. This
392    parameter will be used as the power of 2 when computing table size.
393
394    Default value is “9 (512)”.
395
396    Example 1.14. Set pres_htable_size parameter
397 ...
398 modparam("presence", "pres_htable_size", 11)
399 ...
400
401 3.15. enable_sphere_check (int)
402
403    This parameter is a flag that should be set if permission rules include
404    sphere checking. The sphere information is expected to be present in
405    the RPID body published by the presentity. The flag is introduced as
406    this check requires extra processing that should be avoided if this
407    feature is not supported by the clients.
408
409    Default value is “0 ”.
410
411    Example 1.15. Set enable_sphere_check parameter
412 ...
413 modparam("presence", "enable_sphere_check", 1)
414 ...
415
416 3.16. timeout_rm_subs (int)
417
418    This parameter is a flag that should be set if subscriptions should be
419    removed from the active_watchers when a NOTIFY times out. RFC3265
420    section 3.2.2 defines this behaviour as a SHOULD, so by default it is
421    on. Disabling this will keep subscriptions active on unreliable
422    networks.
423
424    Default value is “1”.
425
426    Example 1.16. Set timeout_rm_subs parameter
427 ...
428 modparam("presence", "timeout_rm_subs", 0)
429 ...
430
431 4. Exported Functions
432
433    4.1. handle_publish(char* sender_uri)
434    4.2. handle_subscribe()
435    4.3. pres_auth_status(watcher_uri, presentity_uri)
436    4.4. pres_refresh_watchers(uri, event, type)
437    4.5. pres_update_watchers(uri, event)
438
439 4.1.  handle_publish(char* sender_uri)
440
441    Handles PUBLISH requests by storing and updating published information
442    in memory cache and database, then calls functions to send NOTIFY
443    messages when changes in the published information occur. It takes one
444    argument -> sender_uri. The parameter was added for enabling BLA
445    implementation. If present, notification of a change in published state
446    is not sent to the respective uri even though a subscription exists. It
447    should be taken from the Sender header. It was left at the decision of
448    the administrator whether or not to transmit the content of this header
449    as parameter for handle_publish, to prevent security problems.
450
451    This function can be used from REQUEST_ROUTE.
452
453    Return code:
454      * 1 - if success.
455      * -1 - if error.
456
457    The module sends an appropriate stateless reply in all cases.
458
459    Example 1.17. handle_publish usage
460 ...
461         if(is_method("PUBLISH"))
462         {
463                 if($hdr(Sender)!= NULL)
464                         handle_publish("$hdr(Sender)");
465                 else
466                         handle_publish();
467                 t_release();
468         }
469 ...
470
471 4.2.  handle_subscribe()
472
473    The function which handles SUBSCRIBE requests. It stores or updates
474    information in memory and database and calls functions to send NOTIFY
475    messages when a SUBSCRIBE which initiate a dialog is received
476
477    This function can be used from REQUEST_ROUTE.
478
479    Return code:
480      * 1 - if success.
481      * -1 - if error.
482
483    The module sends an appropriate stateless reply in all cases.
484
485    Example 1.18. handle_subscribe usage
486 ...
487 if(method=="SUBSCRIBE")
488     handle_subscribe();
489 ...
490
491 4.3.  pres_auth_status(watcher_uri, presentity_uri)
492
493    The function checks if watcher is authorized to subscribe event
494    'presence' of presentity. Both watcher_uri and presentity_uri are
495    pseudo variables. Function returns ACTIVE_STATUS, if subscription is
496    allowed and PENDING_STATUS, TERMINATED_STATUS, or WAITING_STATUS
497    otherwise. See presence/subscribe.h for the corresponding integer
498    codes. In case of error, function returns -1.
499
500    This function can be used from REQUEST_ROUTE.
501
502    Example 1.19. pres_auth_status usage
503 ...
504 if (method=="MESSAGE") {
505     pres_auth_status("$fu", $ru");
506     if ($retcode == 1) {
507         t_relay();
508     } else {
509         send_reply("403", "Forbidden");
510     }
511 }
512 ...
513
514 4.4.  pres_refresh_watchers(uri, event, type)
515
516    The function can be used in configuration to triger notifies to
517    watchers if a change in watchers authorization or in published state
518    occurred (i.e., updates of xcap documents).
519
520    Parameters:
521      * uri - the uri of the user who made the change and whose watchers
522        should be informed.
523      * event - the event package.
524      * type - it distinguishes between the two different types of events
525        that can trigger the refresh, depending on its value:
526           + 0 - a change in watchers authentication.
527           + 1 - a statical update in published state (either through
528             direct update in db table or by modifying the pidf
529             manipulation document, if pidf_manipulation parameter is set).
530
531    This function can be used from ANY_ROUTE.
532
533    Example 1.20. pres_refresh_watchers usage
534 ...
535 pres_refresh_watchers("sip:test@kamailio.org", "presence", 1);
536 ...
537
538 4.5.  pres_update_watchers(uri, event)
539
540    The function can be used in configuration to triger updates to watchers
541    status if a change in watchers authorization state occurred (i.e.,
542    updates of xcap documents change state from pending to active).
543
544    Parameters:
545      * uri - the uri of the user who made the change and whose watchers
546        should be informed. Can be PV.
547      * event - the event package (e.g., presence).
548
549    This function can be used from ANY_ROUTE.
550
551    Example 1.21. pres_update_watchers usage
552 ...
553 pres_update_watchers("sip:test@kamailio.org", "presence");
554 ...
555
556 5. Exported MI Functions
557
558    5.1. refreshWatchers
559    5.2. cleanup
560
561 5.1.  refreshWatchers
562
563    Triggers sending Notify messages to watchers if a change in watchers
564    authorization or in published state occurred.
565
566    Name: refreshWatchers
567
568    Parameters:
569      * presentity_uri : the uri of the user who made the change and whose
570        watchers should be informed
571      * event : the event package
572      * refresh type : it distinguishes between the two different types of
573        events that can trigger a refresh:
574           + a change in watchers authentication: refresh type= 0 ;
575           + a statical update in published state (either through direct
576             update in db table or by modifying the pidf manipulation
577             document, if pidf_manipulation parameter is set): refresh
578             type!= 0.
579
580    MI FIFO Command Format:
581                 :refreshWatchers:fifo_reply
582                 sip:test@kamailio.org
583                 presence
584                 1
585                 _empty_line_
586
587 5.2.  cleanup
588
589    Manually triggers the cleanup functions for watchers and presentity
590    tables. Useful if you have set clean_period to zero or less.
591
592    Name: cleanup
593
594    Parameters:none.emphasis>
595
596    MI FIFO Command Format:
597                 :cleanup:fifo_reply
598                 _empty_line_
599
600 6. Installation
601
602    The module requires 3 tables in the Kamailio database: "presentity",
603    "active_watchers" and "watchers". The SQL syntax to create them can be
604    found in presence-create.sql script in the database directories in the
605    kamailio/scripts folder. You can also find the complete database
606    documentation on the project webpage,
607    http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
608
609 Chapter 2. Developer Guide
610
611    Table of Contents
612
613    1. bind_presence(presence_api_t* api)
614    2. add_event
615    3. get_rules_doc
616    4. get_auth_status
617    5. apply_auth_nbody
618    6. agg_nbody
619    7. free_body
620    8. aux_body_processing
621    9. aux_free_body
622    10. evs_publ_handl
623    11. evs_subs_handl
624    12. contains_event
625    13. get_event_list
626    14. update_watchers_status
627    15. get_sphere
628
629    The module provides the following functions that can be used in other
630    Kamailio modules.
631
632 1.  bind_presence(presence_api_t* api)
633
634    This function binds the presence modules and fills the structure with
635    one exported function -> add_event, which when called adds a new event
636    to be handled by presence.
637
638    Example 2.1. presence_api_t structure
639 ...
640 typedef struct presence_api {
641         add_event_t add_event;
642         contains_event_t contains_event;
643         search_event_t search_event;
644         get_event_list_t get_event_list;
645
646         update_watchers_t update_watchers_status;
647
648         /* subs hash table handling functions */
649         new_shtable_t new_shtable;
650         destroy_shtable_t destroy_shtable;
651         insert_shtable_t insert_shtable;
652         search_shtable_t search_shtable;
653         delete_shtable_t delete_shtable;
654         update_shtable_t update_shtable;
655         /* function to duplicate a subs structure*/
656         mem_copy_subs_t  mem_copy_subs;
657         /* function used for update in database*/
658         update_db_subs_t update_db_subs;
659         /* function to extract dialog information from a
660         SUBSCRIBE message */
661         extract_sdialog_info_t extract_sdialog_info;
662         /* function to request sphere defition for a presentity */
663         pres_get_sphere_t get_sphere;
664
665 }presence_api_t;
666 ...
667
668 2.  add_event
669
670    Field type:
671 ...
672 typedef int (*add_event_t)(pres_ev_t* event);
673 ...
674
675    This function receives as a parameter a structure with event specific
676    information and adds it to presence event list.
677
678    The structure received as a parameter:
679 ...
680 typedef struct pres_ev
681 {
682         str name;
683         event_t* evp;
684         str content_type;
685         int default_expires;
686         int type;
687         int etag_not_new;
688         /*
689          *  0 - the standard mechanism (allocating new etag
690                         for each Publish)
691          *  1 - allocating an etag only
692                         for an initial Publish
693         */
694         int req_auth;
695         get_rules_doc_t* get_rules_doc;
696         apply_auth_t*  apply_auth_nbody;
697         is_allowed_t*  get_auth_status;
698
699         /* an agg_body_t function should be registered
700          * if the event permits having multiple published
701          * states and requires an aggregation of the information
702          * otherwise, this field should be NULL and the last
703          * published state is taken when constructing Notify msg
704          */
705         agg_nbody_t* agg_nbody;
706         publ_handling_t  * evs_publ_handl;
707         subs_handling_t  * evs_subs_handl;
708         free_body_t* free_body;
709     /* sometimes it is necessary that a module make changes for a body for each
710      * active watcher (e.g. setting the "version" parameter in an XML document.
711      * If a module registers the aux_body_processing callback, it gets called fo
712 r
713      * each watcher. It either gets the body received by the PUBLISH, or the bod
714 y
715      * generated by the agg_nbody function.
716      * The module can deceide if it makes a copy of the original body, which is
717 then
718      * manipulated, or if it works directly in the original body. If the module
719 makes a
720      * copy of the original body, it also has to register the aux_free_body() to
721      * free this "per watcher" body.
722      */
723     aux_body_processing_t* aux_body_processing;
724     free_body_t* aux_free_body;
725         struct pres_ev* wipeer;
726         struct pres_ev* next;
727
728 }pres_ev_t;
729 ...
730
731 3.  get_rules_doc
732
733    Filed type:
734 ...
735 typedef int (get_rules_doc_t)(str* user, str* domain, str** rules_doc);
736 ...
737
738    This function returns the authorization rules document that will be
739    used in obtaining the status of the subscription and processing the
740    notified body. A reference to the document should be put in the
741    auth_rules_doc of the subs_t structure given as a parameter to the
742    functions described bellow.
743
744 4.  get_auth_status
745
746    This filed is a function to be called for a subscription request to
747    return the state for that subscription according to authorization
748    rules. In the auth_rules_doc field of the subs_t structure received as
749    a parameter should contain the rules document of the presentity in
750    case, if it exists.
751
752    It is called only if the req_auth field is not 0.
753
754    Filed type:
755 ...
756 typedef int (is_allowed_t)(struct subscription* subs);
757 ...
758
759 5.  apply_auth_nbody
760
761    This parameter should be a function to be called for an event that
762    requires authorization, when constructing final body. The authorization
763    document is taken from the auth_rules_doc field of the subs_t structure
764    given as a parameter. It is called only if the req_auth field is not 0.
765
766    Filed type:
767 ...
768 typedef int (apply_auth_t)(str* , struct subscription*, str** );
769 ...
770
771 6.  agg_nbody
772
773    If present, this field marks that the events requires aggregation of
774    states. This function receives a body array and should return the final
775    body. If not present, it is considered that the event does not require
776    aggregation and the most recent published information is used when
777    constructing Notifies.
778
779    Filed type:
780 ...
781 typedef str* (agg_nbody_t)(str* pres_user, str* pres_domain,
782 str** body_array, int n, int off_index);
783 ..
784
785 7.  free_body
786
787    This field must be field in if subsequent processing is performed on
788    the info from database before being inserted in Notify message body(if
789    agg_nbody or apply_auth_nbody fields are filled in). It should match
790    the allocation function used when processing the body.
791
792    Filed type:
793 ...
794 typedef void(free_body_t)(char* body);
795 ..
796
797 8.  aux_body_processing
798
799    This field must be set if the module needs to manipulate the NOTIFY
800    body for each watcher. E.g. if the XML body includes a 'version'
801    parameter which will be increased for each NOTIFY, on a "per watcher"
802    basis. The module can either allocate a new buffer for the new body an
803    return it (aux_free_body function must be set too) or it manipualtes
804    the original body directly and returns NULL.
805
806    Filed type:
807 ...
808 typedef str* (aux_body_processing_t)(struct subscription *subs, str* body);
809 ..
810
811 9.  aux_free_body
812
813    This field must be set if the module registers the aux_body_processing
814    function and allocates memory for the new modified body. Then, this
815    function will be used to free the pointer returned by the
816    aux_body_processing function. If the module does use the
817    aux_body_processing, but does not allocate new memory, but manipulates
818    directly the original body buffer, then the aux_body_processing must
819    return NULL and this field should not be set.
820
821    Filed type:
822 ...
823 typedef void(free_body_t)(char* body);
824 ..
825
826 10.  evs_publ_handl
827
828    This function is called when handling Publish requests. Most contain
829    body correctness check.
830
831 ...
832 typedef int (publ_handling_t)(struct sip_msg*);
833 ..
834
835 11.  evs_subs_handl
836
837    It is not compulsory. Should contain event specific handling for
838    Subscription requests.
839
840    Filed type:
841 ...
842 typedef int (subs_handling_t)(struct sip_msg*);
843 ..
844
845 12.  contains_event
846
847    Field type:
848 ..
849 typedef pres_ev_t* (*contains_event_t)(str* name,
850 event_t* parsed_event);
851 ...
852
853    The function parses the event name received as a parameter and searches
854    the result in the list. It returns the found event or NULL, if not
855    found. If the second argument is an allocated event_t* structure it
856    fills it with the result of the parsing.
857
858 13.  get_event_list
859
860    Field type:
861 ...
862 typedef int (*get_event_list_t) (str** ev_list);
863 ...
864
865    This function returns a string representation of the events registered
866    in presence module.( used for Allowed-Events header).
867
868 14.  update_watchers_status
869
870    Field type:
871 ...
872 typedef int (*update_watchers_t)(str pres_uri, pres_ev_t* ev,
873 str* rules_doc);
874 ...
875
876    This function is an external command that can be used to announce a
877    change in authorization rules for a presentity. It updates the stored
878    status and sends a Notify to the watchers whose status has changes.
879    (used by presence_xml module when notified through an MI command of a
880    change in an xcap document).
881
882 15.  get_sphere
883
884    Field type:
885 ...
886 typedef char* (*pres_get_sphere_t)(str* pres_uri);
887 ...
888
889    This function searches for a sphere definition in the published
890    information if this has type RPID. If not found returns NULL. (the
891    return value is allocated in private memory and should be freed)