# &adminguide;

## 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, pua_bla and pua_xmpp. The pua_mi offer the possibility 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. Through pua_bla , BRIDGED LINE APPEARANCE features are added to OpenSIPs. The pua_xmpp module represents a gateway between SIP and XMPP, so that jabber and SIP clients can exchange presence information.

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

Notice: This module must not be used in no fork mode (the locking mechanism used may cause deadlock in no fork mode).

## Dependencies

### &osips; 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 &osips; with this module loaded:

- libxml.

## Exported 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 300.

#### 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 is deleting expired messages.

Default value is 30.

#### Set `update_period` parameter

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

## Exported 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();
    ...

## Installation

The module requires 1 table in OpenSIPS database: pua. The SQL syntax to create it can be found in presence_xml-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;.