# &adminguide;

## Overview

The modules handles PUBLISH and SUBSCRIBE messages and generates NOTIFY messages in a general, event independent way. It allows registering events to it from other &osips; modules. Events that can currently be added to it are: presence, presence.winfo, dialog;sla from presence_xml module and message-summary from presence_mwi module.

The modules uses database storage. It has later been improved with memory caching operations to improve performance. The Subscribe dialog information are stored in memory and are periodically updated in database, while for Publish only the presence or absence of stored info for a certain resource is maintained in memory to avoid unnecessary, costly db operations. It is possible to configure 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 more machines using the same database.

The module can also work only with the functionality of a library, with no message processing and generation, but used only for the exported functions. This mode of operation is enabled if the db_url parameter is not set to any value.

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

## Dependencies

### &osips; Modules

The following modules must be loaded before this module:

- a database module.

- signaling.

### External Libraries or Applications

- libxml-dev.

## Exported Parameters

### `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.

#### Set `db_url` parameter

    ...
    modparam("presence", "db_url",
    	"mysql://opensips:opensipsrw@192.168.2.132/opensips")
    ...

### `presentity_table`(str)

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

Default value is presentity.

#### Set `presentity_table` parameter

    ...
    modparam("presence", "presentity_table", "presentity")
    ...

### `active_watchers_table`(str)

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

Default value is active_watchers.

#### Set `active_watchers_table` parameter

    ...
    modparam("presence", "active_watchers_table", "active_watchers")
    ...

### `watchers_table`(str)

The name of the db table where subscription states are stored.

Default value is watchers.

#### Set `watchers_table` parameter

    ...
    modparam("presence", "watchers_table", "watchers")
    ...

### `clean_period` (int)

The period at which to clean the expired subscription dialogs.

Default value is 100. A zero or negative value disables this activity.

#### Set `clean_period` parameter

    ...
    modparam("presence", "clean_period", 100)
    ...

### `db_update_period` (int)

The period at which to synchronize cached subscriber info with the database.

Default value is 100. A zero or negative value disables synchronization.

#### Set `db_update_period` parameter

    ...
    modparam("presence", "db_update_period", 100)
    ...

### `expires_offset` (int)

The extra time to store a subscription/publication.

Default value is 0.

#### Set `expires_offset` parameter

    ...
    modparam("presence", "expires_offset", 10)
    ...

### `max_expires_subscribe` (int)

The the maximum admissible expires value for SUBSCRIBE messages.

Default value is 3600.

#### Set `max_expires_subscribe` parameter

    ...
    modparam("presence", "max_expires_subscribe", 3600)
    ...

### `max_expires_publish` (int)

The the maximum admissible expires value for PUBLISH messages.

Default value is 3600.

#### Set `max_expires_publish` parameter

    ...
    modparam("presence", "max_expires_publish", 3600)
    ...

### `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.

#### Set `server_address` parameter

    ...
    modparam("presence", "server_address", "sip:10.10.10.10:5060")
    ...

### `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 machines using the same database.

#### Set `fallback2db` parameter

    ...
    modparam("presence", "fallback2db", 1)
    ...

### `subs_htable_size` (int)

The size of the 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).

#### Set `subs_htable_size` parameter

    ...
    modparam("presence", "subs_htable_size", 11)
    ...

### `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).

#### Set `pres_htable_size` parameter

    ...
    modparam("presence", "pres_htable_size", 11)
    ...

### `enable_sphere_check` (int)

This parameter is a flag that should be set if permission rules include sphere checking. The sphere information is expected to be present in the RPID body published by the presentity. The flag is introduced as this check requires extra processing that should be avoided if this feature is not supported by the clients.

Default value is 0 .

#### Set `enable_sphere_check` parameter

    ...
    modparam("presence", "enable_sphere_check", 1)
    ...

### `waiting_subs_daysno` (int)

The number of days to keep the record of a subscription in server database if the subscription is in pending or waiting state (no authorization policy was defined for it or the target user did not register sice the subscription and was not informed about it).

Default value is 3 days. Maximum accepted value is 30 days.

#### Set `waiting_subs_daysno` parameter

    ...
    modparam("presence", "waiting_subs_daysno", 2)
    ...

### `mix_dialog_presence` (int)

This module parameter enables a very nice feature in the presence server - generating presence information from dialogs state. If this parameter is set, the presence server will tell you if a buddy is in a call even if his phone did not send a presence Publish with this information. You will need to load the dialoginfo modules, presence_dialoginfo, pua_dialoginfo, dialog and pua.

Default value is 0.

#### Set `mix_dialog_presence` parameter

    ...
    modparam("presence", "mix_dialog_presence", 1)
    ...

### `bla_presentity_spec` (str)

By default the presentity uri for BLA subscribes (event=dialog;sla) is computed from contact username + from domain. In some cases though, this way of computing the presentity might not be right ( for example if you have a SBC in front that masquerades the contact). So we added this parameter that allows defining a custom uri to be used as presentity uri for BLA subscribes. You should set this parameter to the name of a pseudovariable and then set this pseudovariable to the desired URI before calling the function handle_subscribe.

Default value is NULL.

#### Set `bla_presentity_spec` parameter

    ...
    modparam("presence", "bla_presentity_spec", "$var(bla_pres)")
    ...

### `bla_fix_remote_target` (int)

Polycom has a bug in the bla implementation. It inserts the remote IP contact in the Notify body and when a phone picks up a call put on hold by another phone in the same BLA group, it sends an Invite directly to the remote IP. OpenSIPS BLA server tries to prevent this by replacing the IP contact with the domain, when this is possible.

In some cases(configurations) however this is not desirable, so this parameter was introduced to disable this behaviour when needed.

Default value is 1.

#### Set `bla_fix_remote_target` parameter

    ...
    modparam("presence", "bla_fix_remote_target", 0)
    ...

### `notify_offline_body` (int)

If this parameter is set, when no published info is found for a user, the presence server will generate a dummy body with status 'closed' and use it when sending Notify, instead of notifying with no body.

Default value is 0.

#### Set `notify_offline_body` parameter

    ...
    modparam("presence", "notify_offline_body", 1)
    ...

### `end_sub_on_timeout` (int)

If a presence subscription should be automatically terminated (destroyed) when receiving a SIP timeout (408) for a sent NOTIFY requests.

Default value is 1 (enabled).

#### Set `end_sub_on_timeout` parameter

    ...
    modparam("presence", "end_sub_on_timeout", 0)
    ...

## Exported Functions

### `handle_publish(char* sender_uri)`

The function handles PUBLISH requests. It stores and updates published information in database and 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.

#### `handle_publish` usage

    ...
    	if(is_method("PUBLISH"))
    	{
    		if($hdr(Sender)!= NULL)
    			handle_publish("$hdr(Sender)");
    		else
    			handle_publish();
    	}
    ...

### `handle_subscribe(char* force_active)`

This function is to be used for handling SUBSCRIBE requests. It stores or updates the watcher/subscriber information in database. Additionally, in response to initial SUBSCRIBE requests (creating a new subscription session), the function also sends back the NOTIFY (with the presence information) to the wathcer/subscriber.

The function may take on parameter that controlls what is the default policy (of the presentity) on accepting new subscriptions (accept or reject) - of course, this parameter makes sense only when using a presence configuration with privacy rules enabled (force_active parameter in presence_xml module is not set).

There are scenarios where the presentity (the party you subscribe to) can not upload an XCAP document with it's privacy rules (to controll which watchers are allowed to subscribe to it). In such case, from script level, you can force the presence server to consider the current subscription allowed (with Subscription-Status:active) by calling handle_subscribe() function with the string parameter "1".

       Ex:
    	if(uri =~ "kphone@opensips.org")
    		handle_subscribe("1");

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.

#### `handle_subscribe` usage

    ...
    if(method=="SUBSCRIBE")
        handle_subscribe();
    ...

## Exported MI Functions

### `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_

### `cleanup`

Manually triggers the cleanup functions for watchers and presentity tables. Useful if you have set `clean_period` to zero or less.

Name: cleanup

Parameters:none.emphasis>

MI FIFO Command Format:

    :cleanup:fifo_reply
    _empty_line_

### `pres_phtable_list`

Lists all the presentity records.

Name: pres_phtable_list

Parameters:none.

MI FIFO Command Format:

    :pres_phtable_list:fifo_reply
    _empty_line_

### `subs_phtable_list`

Lists all the subscription records.

Name: subs_phtable_list

Parameters:none.

MI FIFO Command Format:

    :subs_phtable_list:fifo_reply
    _empty_line_

## Exported Events

### `E_PRESENCE_PUBLISH`

This event is raised when the presence module receives a PUBLISH message.

Parameters:

- user - the AOR of the user

- domain - the domain

- event - the type of the event published

- expires - the expire value of the publish

- etag - the entity tag

- body - the body of the PUBLISH request

## Installation

The module requires 3 table in OpenSIPS database: presentity, active_watchers and watchers tables. The SQL syntax to create them can be found in presence-create.sql script in the database directories in the opensips/scripts folder. You can also find the complete database documentation on the project webpage, &osipsdbdocslink;.