
Presence Module

Anca-Maria Vamanu

   voice-system.ro

Edited by

Anca-Maria Vamanu

   Copyright © 2006 voice-system.ro
   Revision History
   Revision $Revision: 5905 $ $Date: 2008-08-06 12:08:33 +0200
   (Wed, 06 Aug 2008) $
     _________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. Kamailio Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. db_url(str)
              1.3.2. presentity_table(str)
              1.3.3. active_watchers_table(str)
              1.3.4. watchers_table(str)
              1.3.5. clean_period (int)
              1.3.6. db_update_period (int)
              1.3.7. to_tag_pref (str)
              1.3.8. expires_offset (int)
              1.3.9. max_expires (int)
              1.3.10. server_address (str)
              1.3.11. fallback2db (int)
              1.3.12. subs_htable_size (int)
              1.3.13. pres_htable_size (int)
              1.3.14. enable_sphere_check (int)

        1.4. Exported Functions

              1.4.1. handle_publish(char* sender_uri) 
              1.4.2. handle_subscribe() 

        1.5. Exported MI Functions

              1.5.1. refreshWatchers 
              1.5.2. cleanup 

        1.6. Installation

   2. Developer Guide

        2.1. bind_presence(presence_api_t* api) 
        2.2. add_event 
        2.3. get_rules_doc 
        2.4. get_auth_status 
        2.5. apply_auth_nbody 
        2.6. agg_nbody 
        2.7. free_body 
        2.8. aux_body_processing 
        2.9. aux_free_body 
        2.10. evs_publ_handl 
        2.11. evs_subs_handl 
        2.12. contains_event 
        2.13. get_event_list 
        2.14. update_watchers_status 
        2.15. get_sphere 

   List of Examples

   1.1. Set db_url parameter
   1.2. Set presentity_table parameter
   1.3. Set active_watchers_table parameter
   1.4. Set watchers_table parameter
   1.5. Set clean_period parameter
   1.6. Set db_update_period parameter
   1.7. Set to_tag_pref parameter
   1.8. Set expires_offset parameter
   1.9. Set max_expires parameter
   1.10. Set server_address parameter
   1.11. Set fallback2db parameter
   1.12. Set subs_htable_size parameter
   1.13. Set pres_htable_size parameter
   1.14. Set enable_sphere_check parameter
   1.15. handle_publish usage
   1.16. handle_subscribe usage
   2.1. presence_api_t structure

Chapter 1. Admin Guide

1.1. Overview

   The Presence module implements the core functionality of SIP
   event notification. It handles PUBLISH and SUBSCRIBE messages
   and generates NOTIFY messages in a general, event independent
   way. It is extensible and allows registering events to it from
   other Kamailio modules. Supported SIP event packages are
   presence, presence.winfo, dialog;sla from the presence_xml
   module and message-summary from the presence_mwi module.

   The module uses database storage and memory caching (to
   improve performance). The SIP SUBSCRIBE dialog information is
   stored in memory and is periodically updated in the database,
   while for PUBLISH only the presence or absence of stored info
   for a certain resource is maintained in memory to avoid
   unnecessary, costly database operations. It is possible to enable
   database lookups on cache misses by configuring a fallback to
   database mode (by setting module parameter "fallback2db").
   In this mode, in case a searched record is not found in cache,
   the search is continued in database. This is useful for an
   architecture in which processing and memory load might be
   divided on several Kamailio instances, maybe on different
   servers using the same database.

   The module implements several API functions, that can be used
   by other modules. In fact, it can be used only as a resource
   module, or "library". This mode of operation is enabled if the
   db_url parameter is not set to any value.

   The Kamailio Presence module implements the specifications in:
   RFC3265, RFC3856, RFC3857, RFC3858.

1.2. Dependencies

1.2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * a database module.
     * sl.
     * tm.

1.2.2. External Libraries or Applications

     * libxml.

1.3. Exported Parameters

1.3.1. db_url(str)

   The database url.

   If set, the module is a fully operational presence server.
   Otherwise, it is used as a 'library', for its exported
   functions.

   Default value is "NULL". 

   Example 1.1. Set db_url parameter
...
modparam("presence", "db_url",
        "mysql://openser:openserrw@192.168.2.132/openser")
...

1.3.2. presentity_table(str)

   The name of the db table where PUBLISH presence information is
   stored.

   Default value is "presentity". 

   Example 1.2. Set presentity_table parameter
...
modparam("presence", "presentity_table", "presentity")
...

1.3.3. active_watchers_table(str)

   The name of the db table where active subscription information
   is stored.

   Default value is "active_watchers". 

   Example 1.3. Set active_watchers_table parameter
...
modparam("presence", "active_watchers_table", "active_watchers")
...

1.3.4. watchers_table(str)

   The name of the db table where subscription states are stored.

   Default value is "watchers". 

   Example 1.4. Set watchers_table parameter
...
modparam("presence", "watchers_table", "watchers")
...

1.3.5. clean_period (int)

   The period in seconds between checks if there are expired
   messages stored in database.

   Default value is "100". A zero or negative value disables this
   activity. 

   Example 1.5. Set clean_period parameter
...
modparam("presence", "clean_period", 100)
...

1.3.6. db_update_period (int)

   The period at which to synchronize cached subscriber info with
   the database.

   Default value is "100". A zero or negative value disables
   synchronization. 

   Example 1.6. Set db_update_period parameter
...
modparam("presence", "db_update_period", 100)
...

1.3.7. to_tag_pref (str)

   The prefix used when generating to_tag when sending replies
   for SUBSCRIBE requests.

   Default value is "10". 

   Example 1.7. Set to_tag_pref parameter
...
modparam("presence", "to_tag_pref", 'pres')
...

1.3.8. expires_offset (int)

   The value in seconds that should be subtracted from the
   expires value when sending a 200OK for a publish. It is used
   for forcing the client cu send an update before the old
   publish expires.

   Default value is "0". 

   Example 1.8. Set expires_offset parameter
...
modparam("presence", "expires_offset", 10)
...

1.3.9. max_expires (int)

   The the maximum admissible expires value for PUBLISH/SUBSCRIBE
   message (in seconds).

   Default value is "3600". 

   Example 1.9. Set max_expires parameter
...
modparam("presence", "max_expires", 3600)
...

1.3.10. server_address (str)

   The presence server address which will become the value of
   Contact header filed for 200OK replies to Subscribe and
   Publish and in Notify messages.

   Example 1.10. Set server_address parameter
...
modparam("presence", "server_address", "sip:10.10.10.10:5060")
...

1.3.11. fallback2db (int)

   Setting this parameter enables a fallback to db mode of
   operation. In this mode, in case a searched record is not
   found in cache, the search is continued in database. Useful
   for an architecture in which processing and memory load might
   be divided on more servers using the same database.
   During runtime, the database is kept up2date regardless of the parameter's value.

   Example 1.11. Set fallback2db parameter
...
modparam("presence", "fallback2db", 1)
...

1.3.12. subs_htable_size (int)

   The size of the in-memory hash table to store subscription
   dialogs. This parameter will be used as the power of 2 when
   computing table size.

   Default value is "9 (512)". 

   Example 1.12. Set subs_htable_size parameter
...
modparam("presence", "subs_htable_size", 11)
...

1.3.13. pres_htable_size (int)

   The size of the in-memory hash table to store publish records.
   This parameter will be used as the power of 2 when computing
   table size.

   Default value is "9 (512)". 

   Example 1.13. Set pres_htable_size parameter
...
modparam("presence", "pres_htable_size", 11)
...

1.3.14. enable_sphere_check (int)

   This parameter is a flag that should be set if permission
   rules include sphere checking. The sphere information is
   expected to be present in the RPID body published by the
   presentity. The flag is introduced as this check requires
   extra processing that should be avoided if this feature is not
   supported by the clients.

   Default value is "0 ". 

   Example 1.14. Set enable_sphere_check parameter
...
modparam("presence", "enable_sphere_check", 1)
...

1.4. Exported Functions

1.4.1.  handle_publish(char* sender_uri)

   Handles PUBLISH requests by storing and updating published
   information in memory cach and database, then calls functions
   to send NOTIFY messages when changes in the published
   information occur. It takes one argument -> sender_uri. The
   parameter was added for enabling BLA implementation. If
   present, Notification of a change in published state is not
   sent to the respective uri even though a subscription exists.
   It should be taken from the Sender header. It was left at the
   decision of the administrator whether or not to transmit the
   content of this header as parameter for handle_publish, to
   prevent security problems.

   This function can be used from REQUEST_ROUTE.

   Return code:
     * 1 - if success.
     * -1 - if error.

   The module sends an appropriate stateless reply in all cases.

   Example 1.15. handle_publish usage
...
        if(is_method("PUBLISH"))
        {
                if($hdr(Sender)!= NULL)
                        handle_publish("$hdr(Sender)");
                else
                        handle_publish();
                t_release();
        }
...

1.4.2.  handle_subscribe()

   The function which handles SUBSCRIBE requests. It stores or
   updates information in memory and database and calls functions
   to send Notify messages when a SUBSCRIBE which initiate a
   dialog is received

   This function can be used from REQUEST_ROUTE.

   Return code:
     * 1 - if success.
     * -1 - if error.

   The module sends an appropriate stateless reply in all cases.

   Example 1.16. handle_subscribe usage
...
if(method=="SUBSCRIBE")
    handle_subscribe();
...

1.5. Exported MI Functions

1.5.1.  refreshWatchers

   Triggers sending Notify messages to watchers if a change in
   watchers authorization or in published state occurred.

   Name: refreshWatchers

   Parameters:
     * presentity_uri : the uri of the user who made the change
       and whose watchers should be informed
     * event : the event package
     * refresh type : it distinguishes between the two different
       types of events that can trigger a refresh:
          + a change in watchers authentication: refresh type= 0
            ;
          + a statical update in published state (either through
            direct update in db table or by modifying the pidf
            manipulation document, if pidf_manipulation parameter
            is set): refresh type!= 0.

   MI FIFO Command Format:
                :refreshWatchers:fifo_reply
                sip:11@192.168.2.132
                presence
                1
                _empty_line_

1.5.2.  cleanup

   Manually triggers the cleanup functions for watchers and
   presentity tables. Useful if you have set clean_period to zero
   or less.

   Name: cleanup

   Parameters:none.emphasis>

   MI FIFO Command Format:
                :cleanup:fifo_reply
                _empty_line_


1.6. Installation

   The module requires 3 tables in the Kamailio database:
   "presentity", "active_watchers" and "watchers". The SQL syntax
   to create them can be found in presence-create.sql script in
   the database directories in the kamailio/scripts folder. You
   can also find the complete database documentation on the
   project webpage,
   http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.

Chapter 2. Developer Guide

   The module provides the following functions that can be used
   in other Kamailio modules.

2.1.  bind_presence(presence_api_t* api)

   This function binds the presence modules and fills the
   structure with one exported function -> add_event, which when
   called adds a new event to be handled by presence.

   Example 2.1. presence_api_t structure
...
typedef struct presence_api {
        add_event_t add_event;
        contains_event_t contains_event;
        search_event_t search_event;
        get_event_list_t get_event_list;

        update_watchers_t update_watchers_status;

        /* subs hash table handling functions */
        new_shtable_t new_shtable;
        destroy_shtable_t destroy_shtable;
        insert_shtable_t insert_shtable;
        search_shtable_t search_shtable;
        delete_shtable_t delete_shtable;
        update_shtable_t update_shtable;
        /* function to duplicate a subs structure*/
        mem_copy_subs_t  mem_copy_subs;
        /* function used for update in database*/
        update_db_subs_t update_db_subs;
        /* function to extract dialog information from a
        SUBSCRIBE message */
        extract_sdialog_info_t extract_sdialog_info;
        /* function to request sphere defition for a presentity */
        pres_get_sphere_t get_sphere;

}presence_api_t;
...

2.2.  add_event

   Field type:
...
typedef int (*add_event_t)(pres_ev_t* event);
...

   This function receives as a parameter a structure with event
   specific information and adds it to presence event list.

   The structure received as a parameter:
...
typedef struct pres_ev
{
        str name;
        event_t* evp;
        str content_type;
        int default_expires;
        int type;
        int etag_not_new;
        /*
         *  0 - the standard mechanism (allocating new etag
                        for each Publish)
         *  1 - allocating an etag only
                        for an initial Publish
        */
        int req_auth;
        get_rules_doc_t* get_rules_doc;
        apply_auth_t*  apply_auth_nbody;
        is_allowed_t*  get_auth_status;

        /* an agg_body_t function should be registered
         * if the event permits having multiple published
         * states and requires an aggregation of the information
         * otherwise, this field should be NULL and the last
         * published state is taken when constructing Notify msg
         */
        agg_nbody_t* agg_nbody;
        publ_handling_t  * evs_publ_handl;
        subs_handling_t  * evs_subs_handl;
        free_body_t* free_body;
    /* sometimes it is necessary that a module make changes for a body
for each
     * active watcher (e.g. setting the "version" parameter in an XML d
ocument.
     * If a module registers the aux_body_processing callback, it gets
called for
     * each watcher. It either gets the body received by the PUBLISH, o
r the body
     * generated by the agg_nbody function.
     * The module can deceide if it makes a copy of the original body,
which is then
     * manipulated, or if it works directly in the original body. If th
e module makes a
     * copy of the original body, it also has to register the aux_free_
body() to
     * free this "per watcher" body.
     */
    aux_body_processing_t* aux_body_processing;
    free_body_t* aux_free_body;
        struct pres_ev* wipeer;
        struct pres_ev* next;

}pres_ev_t;
...

2.3.  get_rules_doc

   Filed type:
...
typedef int (get_rules_doc_t)(str* user, str* domain, str** rules_doc);
...

   This function returns the authorization rules document that
   will be used in obtaining the status of the subscription and
   processing the notified body. A reference to the document
   should be put in the auth_rules_doc of the subs_t structure
   given as a parameter to the functions described bellow.

2.4.  get_auth_status

   This filed is a function to be called for a subscription
   request to return the state for that subscription according to
   authorization rules. In the auth_rules_doc field of the subs_t
   structure received as a parameter should contain the rules
   document of the presentity in case, if it exists.

   It is called only if the req_auth field is not 0.

   Filed type:
...
typedef int (is_allowed_t)(struct subscription* subs);
...

2.5.  apply_auth_nbody

   This parameter should be a function to be called for an event
   that requires authorization, when constructing final body. The
   authorization document is taken from the auth_rules_doc field
   of the subs_t structure given as a parameter. It is called
   only if the req_auth field is not 0.

   Filed type:
...
typedef int (apply_auth_t)(str* , struct subscription*, str** );
...

2.6.  agg_nbody

   If present, this field marks that the events requires
   aggregation of states. This function receives a body array and
   should return the final body. If not present, it is considered
   that the event does not require aggregation and the most
   recent published information is used when constructing
   Notifies.

   Filed type:
...
typedef str* (agg_nbody_t)(str* pres_user, str* pres_domain,
str** body_array, int n, int off_index);
..

2.7.  free_body

   This field must be field in if subsequent processing is
   performed on the info from database before being inserted in
   Notify message body(if agg_nbody or apply_auth_nbody fields
   are filled in). It should match the allocation function used
   when processing the body.

   Filed type:
...
typedef void(free_body_t)(char* body);
..

2.8.  aux_body_processing

   This field must be set if the module needs to manipulate the
   NOTIFY body for each watcher. E.g. if the XML body includes a
   'version' parameter which will be increased for each NOTIFY,
   on a "per watcher" basis. The module can either allocate a new
   buffer for the new body an return it (aux_free_body function
   must be set too) or it manipualtes the original body directly
   and returns NULL.

   Filed type:
...
typedef str* (aux_body_processing_t)(struct subscription *subs, str* bo
dy);
..

2.9.  aux_free_body

   This field must be set if the module registers the
   aux_body_processing function and allocates memory for the new
   modified body. Then, this function will be used to free the
   pointer returned by the aux_body_processing function. If the
   module does use the aux_body_processing, but does not allocate
   new memory, but manipulates directly the original body buffer,
   then the aux_body_processing must return NULL and this field
   should not be set.

   Filed type:
...
typedef void(free_body_t)(char* body);
..

2.10.  evs_publ_handl

   This function is called when handling Publish requests. Most
   contain body correctness check.

...
typedef int (publ_handling_t)(struct sip_msg*);
..

2.11.  evs_subs_handl

   It is not compulsory. Should contain event specific handling
   for Subscription requests.

   Filed type:
...
typedef int (subs_handling_t)(struct sip_msg*);
..

2.12.  contains_event

   Field type:
..
typedef pres_ev_t* (*contains_event_t)(str* name,
event_t* parsed_event);
...

   The function parses the event name received as a parameter and
   searches the result in the list. It returns the found event or
   NULL, if not found. If the second argument is an allocated
   event_t* structure it fills it with the result of the parsing.

2.13.  get_event_list

   Field type:
...
typedef int (*get_event_list_t) (str** ev_list);
...

   This function returns a string representation of the events
   registered in presence module.( used for Allowed-Events
   header).

2.14.  update_watchers_status

   Field type:
...
typedef int (*update_watchers_t)(str pres_uri, pres_ev_t* ev,
str* rules_doc);
...

   This function is an external command that can be used to
   announce a change in authorization rules for a presentity. It
   updates the stored status and sends a Notify to the watchers
   whose status has changes. (used by presence_xml module when
   notified through an MI command of a change in an xcap
   document).

2.15.  get_sphere

   Field type:
...
typedef char* (*pres_get_sphere_t)(str* pres_uri);
...

   This function searches for a sphere definition in the
   published information if this has type RPID. If not found
   returns NULL. (the return value is allocated in private memory
   and should be freed)
