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.

Return code:

  • 1 - if success.

  • -1 - if error.

The module sends an appropriate stateless reply in all cases.

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.

Return code:

  • 1 - if success.

  • -1 - if error.

The module sends an appropriate stateless reply in all cases.

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,
  `remote_cseq` int(11) NOT NULL,
  `local_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',
  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://www.openser-project.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:

E-mails regarding any stable OpenSER release should be sent to and e-mails regarding development versions should be sent to .

If you want to keep the mail private, send it to .

3.3. How can I report a bug?

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