modules_k/presence_xml/README
b7a0db74
 Presence_XML Module
 
 Anca-Maria Vamanu
 
d9bb387b
    Voice Sistem SRL
b7a0db74
 
 Edited by
 
 Anca-Maria Vamanu
 
d9bb387b
    Copyright © 2007 Voice Sistem SRL
dd78db27
      __________________________________________________________________
b7a0db74
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
b7a0db74
 
dd78db27
         1. Overview
         2. Dependencies
b7a0db74
 
dd78db27
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
b7a0db74
 
dd78db27
         3. Exported Parameters
b7a0db74
 
dd78db27
               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. force_active (int)
               3.7. pidf_manipulation (int)
               3.8. integrated_xcap_server (int)
               3.9. xcap_server (str)
986c26b7
               3.10. passive_mode(int)
b7a0db74
 
dd78db27
         4. Exported Functions
         5. Installation
986c26b7
         6. Exported pseudo-variables
b7a0db74
 
9fc784c6
    2. Developer Guide
b7a0db74
 
    List of Examples
d77df08a
 
    1.1. Set db_url parameter
    1.2. Set xcap_table parameter
8a3f29f8
    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
986c26b7
    1.10. Set passive_mode parameter
b7a0db74
 
9fc784c6
 Chapter 1. Admin Guide
b7a0db74
 
dd78db27
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
    3. Exported 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. force_active (int)
         3.7. pidf_manipulation (int)
         3.8. integrated_xcap_server (int)
         3.9. xcap_server (str)
986c26b7
         3.10. passive_mode(int)
dd78db27
 
    4. Exported Functions
    5. Installation
986c26b7
    6. Exported pseudo-variables
b7a0db74
 
dd78db27
 1. Overview
b7a0db74
 
dd78db27
    The module does specific handling for notify-subscribe events using xml
    bodies. It is used with the general event handling module, presence. It
57d99f46
    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.
b7a0db74
 
dd78db27
    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.
b7a0db74
 
dd78db27
 2. Dependencies
 
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
b7a0db74
 
    The following modules must be loaded before this module:
      * a database module.
      * presence.
      * sl.
7532087a
      * xcap_client.
        Only compulsory if not using an integrated xcap server (if
        'integrated_xcap_server' parameter is not set).
b7a0db74
 
dd78db27
 2.2. External Libraries or Applications
b7a0db74
 
dd78db27
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
b7a0db74
      * libxml.
 
dd78db27
 3. Exported 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. force_active (int)
    3.7. pidf_manipulation (int)
    3.8. integrated_xcap_server (int)
    3.9. xcap_server (str)
986c26b7
    3.10. passive_mode(int)
b7a0db74
 
dd78db27
 3.1. db_url(str)
b7a0db74
 
1298a756
    The database URL.
b7a0db74
 
5d5f3422
    Default value is “mysql://openser:openserrw@localhost/openser”.
b7a0db74
 
d77df08a
    Example 1.1. Set db_url parameter
b7a0db74
 ...
dd78db27
 modparam("presence_xml", "db_url", "dbdriver://username:password@dbhost/dbname")
b7a0db74
 ...
 
dd78db27
 3.2. xcap_table(str)
b7a0db74
 
dd78db27
    The name of the database table where XCAP documents are stored.
b7a0db74
 
5d5f3422
    Default value is “xcap”.
b7a0db74
 
d77df08a
    Example 1.2. Set xcap_table parameter
b7a0db74
 ...
 modparam("presence_xml", "xcap_table", "xcaps")
 ...
 
dd78db27
 3.3. disable_presence(int)
8a3f29f8
 
dd78db27
    Set this parameter to disable the handling of the "presence" event.
8a3f29f8
 
5d5f3422
    Default value: “0”.
8a3f29f8
 
    Example 1.3. Set disable_presence parameter
 ...
 modparam("presence_xml", "disable_presence", 1)
 ...
 
dd78db27
 3.4. disable_winfo(int)
8a3f29f8
 
dd78db27
    Set this parameter to disable the handling of the "presence.winfo"
    event.
8a3f29f8
 
5d5f3422
    Default value: “0”.
8a3f29f8
 
    Example 1.4. Set disable_winfo parameter
 ...
 modparam("presence_xml", "disable_winfo", 1)
 ...
 
dd78db27
 3.5. disable_bla(int)
8a3f29f8
 
dd78db27
    Set this parameter to disable the handling of the "dialog;sla" event.
8a3f29f8
 
5d5f3422
    Default value: “1” (0 - enabled, 1 - disabled).
8a3f29f8
 
    Example 1.5. Set disable_bla parameter
 ...
 modparam("presence_xml", "disable_bla", 1)
 ...
 
dd78db27
 3.6. force_active (int)
b7a0db74
 
    This parameter is used for permissions when handling Subscribe
dd78db27
    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.
7532087a
 
dd78db27
    Note: When switching from one value to another, the watchers table must
    be emptied.
b7a0db74
 
5d5f3422
    Default value is “0”.
b7a0db74
 
8a3f29f8
    Example 1.6. Set force_active parameter
b7a0db74
 ...
 modparam("presence_xml", "force_active", 1)
 ...
 
dd78db27
 3.7. pidf_manipulation (int)
a1776eca
 
dd78db27
    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).
a1776eca
 
5d5f3422
    Default value is “0”.
a1776eca
 
8a3f29f8
    Example 1.7. Set pidf_manipulation parameter
a1776eca
 ...
 modparam("presence_xml", "pidf_manipulation", 1)
 ...
 
dd78db27
 3.8. integrated_xcap_server (int)
7532087a
 
dd78db27
    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.
7532087a
 
dd78db27
    Otherwise, it uses xcap_client module to fetch documents from the XCAP
    servers with HTTP requests. This mode is currently not supported.
7532087a
 
5d5f3422
    Default value is “0”.
7532087a
 
8a3f29f8
    Example 1.8. Set integrated_xcap_server parameter
7532087a
 ...
 modparam("presence_xml", "integrated_xcap_server", 1)
 ...
 
dd78db27
 3.9. xcap_server (str)
7532087a
 
dd78db27
    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.
7532087a
 
8a3f29f8
    Example 1.9. Set xcap_server parameter
7532087a
 ...
 modparam("presence_xml", "xcap_server", "xcap_server.example.org")
 modparam("presence_xml", "xcap_server", "xcap_server.ag.org")
 ...
 
986c26b7
 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(...)
    pseudoc-variable.
 
5d5f3422
    Default value: “0” (0 - active mode, 1 - passive mode).
986c26b7
 
    Example 1.10. Set passive_mode parameter
 ...
 modparam("presence_xml", "passive_mode", 1)
 ...
 
dd78db27
 4. Exported Functions
b7a0db74
 
    None to be used in configuration file.
 
dd78db27
 5. Installation
b7a0db74
 
5d5f3422
    The module requires one table in Kamailio database: “xcap”. The SQL
dd78db27
    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,
873d51d6
    http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
b7a0db74
 
986c26b7
 6. Exported pseudo-variables
 
      * $xml(name=>spec)
 
    Exported pseudo-variables are documented at
    http://www.kamailio.org/dokuwiki/.
 
9fc784c6
 Chapter 2. Developer Guide
b7a0db74
 
dd78db27
    The module exports no function to be used in other Kamailio modules.