
Presence Module

Anca-Maria Vamanu

   voice-system.ro

Edited by

Anca-Maria Vamanu

   Copyright  2006 voice-system.ro
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. To-do
        1.3. Dependencies

              1.3.1. OpenSER Modules
              1.3.2. External Libraries or Applications

        1.4. Exported Parameters

              1.4.1. db_url(str)
              1.4.2. presentity_table(str)
              1.4.3. active_watchers_table(str)
              1.4.4. watchers_table(str)
              1.4.5. xcap_table(str)
              1.4.6. clean_period (int)
              1.4.7. to_tag_pref (str)
              1.4.8. lock_set_size (int)
              1.4.9. expires_offset (int)
              1.4.10. force_active (int)
              1.4.11. max_expires (int)
              1.4.12. server_address (str)

        1.5. Exported Functions

              1.5.1. handle_publish()
              1.5.2. handle_subscribe()

        1.6. Installation

   2. Developer's Guide
   3. Frequently Asked Questions

   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 xcap_table parameter
   1-6. Set clean_period parameter
   1-7. Set to_tag_pref parameter
   1-8. Set lock_set_size parameter
   1-9. Set expires_offset parameter
   1-10. Set force_active parameter
   1-11. Set max_expires parameter
   1-12. Set server_address parameter
   1-13. handle_publish usage
   1-14. handle_subscribe usage
   1-15. PRESENCE tables
     _________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   The modules implements a presence server. It handles PUBLISH
   and SUBSCRIBE messages and generates NOTIFY messages. It
   offers support for aggregation of published presence
   information for the same presentity using more devices. It can
   also filter the information provided to watchers according to
   privacy rules.

   The modules works with database storage. It stores published
   information and Subscribe -Notify dialog characteristics.
   There is also an extra table which stores xcap documents with
   permission rules.

   The server follows the specifications in: RFC3265, RFC3856,
   RFC3857, RFC3858.
     _________________________________________________________

1.2. To-do

   Provide support for clients which implement end-to-end
   presence.
     _________________________________________________________

1.3. Dependencies

1.3.1. OpenSER Modules

   The following modules must be loaded before this module:

     * a database module.
     * sl.
     * tm.
     _________________________________________________________

1.3.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSER with this module loaded:

     * libxml.
     _________________________________________________________

1.4. Exported Parameters

1.4.1. db_url(str)

   The database url.

   Default value is "NULL". 

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

1.4.2. presentity_table(str)

   The name of the db table where Publish information are stored.

   Default value is "presentity". 

   Example 1-2. Set presentity_table parameter
...
modparam("presence", "presentity_table", "presentity");
...
     _________________________________________________________

1.4.3. active_watchers_table(str)

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

   Default value is "active_watchers". 

   Example 1-3. Set active_watchers_table parameter
...
modparam("presence", "active_watchers_table", "active_watchers")
...
     _________________________________________________________

1.4.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.4.5. xcap_table(str)

   The name of the db table where XCAP XMLs are stored.

   Default value is "scap_xml". 

   Example 1-5. Set xcap_table parameter
...
modparam("presence", "xcap_table", "xcaps")
...
     _________________________________________________________

1.4.6. clean_period (int)

   The period at which to verify if there are expired messages
   stored in database.

   Default value is "100". 

   Example 1-6. Set clean_period parameter
...
modparam("presence", "clean_period", 100)
...
     _________________________________________________________

1.4.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", 'a')
...
     _________________________________________________________

1.4.8. lock_set_size (int)

   The size of the lock used for synchronizing updating
   information from database.

   Default value is "8". 

   Example 1-8. Set lock_set_size parameter
...
modparam("presence", "lock_set_size", 8)
...
     _________________________________________________________

1.4.9. expires_offset (int)

   The value 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-9. Set expires_offset parameter
...
modparam("presence", "expires_offset", 10)
...
     _________________________________________________________

1.4.10. 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. Otherwise,
   the xcap_table is queried and the state is extracted from
   there. If no record exists, the subscriptions remains in
   pending state and the watcher receives Notify messages with no
   body. ( If not using an xcap server, you should set this
   parameter to 1).

   Default value is "0". 

   Example 1-10. Set force_active parameter
...
modparam("presence", "force_active", 1)
...
     _________________________________________________________

1.4.11. max_expires (int)

   The the maximum admissible expires value for PUBLISH/SUBSCRIBE
   message.

   Default value is "3600". 

   Example 1-11. Set max_expires parameter
...
modparam("presence", "max_expires", 3600)
...
     _________________________________________________________

1.4.12. server_address (str)

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

   Example 1-12. Set server_address parameter
...
modparam("presence", "server_address", "sip:10.10.10.10:5060")
...
     _________________________________________________________

1.5. Exported Functions

1.5.1. handle_publish()

   The function handles PUBLISH requests. It stores and updates
   presence information in database and calls functions to send
   NOTIFY messages when changes in presence information occur.

   This function can be used from REQUEST_ROUTE.

   Example 1-13. handle_publish usage
...
if(method=="PUBLISH")
    handle_publish();
...
     _________________________________________________________

1.5.2. handle_subscribe()

   The function which handles SUBSCRIBE requests. It stores or
   updates information in 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.

   Example 1-14. handle_subscribe usage
...
if(method=="SUBSCRIBE")
    handle_subscribe();
...
     _________________________________________________________

1.6. Installation

   The module requires 4 table in OpenSER database. Next SQL
   statements shows the syntax to create them.

   Example 1-15. PRESENCE tables
...

use openser;

CREATE TABLE `presentity` (
  `id` int(10) NOT NULL auto_increment,
  `username` varchar(64) NOT NULL,
  `domain` varchar(124) NOT NULL,
  `event` varchar(64) NOT NULL,
  `etag` varchar(64) NOT NULL,
  `expires` int(11) NOT NULL,
  `received_time` int(11) NOT NULL,
  `body` text NOT NULL,
  UNIQUE KEY udee_presentity (`username`,`domain`,`event`,`etag`),
  PRIMARY KEY (id)
) ENGINE=MyISAM;

CREATE TABLE `active_watchers` (
  `id` int(10) NOT NULL auto_increment,
  `to_user` varchar(64) NOT NULL,
  `to_domain` varchar(128) NOT NULL,
  `from_user` varchar(64) NOT NULL,
  `from_domain` varchar(128) NOT NULL,
  `event` varchar(64) NOT NULL default 'presence',
  `event_id` varchar(64),
  `to_tag` varchar(128) NOT NULL,
  `from_tag` varchar(128) NOT NULL,
  `callid` varchar(128) NOT NULL,
  `cseq` int(11) NOT NULL,
  `contact` varchar(128) NOT NULL,
  `record_route` varchar(255),
  `expires` int(11) NOT NULL,
  `status` varchar(32) NOT NULL default 'pending',
  `version` int(11) default '0',
  `socket_info` varchar(128) NOT NULL,
  `local_contact` varchar(255) NOT NULL,
  PRIMARY KEY  (`id`),
  UNIQUE KEY `tt_watchers` (`to_tag`),
  KEY `due_activewatchers` (`to_domain`,`to_user`,`event`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1 AUTO_INCREMENT=1 ;


CREATE TABLE `watchers` (
  `id` int(10) NOT NULL auto_increment,
  `p_user` varchar(64) NOT NULL,
  `p_domain` varchar(128) NOT NULL,
  `w_user` varchar(64) NOT NULL,
  `w_domain` varchar(128) NOT NULL,
  `subs_status` varchar(64) NOT NULL,
  `reason` varchar(64),
  `inserted_time` int(11) NOT NULL,
  UNIQUE KEY udud_watchers (`p_user`,`p_domain`,`w_user`,`w_domain`),
  PRIMARY KEY (id)
) ENGINE=MyISAM;



CREATE TABLE `xcap_xml` (
  `id` int(10) NOT NULL auto_increment,
  `username` varchar(66) NOT NULL,
  `domain` varchar(128) NOT NULL,
  `xcap` text NOT NULL,
  `doc_type` int(11) NOT NULL,
  UNIQUE KEY udd_xcap (`username`,`domain`,`doc_type`),
  PRIMARY KEY (id)
) ENGINE=MyISAM;

...
     _________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     _________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about OpenSER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.2. Where can I post a question about this module?

   First at all check if your question was already answered on
   one of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.
