Presence User Agent Module

Anca-Maria Vamanu

Edited by

Anca-Maria Vamanu


Table of Contents
1. User's Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSER Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. hash_size (int)
1.3.2. db_url (str)
1.3.3. db_table (str)
1.3.4. min_expires (int)
1.3.5. default_expires (int)
1.3.6. update_period (int)
1.4. Exported Functions
1.5. Installation
2. Developer's Guide
2.1. bind_pua(pua_api_t* api)
2.2. send_publish(publ_info_t*)
2.3. send_subscribe(subs_info_t*)
3. Frequently Asked Questions
List of Examples
1-1. Set hash_size parameter
1-2. Set db_url parameter
1-3. Set db_table parameter
1-4. Set min_expires parameter
1-5. Set default_expires parameter
1-6. Set update_period parameter
1-7. PUA tables
2-1. pua_api structure

Chapter 1. User's Guide

1.1. Overview

This module offer the functionality of a presence user agent client, sending Subscribe and Publish messages.

Now it can be used with the following modules: pua_mi and pua_usrloc. The pua_mi offer the possiblity to publish any kind of information or subscribing to a resource through fifo. The pua_usrloc module calls a function exported by pua modules to publish elementary presence information, such as basic status "open" or "closed", for clients that do not implement client-to-server presence.

The module use cache to store presentity list and writes to database on timer to be able to recover upon restart.


1.2. Dependencies

1.2.1. OpenSER Modules

The following modules must be loaded before this module:

  • a database modules.

  • tm.


1.2.2. External Libraries or Applications

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

  • libxml.


1.3. Exported Parameters

1.3.1. hash_size (int)

The size of the hash table used for storing Subscribe and Publish information.

Default value is "4".

Example 1-1. Set hash_size parameter

...
modparam("pua", "hash_size", 9)
...

1.3.2. db_url (str)

Database url.

Default value is "NULL".

Example 1-2. Set db_url parameter

...
modparam("pua", "db_url" 
		"mysql://openser:openserrw@192.168.2.132/openser")
...

1.3.3. db_table (str)

The name of the database table.

Default value is "pua".

Example 1-3. Set db_table parameter

...
modparam("pua", "db_table", "pua")
...

1.3.4. min_expires (int)

The inferior expires limit for both Publish and Subscribe.

Default value is "0".

Example 1-4. Set min_expires parameter

...
modparam("pua", "min_expires", 0)
...

1.3.5. default_expires (int)

The default expires value used in case this information is not provisioned.

Default value is "3600".

Example 1-5. Set default_expires parameter

...
modparam("pua", "default_expires", 3600)
...

1.3.6. update_period (int)

The interval at which the information in database and hash table should be updated. In the case of the hash table updating is deleting expired messages.

Default value is "30".

Example 1-6. Set update_period parameter

...
modparam("pua", "update_period", 100)
...

1.4. Exported Functions

No function exported to be used in configuration script.


1.5. Installation

The module requires a new table in OpenSER database. Next SQL statement shows the syntax to create it.

Example 1-7. PUA tables

...

use openser;

CREATE TABLE pua (
  id int(10) unsigned NOT NULL auto_increment,
  pres_uri varchar(128) NOT NULL,
  pres_id varchar(128) NOT NULL,
  expires int(11) NOT NULL,
  flag int(11) NOT NULL,
  etag varchar(128) NOT NULL,
  tuple_id varchar(128) NOT NULL,
  watcher_uri varchar(128) NOT NULL,
  call_id varchar(128) NOT NULL,
  to_tag varchar(128) NOT NULL,
  from_tag varchar(128) NOT NULL,
  cseq int(11) NOT NULL,
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM;


...

Chapter 2. Developer's Guide

The module provides the following functions that can be used in other OpenSER modules.


2.1. bind_pua(pua_api_t* api)

This function binds the pua modules and fills the structure with the two exported function.

Example 2-1. pua_api structure

...
typedef struct pua_api {
	send_subscribe_t send_subscribe;
	send_publish_t send_publish;
} pua_api_t;
...

2.2. send_publish(publ_info_t*)

This function receives as a parameter a structure with Publish required information and sends a Publish message.

The structure received as a parameter:

...
typedef struct publ_info
{
  str id;            /*  an id value unique for one combination of 
                      *  pres_uri and flag */
  str* pres_uri;	 /*  the presentity uri */	
  str* body;		 /*  the body of the Publish message; 
                      *  can be NULL in case of an update */ 	
  time_t expires;	 /*  the absolute value at which the message expires*/	
  int flag;	         /*  it can be : INSERT_TYPE or UPDATE_TYPE
                      *  if missing it will be established according 
                      *  to the result of the search in hash table*/ 	
  int source_flag;   /*  flag identifying the resource ;
                      *  used values: UL_PUBLISH, MI_PUBLISH,
                      *  MI_SUBSCRIBE */
}publ_info_t;
...
		


2.3. send_subscribe(subs_info_t*)

This function receives as a parameter a structure with Susbcribe required information and sends a Subscribe message.

...
The structure received as a parameter:
typedef struct subs_info
{
  str id;            /*  an id value unique for one combination
                      * of pres_uri and flag */
  str* pres_uri;     /*  the presentity uri */	
  str* watcher_uri;  /*  the watcher uri */
  time_t expires;    /*  the absolute value at which the message
						  expires */	
  int flag;          /*  it can be : INSERT_TYPE or UPDATE_TYPE
                      *  not compulsory */	
  int source_flag;   /*  flag identifying the resource ;
                      *  used values: UL_PUBLISH, MI_PUBLISH,
                      * MI_SUBSCRIBE */
}subs_info_t;
...


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?

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.