
Presence User Agent 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. 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 ex
pires*/
  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?

   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.
