Presence_XML Module

Anca-Maria Vamanu

   voice-system.ro

Edited by

Anca-Maria Vamanu

   Copyright © 2007 voice-system.ro
   Revision History
   Revision $Revision: 1499 $ $Date: 2007-01-12 14:05:57 +0200
                              (Fri, 12 Jan 2007) $
     __________________________________________________________

   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. xcap_table(str)
              1.3.3. disable_presence(int)
              1.3.4. disable_winfo(int)
              1.3.5. disable_bla(int)
              1.3.6. force_active (int)
              1.3.7. pidf_manipulation (int)
              1.3.8. integrated_xcap_server (int)
              1.3.9. xcap_server (str)

        1.4. Exported Functions
        1.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 force_active parameter
   1.7. Set pidf_manipulation parameter
   1.8. Set integrated_xcap_server parameter
   1.9. Set xcap_server parameter

Chapter 1. Admin Guide

1.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 - Bridged Line Appearances (BLA):
       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.

1.2. Dependencies

1.2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * a database module.
     * presence.
     * sl.
     * xcap_client.
       Only compulsory if not using an integrated xcap server (if
       'integrated_xcap_server' parameter is not set).

1.2.2. External Libraries or Applications

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

1.3. Exported Parameters

1.3.1. db_url(str)

   The database URL.

   Default value is "mysql://openser:openserrw@localhost/openser".

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

1.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")
...

1.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)
...

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)
...

1.3.5. disable_bla(int)

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

   Default value: "1".

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

1.3.6. 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.6. Set force_active parameter
...
modparam("presence_xml", "force_active", 1)
...

1.3.7. pidf_manipulation (int)

   Setting this parameter to 1 enables the features described in
   RFC 4827. It gives the possibility to have a permanent state
   notified to the users even in the case in which the phone is
   not online. The presence document is taken from the XCAP server
   and aggregated together with the other presence information, if
   any exist, for each Notify that is sent to the watchers. It is
   also possible to have information notified even if not issuing
   any Publish (useful for services such as email, SMS, MMS).

   Default value is "0".

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

1.3.8. integrated_xcap_server (int)

   This parameter is a flag for the type of XCAP server or servers
   used. If the XCAP server is integrated with Kamailio
   presence_XML module and access the same database tables
   directly, like the XCAP-lite server from AG Projects, the
   parameter should be set to a positive value. Apart from
   updating in xcap table, the integrated server must send an MI
   command refershWatchers [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, it uses xcap_client module to fetch documents from
   the XCAP servers with HTTP requests. This mode is currently not
   supported.

   Default value is "0".

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

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")
...

1.4. Exported Functions

   None to be used in configuration file.

1.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,
   http://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.
