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. Dependencies
1.2.1. OpenSER Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. db_url(str)
1.3.2. presentity_table(str)
1.3.3. active_watchers_table(str)
1.3.4. watchers_table(str)
1.3.5. clean_period (int)
1.3.6. to_tag_pref (str)
1.3.7. expires_offset (int)
1.3.8. max_expires (int)
1.3.9. server_address (str)
1.3.10. fallback2db (int)
1.3.11. subs_htable_size (int)
1.3.12. pres_htable_size (int)
1.4. Exported Functions
1.4.1. handle_publish(char* sender_uri)
1.4.2. handle_subscribe()
1.5. Exported MI Functions
1.5.1. refreshWatchers
1.6. Installation
2. Developer's Guide
2.1. bind_presence(presence_api_t* api)
2.2. add_event
2.3. get_rules_doc
2.4. get_auth_status
2.5. apply_auth_nbody
2.6. agg_nbody
2.7. free_body
2.8. evs_publ_handl
2.9. evs_subs_handl
2.10. contains_event
2.11. get_event_list
2.12. update_watchers_status
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 clean_period parameter
1-6. Set to_tag_pref parameter
1-7. Set expires_offset parameter
1-8. Set max_expires parameter
1-9. Set server_address parameter
1-10. Set fallback2db parameter
1-11. Set subs_htable_size parameter
1-12. Set pres_htable_size parameter
1-13. handle_publish usage
1-14. handle_subscribe usage
2-1. presence_api_t structure
__________________________________________________________
Chapter 1. User's Guide
1.1. Overview
The Presence module implements the core functionality of SIP
event notification. It handles PUBLISH and SUBSCRIBE messages
and generates NOTIFY messages in a general, event independent
way. It is extensible and allows registering events to it from
other OpenSER modules. Supported SIP event packages are
presence, presence.winfo, dialog;sla from the presence_xml
module and message-summary from the presence_mwi module.
The module uses database storage and memory caching (to improve
performance). The SIP SUBSCRIBE dialog information is stored in
memory and is periodically updated in the database, while for
PUBLISH only the presence or absence of stored info for a
certain resource is maintained in memory to avoid unnecessary,
costly database operations. It is possible to disable in-memory
caching by configurng a fallback to database mode (by setting
module parameter "fallback2db"). In this mode, in case a
searched record is not found in cache, the search is continued
in database. This is useful for an architecture in which
processing and memory load might be divided on several OpenSER
instances, maybe on different servers using the same database.
The module implements several API functions, that can be used
by other modules. In fact, it can be used only as a resource
module, or "library". This mode of operation is enabled if the
db_url parameter is not set to any value.
The OpenSER Presence module implements the specifications in:
RFC3265, RFC3856, RFC3857, RFC3858.
__________________________________________________________
1.2. Dependencies
1.2.1. OpenSER Modules
The following modules must be loaded before this module:
* a database module.
* sl.
* tm.
__________________________________________________________
1.2.2. External Libraries or Applications
* libxml.
__________________________________________________________
1.3. Exported Parameters
1.3.1. db_url(str)
The database url.
If set, the module is a fully operational presence server.
Otherwise, it is used as a 'library', for its exported
functions.
Default value is "NULL".
Example 1-1. Set db_url parameter
...
modparam("presence", "db_url",
"mysql://openser:openserrw@192.168.2.132/openser")
...
__________________________________________________________
1.3.2. presentity_table(str)
The name of the db table where PUBLISH presence information is
stored.
Default value is "presentity".
Example 1-2. Set presentity_table parameter
...
modparam("presence", "presentity_table", "presentity");
...
__________________________________________________________
1.3.3. active_watchers_table(str)
The name of the db table where active subscription information
is stored.
Default value is "active_watchers".
Example 1-3. Set active_watchers_table parameter
...
modparam("presence", "active_watchers_table", "active_watchers")
...
__________________________________________________________
1.3.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.3.5. clean_period (int)
The period between checks if there are expired messages stored
in database.
Default value is "100".
Example 1-5. Set clean_period parameter
...
modparam("presence", "clean_period", 100)
...
__________________________________________________________
1.3.6. to_tag_pref (str)
The prefix used when generating to_tag when sending replies for
SUBSCRIBE requests.
Default value is "10".
Example 1-6. Set to_tag_pref parameter
...
modparam("presence", "to_tag_pref", 'pres')
...
__________________________________________________________
1.3.7. 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-7. Set expires_offset parameter
...
modparam("presence", "expires_offset", 10)
...
__________________________________________________________
1.3.8. max_expires (int)
The the maximum admissible expires value for PUBLISH/SUBSCRIBE
message.
Default value is "3600".
Example 1-8. Set max_expires parameter
...
modparam("presence", "max_expires", 3600)
...
__________________________________________________________
1.3.9. server_address (str)
The presence server address which will become the value of
Contact header filed for 200OK replies to Subscribe and Publish
and in Notify messages.
Example 1-9. Set server_address parameter
...
modparam("presence", "server_address", "sip:10.10.10.10:5060")
...
__________________________________________________________
1.3.10. fallback2db (int)
Setting this parameter enables a fallback to db mode of
operation. In this mode, in case a searched record is not found
in cache, the search is continued in database. Useful for an
architecture in which processing and memory load might be
divided on more servers using the same database.
Example 1-10. Set fallback2db parameter
...
modparam("presence", "fallback2db", 1)
...
__________________________________________________________
1.3.11. subs_htable_size (int)
The size of the in-memory hash table to store subscription
dialogs. This parameter will be used as the power of 2 when
computing table size.
Default value is "9 (512)".
Example 1-11. Set subs_htable_size parameter
...
modparam("presence", "subs_htable_size", 11)
...
__________________________________________________________
1.3.12. pres_htable_size (int)
The size of the hash table to store publish records. This
parameter will be used as the power of 2 when computing table
size.
Default value is "9 (512)".
Example 1-12. Set pres_htable_size parameter
...
modparam("presence", "pres_htable_size", 11)
...
__________________________________________________________
1.4. Exported Functions
1.4.1. handle_publish(char* sender_uri)
Handles PUBLISH requests by storing and updating published
information in memory cach and database, then calls functions
to send NOTIFY messages when changes in the published
information occur. It takes one argument -> sender_uri. The
parameter was added for enabling BLA implementation. If
present, Notification of a change in published state is not
sent to the respective uri even though a subscription exists.
It should be taken from the Sender header. It was left at the
decision of the administrator whether or not to transmit the
content of this header as parameter for handle_publish, to
prevent security problems.
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(is_method("PUBLISH"))
{
if($hdr(Sender)!= NULL)
handle_publish("$hdr(Sender)");
else
handle_publish();
t_release();
}
...
__________________________________________________________
1.4.2. handle_subscribe()
The function which handles SUBSCRIBE requests. It stores or
updates information in memory and 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.5. Exported MI Functions
1.5.1. refreshWatchers
Triggers sending Notify messages to watchers if a change in
watchers authorization or in published state occurred.
Name: refreshWatchers
Parameters:
* presentity_uri : the uri of the user who made the change
and whose watchers should be informed
* event : the event package
* refresh type : it distinguishes between the two different
types of events that can trigger a refresh:
+ a change in watchers authentication: refresh type= 0 ;
+ a statical update in published state (either through
direct update in db table or by modifying the pidf
manipulation document, if pidf_manipulation parameter
is set): refresh type!= 0.
MI FIFO Command Format:
:refreshWatchers:fifo_reply
sip:11@192.168.2.132
presence
1
_empty_line_
__________________________________________________________
1.6. Installation
The module requires 3 tables in the OpenSER database:
"presentity", "active_watchers" and "watchers". The SQL syntax
to create them can be found in presence-create.sql script in
the database directories in the openser/scripts folder. You can
also find the complete database documentation on the project
webpage,
http://www.openser.org/docs/db-tables/openser-db-devel.html.
__________________________________________________________
Chapter 2. Developer's Guide
The module provides the following functions that can be used in
other OpenSER modules.
__________________________________________________________
2.1. bind_presence(presence_api_t* api)
This function binds the presence modules and fills the
structure with one exported function -> add_event, which when
called adds a new event to be handled by presence.
Example 2-1. presence_api_t structure
...
typedef struct presence_api {
add_event_t add_event;
contains_event_t contains_event;
search_event_t search_event;
get_event_list_t get_event_list;
update_watchers_t update_watchers_status;
/* subs hash table handling functions */
new_shtable_t new_shtable;
destroy_shtable_t destroy_shtable;
insert_shtable_t insert_shtable;
search_shtable_t search_shtable;
delete_shtable_t delete_shtable;
update_shtable_t update_shtable;
/* function to duplicate a subs structure*/
mem_copy_subs_t mem_copy_subs;
/* function used for update in database*/
update_db_subs_t update_db_subs;
/* function to extract dialog information from a
SUBSCRIBE message */
extract_sdialog_info_t extract_sdialog_info;
}presence_api_t;
...
__________________________________________________________
2.2. add_event
Field type:
...
typedef int (*add_event_t)(pres_ev_t* event);
...
This function receives as a parameter a structure with event
specific information and adds it to presence event list.
The structure received as a parameter:
...
typedef struct pres_ev
{
str name;
event_t* evp;
str content_type;
int default_expires;
int type;
int etag_not_new;
/*
* 0 - the standard mechanism (allocating new etag
for each Publish)
* 1 - allocating an etag only
for an initial Publish
*/
int req_auth;
get_rules_doc_t* get_rules_doc;
apply_auth_t* apply_auth_nbody;
is_allowed_t* get_auth_status;
/* an agg_body_t function should be registered
* if the event permits having multiple published
* states and requires an aggregation of the information
* otherwise, this field should be NULL and the last
* published state is taken when constructing Notify msg
*/
agg_nbody_t* agg_nbody;
publ_handling_t * evs_publ_handl;
subs_handling_t * evs_subs_handl;
free_body_t* free_body;
struct pres_ev* wipeer;
struct pres_ev* next;
}pres_ev_t;
...
__________________________________________________________
2.3. get_rules_doc
Filed type:
...
typedef int (get_rules_doc_t)(str* user, str* domain, str** rules_doc);
...
This function returns the authorization rules document that
will be used in obtaining the status of the subscription and
processing the notified body. A reference to the document
should be put in the auth_rules_doc of the subs_t structure
given as a parameter to the functions described bellow.
__________________________________________________________
2.4. get_auth_status
This filed is a function to be called for a subscription
request to return the state for that subscription according to
authorization rules. In the auth_rules_doc field of the subs_t
structure received as a parameter should contain the rules
document of the presentity in case, if it exists.
It is called only if the req_auth field is not 0.
Filed type:
...
typedef int (is_allowed_t)(struct subscription* subs);
...
__________________________________________________________
2.5. apply_auth_nbody
This parameter should be a function to be called for an event
that requires authorization, when constructing final body. The
authorization document is taken from the auth_rules_doc field
of the subs_t structure given as a parameter. It is called only
if the req_auth field is not 0.
Filed type:
...
typedef int (apply_auth_t)(str* , struct subscription*, str** );
...
__________________________________________________________
2.6. agg_nbody
If present, this field marks that the events requires
aggregation of states. This function receives a body array and
should return the final body. If not present, it is considered
that the event does not require aggregation and the most recent
published information is used when constructing Notifies.
Filed type:
...
typedef str* (agg_nbody_t)(str* pres_user, str* pres_domain,
str** body_array, int n, int off_index);
..
__________________________________________________________
2.7. free_body
This field must be field in if subsequent processing is
performed on the info from database before being inserted in
Notify message body(if agg_nbody or apply_auth_nbody fields are
filled in). It should match the allocation function used when
processing the body.
Filed type:
...
typedef void(free_body_t)(char* body);
..
__________________________________________________________
2.8. evs_publ_handl
This function is called when handling Publish requests. Most
contain body correctness check.
...
typedef int (publ_handling_t)(struct sip_msg*);
..
__________________________________________________________
2.9. evs_subs_handl
It is not compulsory. Should contain event specific handling
for Subscription requests.
Filed type:
...
typedef int (subs_handling_t)(struct sip_msg*);
..
__________________________________________________________
2.10. contains_event
Field type:
..
typedef pres_ev_t* (*contains_event_t)(str* name,
event_t* parsed_event);
...
The function parses the event name received as a parameter and
searches the result in the list. It returns the found event or
NULL, if not found. If the second argument is an allocated
event_t* structure it fills it with the result of the parsing.
__________________________________________________________
2.11. get_event_list
Field type:
...
typedef int (*get_event_list_t) (str** ev_list);
...
This function returns a string representation of the events
registered in presence module.( used for Allowed-Events
header).
__________________________________________________________
2.12. update_watchers_status
Field type:
...
typedef int (*update_watchers_t)(str pres_uri, pres_ev_t* ev,
str* rules_doc);
...
This function is an external command that can be used to
announce a change in authorization rules for a presentity. It
updates the stored status and sends a Notify to the watchers
whose status has changes. (used by presence_xml module when
notified through an MI command of a change in an xcap
document).
__________________________________________________________
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.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://lists.openser.org/cgi-bin/mailman/listinfo/users
* Developer Mailing List -
http://lists.openser.org/cgi-bin/mailman/listinfo/devel
E-mails regarding any stable OpenSER release should be sent to
<users@lists.openser.org> and e-mails regarding development
versions should be sent to <devel@lists.openser.org>.
If you want to keep the mail private, send it to
<team@lists.openser.org>.
3.3. How can I report a bug?
Please follow the guidelines provided at:
http://sourceforge.net/tracker/?group_id=139143.
