SIP SIMPLE Client SDK

= Presence blueprint =

[[TOC(Design*, depth=1)]]

This is a high level representation of a mechanism that maintains a '''Contacts list''' that can be used by a GUI.  It implements a combination of SIP SIMPLE standards related to presence event package, storage and policy.

 * Account

 * Contacts

 * Watcher list

 * Presence rules

 * Icon exchange

 * Preferences

== Design principle ==

The client maintains a '''Contacts list''' that is a contacted list of resource-lists XCAP documents stored on multiple XCAP servers. A Contact is stored on exactly one XCAP server to provide atomic transaction. When a Contact is added/modified/deleted the corespondent remote XCAP storage is accessed. The remote storage is set per Contact in the Add/Edit Contact dialog.

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

== Prerequisites ==

To implement full presence support the following functionality must be available in the servers side.

 1. Support in OpenXCAP for '''icon''' application, http://openxcap.org/ticket/100

 1. Support in OpenXCAP for '''xcap-directory''' application, http://openxcap.org/ticket/101

 1. OpenSIPS '''xcap-diff''' module to perform refresh_watchers()

 1. OpenSIPS '''dialog-info''' module to use XCAP document dialog-rules for authorization

 1. OpenSIPS '''dialog-info''' module to sent notify for dialog-info.winfo Event 

 1. OpenXCAP to perform PUBLISH for xcap-diff when any xcap doc changes

 1. Implement caps payload type in client (device capabilities) 

 1. Implement dialog-info event package in client

== Account ==

On boot if presence enabled

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

 * GET XCAP application xcap-caps

 * GET the default filename for all applications supported in xcap-caps and cache them locally

 * Initialize own '''presentity''' 

 * Initialize '''watchers list''' for Event presence

 * Initialize '''watchers list''' for Event dialog-info

 * If '''pidf-manipulation''' application is supported by XCAP server, update the '''presentity''' with the PIDF stored on the XCAP server

 * Compose and send PUBLISH for '''Event: presence'''

 * Initialize '''Contacts''' using the content of the XCAP document '''resource-lists'''

 * If '''account.presence.subscribe_xcap_diff''' is Enabled, SUBSCRIBE for '''Event: xcap-diff'''

While running

 * Refresh the XCAP server location based on DNS TTL

 * Reload XCAP documents based on '''xcap-diff''' NOTIFYs

== Contacts ==

Contains is a list of contacts displayed in a GUI. For some contacts we SUBSCRIBE for '''Event: presence''' and '''Event: dialog-info'''. The list is indexed by a unique SIP URI, a random SIP URI must be generated for contacts that do not have a SIP URI and we must mark the contacts that we want to subscribe to. 

Additional, one can store full names and other attributes for each contact by using extensions to PIDF for contact information. 

Based on received NOTIFY messages for Event=presence, each contact has a '''presentity''' attribute that contains its own published information. The GUI can display attributes of each '''presentity'''.

 * The contacts list is stored in the main '''resource-lists''' XCAP document '''index'''

 * Maintain a '''presentity''' attribute with what is received in the Notify for presence for each contact

 * Maintain a '''dialog-info''' attribute with what is received in the Notify for dialog-info event for each contact

 * If '''account.presence.subscribe_rls_services''' is True, a RLS document that contains a list of discrete SIP URIs we subscribe to and PUT it on the server under SIP URI account-buddies@domain. Then a Subscribe is sent with Supported: eventlist for this SIP URI. /otherwise send SUBSCRIBVE to each contact for '''Event: presence''' 

 * On contacts list change, PUT resource-lists and rls-services documents on the XCAP server

A contact has properties related to his device capabilities (e.g. can_chat, can_share, can_talk, can_video). This is conveyed via '''presence caps''' and updates the preferences set by the local user

== Watcher lists ==

 * Built based on the body of NOTIFY for '''Event=presence.winfo'''.

 * Built based on the body of NOTIFY for '''Event=dialog-info.winfo'''.

== Presence rules ==

 * Based on NOTIFY for event '''watcher.info''' we update the policy

 * PUT '''pres-rules''' document on the XCAP server and cache locally

== Icon exhange ==

There is how OMA has specified such XCAP application: 

'"Presence Content XDM Specification'"

http://www.openmobilealliance.org/technical/release_program/docs/PresenceSIMPLE/V2_0-20081223-C/OMA-TS-Presence_SIMPLE_Content_XDM-V1_0-20081223-C.pdf

Publishing end-point, on boot:

 1. HTTP GET for xcap-directory and locate previously uploaded icon (e.g. ABC)

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

Publishing end-point, on icon change:

 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. HTTP PUT to xcap server

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

 1. HTTP DELETE any previous icon file ABC

Subscribing end-point:

 1. Parse <icon> element of pidf 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

== Preferences ==

Manage the '''pres-rules''' and '''dialog-rules''' policy documents on XCAP server