SIP SIMPLE Client SDK

= Presence Functionality =

[[TOC(DesignBuddyList, depth=2)]]

This is a high level design of a mechanism that manages a ''Contacts List'' and handles Subscriptions, Publications and Notifications that can be used by a ''SIP client'' with a graphical user interface.

The goal of the design is to help implementing the SIP SIMPLE standards related to ''presence'' and ''presence.winfo'' event packages into the ''SIP client''. 

The design requires a ''Presence Agent'' and an ''XCAP server'' serving the domain of the SIP account for which this functionality is desired.

== Contacts List ==

''Contacts List'' contains is a list of discrete contacts displayed by the GUI. It must be managed by the SIP client at a global level above the individual SIP account level.

The ''Contacts List'' is organized into ''Groups''. The ''SIP client'' maintains this central ''Groups List'' by merging all found groups on local and remote storage(s) and populates each group with all contacts found for them.

Some contacts are marked to Subscribe to them for ''Event: presence''. Based on received Notify messages for ''Event: presence'', each Contact has a ''presentity'' attribute that contains its own published information as pidf xml payload, the GUI can display attributes of it.

The following presence related payloads as used to generate the presentity payload used for publish:

 * Presence Data Model RFC4479

 * Rich Presence Extensions RFC4480

 * Contact Information for the Presence Information Data Format RFC4482

 * User Agent Capability Extension to Presence Information Data Format RFC5196

> Same Contact may end up belonging to different Groups if the same SIP address is stored on multiple XCAP servers in different groups.

=== Storage ===

The ''SIP client'' builds the ''Contacts List'' by concatenating the individual lists stored locally or on the ''resource-lists'' documents stored on the XCAP server corespondent to each SIP account. 

When a Contact is added/modified/deleted the corespondent remote XCAP storage documents are also updated. The remote storage is set per Contact in the Add/Edit Contact dialog of the SIP client. This remote server storage is used for initializing the locally cached Contacts List between restarts and to synchronize changes between multiple SIP UAs configured for the same SIP account.

[[Image(BuddyList-Aggregation.png)]]

== Account ==

Each SIP Account has settings in the middleware that affect the way it interacts with its correspondent Contacts

 * Subscribes to information related to who has subscribed to its own presence information and generate a policy document that is used for subsequent subscriptions and notifications by the Presence Agent

 * Stores its data into the XCAP server corespondent with the SIP account or locally if no XCAP server is available

On boot:

=== Publish  ===

If ''account.xcap'' is enabled

 * If ''account.xcap.xcap_root'' is not set, locate XCAP root by doing a DNS TXT lookup for xcap.example.com

 * GET XCAP application xcap-caps

 * GET XCAP application xcap-directory

 * For all supported applications returned by above step, GET their files and cache them locally

If ''account.xcap.subscribe_xcap_diff'' is enabled

 * Sent Subscribe for ''Event: xcap-diff''

If ''Icon'' application is enabled

 * GET the previous icon using HTTP request

If ''account.presence.subscribe_winfo'' is enabled

  * Send Subscribe for ''presence.winfo''

  * Initialize ''Watchers List'' for ''Event: presence'' based on received Notify

If ''account.presence.enable_publish'' is enabled

  * If ''pidf-manipulation'' application is supported by the XCAP server, update the pidf with its content and update GUI with the fact that we have server based PIDF set  

  * Send Publish with the current pidf if pidf_manipulation is not set, let the user change his state manually if pidf_manipulation is set

If ''account.presence.resource_lists'' is enabled

 * Initialize the ''Contacts List'' by using the content of the XCAP document ''resource-lists'', filename ''index''. Initialize the ''Subscriptions List'' using the Contacts marked for ''Subscribe to Presence''

If ''account.presence.rls_services'' is enabled

 * Put the content of ''Subscription List'' initialized above to the XCAP document ''rls-services'' identified by SIP URI account-buddies@domain.

=== Subscribe ===

If ''account.presence.subscribe_presence'' is enabled

 * If ''account.presence.subscribe_rls_services'' is True send one Subscribe for ''Event: presence'', and header ''Supported: eventlist'' to account-buddies@domain

 * Else for each contact in the ''Subscriptions List'' send individual Subscribe for ''Event: presence''

While running:

 * Refresh the location of the XCAP server based on DNS TTL

 * Refresh the Publish

 * Refresh the Subscribe

=== Notify ===

 * On Notify for ''Event: xcap-diff'' that a supported XCAP document has been changed by other SIP UA GET the new document

 * On Notify for ''Event: presence'' update the presentity of affected Contacts

 * On Notify for 'Event: presence,winfo'' trigger notifications end user to update its policy 

> Each individual contact list stored in a resource-lists document is indexed by a unique SIP URI, a random SIP URI must be generated for Contacts that do not have a real SIP URI and we must mark the contacts that we want to Subscribe to for presence information. Additional, one can store full names and other attributes related to remote recipient by using extensions to PIDF for contact information (cipid extension). 

== Policy change ==

 * Based on Notify for ''Event: presence.winfo'' alert the user about new watchers and update the policy stored in the pres-rules XCAP document

 * PUT ''pres-rules'' document on the XCAP server

Transformations are required to support the following functionality:

 1.  First degree watchers - access to entire PIDF

 1.  Second degree watchers - access to subset of PIDF

 1.  Third degree watchers - access to basic presence online/offline

== Icon change ==

OMA has specified the use of XCAP server for icon application [http://www.openmobilealliance.org/technical/release_program/docs/PresenceSIMPLE/V2_0-20081223-C/OMA-TS-Presence_SIMPLE_Content_XDM-V1_0-20081223-C.pdf Presence Content XDM Specification]

Publishing end-point:

 1. Generate a new random filename: XYZ

 1. Build URL http://xcap.example.com/xcap-root/org.openmobilealliance.pres-content/users/sip:alice@example.com/oma_status-icon/XYZ

 1. PUT the new icon document to XCAP server

 1. Update <icon> element of pidf and PUBLISH new pidf

 1. DELETE any previously uploaded icon file

Subscribing end-point:

 1. Parse <icon> element of pidf cipid extension received in Notify

 2. HTTP GET http://xcap.example.com/xcap-root/org.openmobilealliance.pres-content/users/sip:alice@example.com/oma_status-icon/XYZ

 3. Cache picture until next Notify with diferent <icon> element is received

== GUI notifications ==

The GUI client must be notified by the middleware when a network event related to Presence occurs:

 1. Watcher list has changed

 1. Presence information of a Contact has changed

 1. A conflict exists between the server version and the local version of an XCAP document

Each ''Contact'' can publish properties related to his device capabilities (e.g. chat, audio, video). This is conveyed via ''caps'' extension to ''pidf'' and can be used to drive the contextual menu presented for each Contact related to what kind of action can be initiated to it.

== GUI actions ==

 1. Display and manages the ''Contacts List''

 1. Display the several attributes of the Presence information of each Contact 

 1. Manage the content of the ''Policy'' document

 1. Update the ''Icon'' of the SIP account