Presence_XML Module

Anca-Maria Vamanu

   Voice Sistem SRL

Edited by

Anca-Maria Vamanu

   Copyright © 2007 Voice Sistem SRL
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. db_url(str)
              3.2. xcap_table(str)
              3.3. disable_presence(int)
              3.4. disable_winfo(int)
              3.5. disable_bla(int)
              3.6. disable_xcapdiff(int)
              3.7. force_active (int)
              3.8. integrated_xcap_server (int)
              3.9. xcap_server (str)
              3.10. passive_mode(int)
              3.11. xcapauth_userdel_reason(str)
              3.12. force_dummy_presence(int)
              3.13. force_presence_single_body(int)
              3.14. presence_single_body_priorities(str)
              3.15. presence_single_body_lookup_element(str)

        4. Functions

              4.1. pres_check_basic(presentity_uri, status)
              4.2. pres_check_activities(presentity_uri, activity)

        5. Installation

   2. Developer Guide

   List of Examples

   1.1. Set db_url parameter
   1.2. Set xcap_table parameter
   1.3. Set disable_presence parameter
   1.4. Set disable_winfo parameter
   1.5. Set disable_bla parameter
   1.6. Set disable_xcapdiff parameter
   1.7. Set force_active parameter
   1.8. Set integrated_xcap_server parameter
   1.9. Set xcap_server parameter
   1.10. Set passive_mode parameter
   1.11. Set xcapauth_userdel_reason parameter
   1.12. Set force_dummy_presence parameter
   1.13. Set force_presence_single_body parameter
   1.14. Set presence_single_body_priorities parameter
   1.15. Set presence_single_body_lookup_element parameter
   1.16. pres_check_basic usage
   1.17. pres_check_activities usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. db_url(str)
        3.2. xcap_table(str)
        3.3. disable_presence(int)
        3.4. disable_winfo(int)
        3.5. disable_bla(int)
        3.6. disable_xcapdiff(int)
        3.7. force_active (int)
        3.8. integrated_xcap_server (int)
        3.9. xcap_server (str)
        3.10. passive_mode(int)
        3.11. xcapauth_userdel_reason(str)
        3.12. force_dummy_presence(int)
        3.13. force_presence_single_body(int)
        3.14. presence_single_body_priorities(str)
        3.15. presence_single_body_lookup_element(str)

   4. Functions

        4.1. pres_check_basic(presentity_uri, status)
        4.2. pres_check_activities(presentity_uri, activity)

   5. Installation

1. Overview

   The module does specific handling for notify-subscribe events using xml
   bodies. It is used with the general event handling module, presence. It
   constructs and adds 3 events to it:
     * presence - SIMPLE status presence: RFC 3856
     * presence.winfo - SIMPLE watcher info: RFC 3857
     * dialog;sla (or dialog;ma) - Bridged Line Appearances (BLA) (or
       Multiple Line Appearances (MLA)): draft-anil-sipping-bla

   You can control which events are enabled via module parameters.

   This module takes the XCAP permission rule documents from xcap_table.
   The presence permission rules are interpreted according to the
   specifications in RFC 4745 and RFC 5025.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * a database module.
     * presence.
     * sl.
     * xcap_client.
       Needed only when not using the integrated xcap server (if
       'integrated_xcap_server' parameter is set to 0).

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * libxml.

3. Parameters

   3.1. db_url(str)
   3.2. xcap_table(str)
   3.3. disable_presence(int)
   3.4. disable_winfo(int)
   3.5. disable_bla(int)
   3.6. disable_xcapdiff(int)
   3.7. force_active (int)
   3.8. integrated_xcap_server (int)
   3.9. xcap_server (str)
   3.10. passive_mode(int)
   3.11. xcapauth_userdel_reason(str)
   3.12. force_dummy_presence(int)
   3.13. force_presence_single_body(int)
   3.14. presence_single_body_priorities(str)
   3.15. presence_single_body_lookup_element(str)

3.1. db_url(str)

   The database URL.

   Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.

   Example 1.1. Set db_url parameter
...
modparam("presence_xml", "db_url", "dbdriver://username:password@dbhost/dbname")
...

3.2. xcap_table(str)

   The name of the database table where XCAP documents are stored.

   Default value is “xcap”.

   Example 1.2. Set xcap_table parameter
...
modparam("presence_xml", "xcap_table", "xcaps")
...

3.3. disable_presence(int)

   Set this parameter to disable the handling of the "presence" event.

   Default value: “0”.

   Example 1.3. Set disable_presence parameter
...
modparam("presence_xml", "disable_presence", 1)
...

3.4. disable_winfo(int)

   Set this parameter to disable the handling of the "presence.winfo"
   event.

   Default value: “0”.

   Example 1.4. Set disable_winfo parameter
...
modparam("presence_xml", "disable_winfo", 1)
...

3.5. disable_bla(int)

   Set this parameter to disable the handling of the "dialog;sla" event.

   Default value: “1” (0 - enabled, 1 - disabled).

   Example 1.5. Set disable_bla parameter
...
modparam("presence_xml", "disable_bla", 1)
...

3.6. disable_xcapdiff(int)

   Set this parameter to disable the handling of the "xcap-diff" event.

   Default value: “0”.

   Example 1.6. Set disable_xcapdiff parameter
...
modparam("presence_xml", "disable_xcapdiff", 1)
...

3.7. force_active (int)

   This parameter is used for permissions when handling Subscribe
   messages. If set to 1, subscription state is considered active and the
   presentity is not queried for permissions (should be set to 1 if not
   using an XCAP server). Otherwise, the XCAP server is queried and the
   subscription states is according to user defined permission rules. If
   no rules are defined for a certain watcher, the subscriptions remains
   in pending state and the Notify sent will have no body.

   Note: When switching from one value to another, the watchers table must
   be emptied.

   Default value is “0”.

   Example 1.7. Set force_active parameter
...
modparam("presence_xml", "force_active", 1)
...

3.8. integrated_xcap_server (int)

   This parameter is a flag for the type of XCAP servers used. If the XCAP
   server is integrated with Kamailio presence_xml module and access the
   same database tables directly, like the embedded XCAP server
   implemented in xcap_server module, the parameter has to be set to 1.
   Apart from updating in xcap table, if the integrated server is not
   running on the same Kamailio instance, it must send an RPC command
   presence.refreshWatchers [pres_uri] [event] when a user modifies a
   rules document, to instruct the presence_xml module to update states
   from the database and, if needed, send NOTIFY updates.

   Otherwise (if set to 0) it uses xcap_client module to fetch documents
   from the XCAP servers with HTTP requests.

   Default value is “0”.

   Example 1.8. Set integrated_xcap_server parameter
...
modparam("presence_xml", "integrated_xcap_server", 1)
...

3.9. xcap_server (str)

   The address of the xcap servers used for storage. This parameter is
   compulsory if the integrated_xcap_server parameter is not set. It can
   be set more that once, to construct an address list of trusted XCAP
   servers.

   Example 1.9. Set xcap_server parameter
...
modparam("presence_xml", "xcap_server", "xcap_server.example.org")
modparam("presence_xml", "xcap_server", "xcap_server.ag.org")
...

3.10. passive_mode(int)

   If set to 1, module acts in passive mode - no bind to presence module,
   no connection to database. Useful when needing only to use $xml(...)
   pseudo-variable.

   Default value: “0” (0 - active mode, 1 - passive mode).

   Example 1.10. Set passive_mode parameter
...
modparam("presence_xml", "passive_mode", 1)
...

3.11. xcapauth_userdel_reason(str)

   This parameter represents the reason that will be included in the
   Subscription-State header of the Notify when a rule is no longer found
   in the XCAP pres-auth document for a user that was previously allowed.
   The Subscription state in this case switches to "terminated". Because
   it is not clear which reason is most appropriate in this case from the
   ones defined by the RFC 3265, this parameter offers the possibility for
   the admin to decide which one he wishes to use.

   Default value: “probation” . Since probation also accepts a retry-after
   parameter to specify after at least how may seconds the client should
   reattempt to resubscribe, you can include this in the parameter also.

   Example 1.11. Set xcapauth_userdel_reason parameter
...
modparam("presence_xml", "xcapauth_userdel_reason", "probation;retry-after=30")
modparam("presence_xml", "xcapauth_userdel_reason", "rejected")
...

3.12. force_dummy_presence(int)

   Set this parameter to enable simple body notify with status 'open' when
   presentity info is not available.

   Default value: “0”.

   Example 1.12. Set force_dummy_presence parameter
...
modparam("presence_xml", "force_dummy_presence", 1)
...

3.13. force_presence_single_body(int)

   Set this parameter to enable single body notify. One presentity can
   have multiple dialogs and will by default notify all the dialogs and
   this can be a problem when dealing with large ring-groups or
   attendants, use this parameter to only send one body. Look at
   presence_single_body_priorities and presence_single_body_lookup_element
   to customize the behaviour.

   Default value: “0”.

   Example 1.13. Set force_presence_single_body parameter
...
modparam("presence_xml", "force_presence_single_body", 1)
...

3.14. presence_single_body_priorities(str)

   Change this parameter to set the priorities when choosing the dialog
   that will be the final.

   Importance is left to right.

   Default value: “Available|Ringing|On the Phone”.

   Example 1.14. Set presence_single_body_priorities parameter
...
modparam("presence_xml", "presence_single_body_priorities", "Offline|Online|Busy
|Really Busy")
...

3.15. presence_single_body_lookup_element(str)

   Set the name of the element that should be used to get the priority. If
   the value obtained is not in the list of
   presence_single_body_priorities the priority is 0.

   Default value: “note”.

   Example 1.15. Set presence_single_body_lookup_element parameter
...
modparam("presence_xml", "presence_single_body_lookup_element", "status")
...

4. Functions

   4.1. pres_check_basic(presentity_uri, status)
   4.2. pres_check_activities(presentity_uri, activity)

4.1.  pres_check_basic(presentity_uri, status)

   Checks the /presence/tuple/status/basic nodes in the presentity for
   presentity_uri against the value in status.

   This function can be used from ANY_ROUTE.

   Return code:
     * 1 - if a match is found.
     * -1 - if a match is not found.

   Example 1.16. pres_check_basic usage
...
    if (pres_check_basic("$ru", "open")) {
        ...
    } else {
        if (is_method("MESSAGE"))
            m_store();
    else
        send_reply("404", "Not Found");
    }
...

4.2.  pres_check_activities(presentity_uri, activity)

   Checks whether a /presence/person/activities/activity node exists in
   the presentity for presentity_uri.

   This function can be used from ANY_ROUTE.

   Return code:
     * 1 - if a match is found.
     * -1 - if a match is not found.
     * -2 - if /presence/person or /presence/person/activity do not exist.

   Example 1.17. pres_check_activities usage
...
    if (pres_check_basic("$ru", "open")) {
        pres_check_activities("$ru", "unknown");
        if ($retcode || $retcode == -2 || !is_method("INVITE"))
            t_relay();
        else
            send_reply("486", "Busy Here");
    } else {
        ...
    }
...

5. Installation

   The module requires one table in Kamailio database: “xcap”. The SQL
   syntax to create it 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,
   https://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.

Chapter 2. Developer Guide

   The module exports no function to be used in other Kamailio modules.