# Overview

This module implements a presence server, i.e. entity that receives SUBSCRIBE requests and sends NOTIFY when presence status of a user changes and allows user to use PUBLISH request for publishing presence status information.

## Features

- handle SUBSCRIBE requests

- handle PUBLISH requests

- XCAP authorization of subscriptions

- failover - all subscription's data including SIP dialogs can be stored into database and reloaded on startup

- offline watcher info - watchers can be stored into database when presentity is offline and sent in watcher info notification when presentity subscribes to its watcherinfo again

## Presence status

User's presence status is hold internaly (in memory); it can be taken from:

- registrar - online/offline information with contact

- published information by user (see )

- to be done: from reg events subscriptions

- to be done: from subscriptions to users

TODO: cache mode needed by large setups, when the presence status will be in memory only cached, not fully stored (limited size of cache, possibility to switch it off). [status: design in progress, coding will start after Ottendorf will be branched]

## Supported document formats

Supported document formats in PUBLISH:

- PIDF - see

- CPIM-PIDF (last version which differs from PIDF only in namespaces and MIME type name)

- PIDF extensions (like RPID )

Supported document formats in NOTIFY:

- PIDF - see

- CPIM-PIDF (last version which differs from PIDF only in namespaces and MIME type name)

- LPIDF

- XPIDF (MS variant used by Windows Messenger 4.7)

- PIDF extensions (like RPID )

# Dependencies

## Modules

- tm

- dialog

- usrloc

- optionaly database module (mysql, ...)

- optionaly xcap module for XCAP authorization

## Libraries

- libxml2 - external library for parsing XML documents

- libcds (internal)

- libxcap (internal) - XCAP queries (authorization)

- libpresence (internal) - used for internal subscriptions from RLS

# Behaviour

Short notes to be remembered...

There are two possibilities how to get authorization rules from XCAP when creating new presentity (controled by module parameter `async_auth_queries`):

- asynchronously - XCAP is not queried when processing SUBSCRIBE request which created presentity what results into 202 response and delayed authorization of such first watcher. First NOTIFY in this case will carry no information and "pending" status; later (as soon as will be authorization rules got from XCAP) will be generated other NOTIFY with correct authorization status.

- synchronously - XCAP is queried for presence rules immediately, but this slows down processing of such SUBSCRIBE request and may bring problems under heavy load so it is not recommended. In this case first NOTIFY contains correct subscription status and data.

Other SUBSCRIBE requests than the first one which creates the presentity already have authorization document which is stored within presentity's data and don't need to wait for XCAP. But this can consume lots of memory [TODO: this will be solved by intelligent document caching within XCAP module only].

Re-authorization is done by timer - authorization document queries for each presentity are sent time after time and all presentity's watchers are reauthorized. This is due to missing implementation of notification mechanism for XCAP server data changes (might be implemented in the future, but XCAP server able to do it is needed!).

One of reasons which lead to timer-based reauthorization was that previous method, when reauthorization was done only when watcher is resubscribing, was not acceptable for users which want to propagate changes in authorization document immediately.

When a non-2xx final response to a NOTIFY comes, the subscription is destroyed (really needed under high load). It is possible to say that 408 responses are ignored (see parameter `ignore_408_on_notify`) but this should be used for testing only.

# State aggregation

PA modules does state aggregation from multiple sources:

registrar

  Information from registrar is taken by callbacks to usrloc module. Each registered contact is taken as a standalone tuple. Status may be open or closed, contact for the tuple is taken from contact registration. Priority of such tuples is taken from parameter `default_priority_percentage`. It is recommended to have this value lower than priority of tuples published by PUBLISH.

  You can ommit this source by setting `use_callbacks` to 0.

published state

  State published by clients using PUBLISH request according to RFC 3903. There can be more published tuples, each of them is identified by its id in PIDF document. This id is used for tuple identification in re-publications, but it is NOT used as id in NOTIFYs sent from PA. Instead of it is used newly generated tuple id because this id must be unique (across all presentity's UACs).

  It is NOT possible to replace existing tuple with publishing information for tuple with the same id - this would be against RFC 3903! When publishing status it is only possible to have influence on tuples published with the same entity tag (see Sip-If-Match and SIP-ETag header fields).

  PA understoods only basic PIDF, but it can handle PIDF extensions like RPID too. PIDF extensions are hold as whole XML elements without knowing about their definition and thus publishing client is responsible for correct content of them. PA ignores "mustUnderstand" attribute (see ). [Are there any problems with it?]

  You can control this source by PUBLISH request handling in config script (function `handle_publish`).