# &adminguide;

## Overview

This module offers the functionality of a presence user agent client, sending SUBSCRIBE and PUBLISH SIP messages. It's a core part of &kamailio;'s SIP presence package, implementing SIMPLE and various shared line appearance implementations.

It can be used with the following modules: pua_rpc, pua_usrloc, pua_bla, pua_dialoginfo, pua_reginfo and pua_xmpp. The pua_rpc module offers the possibility to publish any kind of information via the RPC transport. 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. Through pua_bla , BRIDGED LINE APPEARANCE features are added to &kamailio; The pua_xmpp module represents a gateway between SIP and XMPP, so that jabber and SIP clients can exchange presence information. The pua_reginfo modules presents registration information from the usrloc module using the reginfo event package.

The module supports 2 modes of operation. In the first a cache is used to store the presentity list and writes to database on timer to be able to recover upon restart. The presence is kept in-memory during run-time. The second is a database only mode where the presentity list is stored purely in a database, allowing both scalability and resilience.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- a database modules.

- tm.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- libxml.

## Parameters

### `hash_size` (int)

The size of the hash table used for storing SUBSCRIBE and PUBLISH information. This parameter will be used as the power of 2 when computing table size.

Default value is 9.

#### Set `hash_size` parameter

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

### `db_url` (str)

Database url.

Default value is >&defaultdb;.

#### Set `db_url` parameter

    ...
    modparam("pua", "db_url", "&exampledb;")
    ...

### `db_table` (str)

The name of the database table.

Default value is pua.

#### Set `db_table` parameter

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

### `min_expires` (int)

The inferior expires limit for both Publish and Subscribe.

Default value is 0.

#### Set `min_expires` parameter

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

### `default_expires` (int)

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

Default value is 3600.

#### Set `default_expires` parameter

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

### `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 means deleting expired messages. Setting a value less than or equal to zero, disables updates.

Default value is 100.

#### Set `update_period` parameter

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

### `outbound_proxy` (str)

SIP URI of outbound proxy to be used when sending PUBLISH requests if no outbound proxy is given in outbound_proxy field of struct publ_info.

By default, no outbound proxy has been defined.

#### Set `outbound_proxy` parameter

    ...
    modparam("pua", "outbound_proxy", "sip:outbound.example.com")
    ...

### `dlginfo_increase_version` (int)

When sending PUBLISH messages for Event: dialog, the body contains an XML document according to RFC 4235. This XML document contains a version attribute to easily detect changes in the dialog state. By setting this parameter, the pua module parses the XML document and sets the version attribute to the proper value. If the receiver of the PUBLISH does not care about the version parameter (e.g. like &kamailio; presence_dialoginfo module) it makes no sense to waste CPU resources for parsing the XML body and the parameter should be set to 0.

Default value is 0.

#### Set `dlginfo_increase_version` parameter

    ...
    modparam("pua", "dlginfo_increase_version", 1)
    ...

### `reginfo_increase_version` (int)

When sending PUBLISH messages for Event: reg, the body contains an XML document according to RFC 4235(?). This XML document contains a version attribute to easily detect changes in the registration state. By setting this parameter, the pua module parses the XML document and sets the version attribute to the proper value. If the receiver of the PUBLISH does not care about the version parameter (e.g. like &kamailio; presence_reginfo module) it makes no sense to waste CPU resources for parsing the XML body and the parameter should be set to 0.

Default value is 0.

#### Set `reginfo_increase_version` parameter

    ...
    modparam("pua", "reginfo_increase_version", 1)
    ...

### `db_mode` (int)

The module supports 2 modes of operation, high speed memory based storage (mode 0), and database only (mode 2) where all data is stored in a database, allowing scalability at the expense of speed. Mode 1 is reserved.

Default value is 0.

#### Set `db_mode` parameter

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

### `db_table_lock_write` (integer)

Enable (=1) or disable (=0) the Locks for table during a transaction. Locking only the "current" table causes problems with a MySQL-Databases in "DB-Only" mode.

Default value is 1 (Write Lock for the Tables).

#### Set `db_table_lock_write` parameter

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

### `check_remote_contact` (int)

When sending a SUBSCRIBE check that the remote contact matches the one in the stored dialog or not. If the remote contact is checked and does not match the one in the stored dialog then the dialog is not matched. Checking the remote contact can cause problems when using modules like RLS and should not be required in order to properly match the dialog anyway. Set this parameter to 0 to disable checking of remote contact for SUBSCRIBE dialog matching.

Default value is 1.

#### Set `check_remote_contact` parameter

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

### `fetch_rows` (integer)

Number of rows to be loaded in one step from database.

Default value is 500.

#### Set `fetch_rows` parameter

    ...
    modparam("pua", "fetch_rows", 1000)
    ...

## Functions

### `pua_update_contact()`

The remote target can be updated by the Contact of a subsequent in dialog request. In the PUA watcher case (sending a SUBSCRIBE messages), this means that the remote target for the following Subscribe messages can be updated at any time by the contact of a Notify message. If this function is called on request route on receiving a Notify message, it will try to update the stored remote target.

This function can be used from REQUEST_ROUTE.

Return code:

- 1 - if success.

- -1 - if error.

#### `pua_update_contact` usage

    ...
    if(method=="NOTIFY")
        pua_update_contact();
    ...

## RPC Commands

### `pua.cleanup`

Manually triggers the cleanup functions for the pua table. Useful if you have set `update_period` to zero or less.

Name: pua.cleanup

Parameters: none

RPC Command Format:

    ...
    &kamcmd; pua.cleanup
    ...

## Installation

The module requires one table in the &kamailio; database: pua. The SQL syntax to create it can be found in presence_xml-create.sql script in the database directories in the kamailio/scripts folder. You can also find the complete database documentation on the project webpage, &kamailiodbdocslink;.