SIP SIMPLE Client SDK

h1. XCAP API

The @sipsimple.xcap@ module offers a high level API for managing XCAP resources to other parts of the middleware or to the applications built on top of the middleware. The XCAP resources

which can be managed by means of this module are:

* *contact list*, by means of the @resource-lists@ and @rls-services@ XCAP applications

* *presence policies*, by means of the @org.openmobilealliance.pres-rules@ or @pres-rules@ XCAP applications

* *dialoginfo policies*, by means of the @org.openxcap.dialog-rules@ XCAP application

* *status icon*, by means of the @org.openmobilealliance.pres-content@ XCAP application

* *offline status*, by means of the @pidf-manipulation@ XCAP application

The module works with OMA-compliant XCAP servers. Not all applications need to be available on the XCAP server, although it is obvious that only those that are will be managed. The required applications are: @org.openmobilealliance.pres-rules@, @resource-lists@ and @rls-services@. The central entity for XCAP resource management is the XCAPManager, whose API relies on a series of objects describing

the resources stored on the XCAP server.

h2. Contact

Implemented in source:"sipsimple/xcap/__init__.py"

A @Contact@ is the representation of a person, containing a list of URIs with additional information stored about them, central to the XCAP contact list management. Information about a contact is stored in the @resource-lists@, @rls-services@ and @org.openmobilealliance.pres-rules@ applications mainly.

*attributes*

*id*

>A unique identifier for the contact. Should be composed of a sufficiently random string across multiple instances.

*name*

>A human-readable name which can be associated with the contact. This is stored using the @display-name@ standard @resource-lists@ element.

*uris*

>A list of @sipsimple.account.xcap.ContactURI@ instances.

*dialog*

> A @sipsimple.account.xcap.EventHandling@ instance which specifies the policy for this contact, and a boolean flag that indicates whether a subscription to the @dialog@ event is desired.

*presence*

> A @sipsimple.account.xcap.EventHandling@ instance which specifies the policy for this contact, and a boolean flag that indicates whether a subscription to the @presence@ event is desired.

*attributes*

>A dictionary containing additional name, value pairs which the middleware or the application can use to store any information regarding this contact. This is stored through a custom AG-Projects

>extension to resource-lists.

*methods*

*<notextile>__init__</notextile>*(_self_, *id*, *name*, *uris*, *presence_handling=None*, *dialog_handling=None*, ***attributes*)

>Initializes a new @Contact@ instance. If @presence_handling@ and @dialog_handling@ are set to None then defaults are created with a @default@ policy and the subscription boolean flag set to False.

h2. Policy

Implemented in source:"sipsimple/xcap/__init__.py"

A @Policy@ is similar to a @Contact@ but instead of representing a physical person, it represents a policy which is applied to a single URI.

*attributes*

*id*

>A unique identifier for the policy. Should be composed of a sufficiently random string across multiple instances.

*name*

>A human-readable name which can be associated with the policy.

*uri*

>A string object representing the URI of this policy.

*dialog*

> A @sipsimple.account.xcap.EventHandling@ instance which specifies the policy for this policy, and a boolean flag that indicates whether a subscription to the @dialog@ event is desired.

*presence*

> A @sipsimple.account.xcap.EventHandling@ instance which specifies the policy for this policy, and a boolean flag that indicates whether a subscription to the @presence@ event is desired.

*attributes*

>A dictionary containing additional name, value pairs which the middleware or the application can use to store any information regarding this policy. This is stored through a custom AG-Projects

>extension to resource-lists.

*methods*

*<notextile>__init__</notextile>*(_self_, *id*, *name*, *uri*, *presence_handling=None*, *dialog_handling=None*, ***attributes*)

>Initializes a new @Policy@ instance. If @presence_handling@ and @dialog_handling@ are set to None then defaults are created with a @default@ policy and the subscription boolean flag set to False.

h2. Group

Implemented in source:"sipsimple/xcap/__init__.py"

A @Group@ is a toplevel element which represents a logical entity for grouping contacts together.

*attributes*

*id*

>A unique identifier for the group. Should be composed of a sufficiently random string across multiple instances.

*name*

>A human-readable name which can be associated with the group.

*contacts*

> A list of @Contact@ objects.

*attributes*

>A dictionary containing additional name, value pairs which the middleware or the application can use to store any information regarding this policy. This is stored through a custom AG-Projects

>extension to resource-lists.

*methods*

*<notextile>__init__</notextile>*(_self_, *id*, *name*, *contacts*, ***attributes*)

>Initializes a new @Group@ instance.

h2. Addressbook

Implemented in source:"sipsimple/xcap/__init__.py"

An @Adressbook@ is a collection of contacts, groups and policies.

*attributes*

*contacts*

> A list of @Contact@ objects.

*groups*

> A list of @Group@ objects.

*policies*

> A list of @Policy@ objects.

*methods*

*<notextile>__init__</notextile>*(_self_, *contacts*, *groups*, *policies*)

>Initializes a new @Addressbook@ instance.

h2. Icon

Implemented in source:"sipsimple/xcap/__init__.py"

An @Icon@ instance represents a status icon stored using the @org.openmobilealliance.pres-content@ application.

*attributes*

*data*

>The binary data of the image, as  a string.

*mime_type*

>The MIME type of the image, one of @image/jpeg@, @image/gif@ or @image/png@.

*description*

>An optional description of the icon.

*location*

>An HTTP(S) URI which can be used by other users to download the status icon of the local user. If the XCAP server returns the custom X-Alternative-Location header in its GET and PUT

>responses, that is used otherwise the XCAP URI of the icon is used.

*methods*

*<notextile>__init__</notextile>*(_self_, *data*, *mime_type*, *description*=@None@, *location*=@None@)

>Initializes a new @Icon@ instance.

h2. OfflineStatus

Implemented in source:"sipsimple/xcap/__init__.py"

An @OfflineStatus@ instance represents data stored using the @pidf-manipulation@ application.

*attributes*

*pidf*

>A @sipsimple.payloads.pidf.PIDF@ instance which is stored in XCAP.

*methods*

*<notextile>__init__</notextile>*(_self_, *pidf*)

>Initializes a new @OfflineStatus@ instance.

h2. XCAPManager

Implemented in source:"sipsimple/xcap/__init__.py"

The XCAPManager is the central entity used to manage resource via the XCAP protocol. It uses a storage factory provided by @SIPApplication@ through the @Storage API@. It has state machine as described in the following diagram:

!{ align=center}xcap-manager-state.png!

The @load@ method needs to be called just once in order to load the data from the cache. Once this is done, the @start@ and @stop@ methods can be called as needed. Initially in the @stopped@ state,

the start method will result in a transition to the @initializing@ state. While in the @initializing@ state, the XCAP manager will try to connect to the XCAP server and retrieve the

capabilities (@xcap-caps@ application). It will then initiate a SUBSCRIBE for the @xcap-diff@ event and transition to the @fetching@ state. In the @fetching@ state, it

will try retrieve all the documents from the XCAP server, also specifying the ETag of the last known version. If none of the documents changed and this is not the first fetch, it transitions to the

@insync@ state. Otherwise, it inserts a @normalize@ operation at the beginning of the journal (described below) and transitions to the @updating@ state. In the @updating@ state, it

applies the operations from the journal which were not applied yet on the currently known documents and tries to push the documents, specifying the Etag of the last known version. If an operation

fails due to a document having been modified, it marks all the operations in the journal as not being applied and transitions to the @fetching@ state; if any other error occurs, the update is

retried periodically. If the update succeeds, data is extracted from the documents and the @XCAPManagerDidReloadData@ notification is sent. The XCAPManager then transitions to the @insync@

state. A call to the @stop@ method will result in a transition to the @stopping@ state, termination of any existing SUBSCRIBE dialog and a transition to the @stopped@ state.

Modifications to the settings which control the XCAPManager can result in either a transition to the @initializing@ state or the termination of any previous SUBSCRIBE dialog and creation of a new

one.

The subscription to the @xcap-diff@ event allows the XCAPManager to be notified when the documents it manages are modified remotely. If the subscription fails, a fetch of all the documents is

tried and the subscription is retried in some time. This allows the XCAPManager to reload the documents when they are modified remotely even if @xcap-diff@ event is not supported by the provider. If subscription for @xcap-diff@ event fails, a fetch of all the documents will be tried every 2 minutes.

The XCAPManager keeps the documents as they are stored on the XCAP server along with their ETags in an on-disk cache. All operations are made using the conditional @If-Match@ and

@If-None-Match@ headers such that remote modifications the XCAPManager does not know about are not overwritten and bandwidth and processing power are not wasted by GET operations when a document

is not modified.

Operations which the XCAPManager can be asked to apply to modify the documents are kept in a journal. This journal is saved to disk, such that operations which cannot be applied when requested due

to server problems or lack of connectivity are retried even after application restarts. In addition, the high-level defined operations and the journal allow the modifications to be applied even if the

document stored on the XCAP server are modified. Put differently, operations do depend on a specific version of the documents and the XCAPManager will try to apply them irrespective of the format

of the document.

*configuration*

*Account.id*, *Account.auth.username*, *Account.auth.password*

>These are used both for the @xcap-diff@ subscription and the XCAP server connection. 

*Account.sip.subscribe_interval*

>This controls the Expires header used for the subscription, although a 423 response from the server can result in a larger Expires value being used.

*Account.xcap.xcap_root*

>This specifies the XCAP root used for contacting the XCAP server and managing the resources. If this setting is @None@, a TXT DNS query is made for the @xcap@ subdomain of the SIP account's

>domain. The result is interpreted as being an XCAP root. Example record for account alice@example.org:

  <pre>

  xcap.example.org.    IN  TXT     "https://xcap.example.org/xcap-root"

</pre>

*SIPSimpleSettings.sip.transport_list*

>This controls the transports which can be used for the subscription.

*methods*

*<notextile>__init__</notextile>*(_self_, *account*)

>Initializes an XCAPManager for the specified account.

*init*(_self_)

>Initializes the XCAPManager before it can be started.

*start*(_self_)

>Starts the XCAPManager. This will result in the subscription being started, the XCAP server being contacted and any operations in the journal being applied. This method must be called in a green

>thread.

*stop*(_self_)

>Stops the XCAPManager from performing any tasks. Waits until the @xcap-diff@ subscription, if any, is terminated. This method must be called in a green thread.

*transaction*(_self_)

> Return as @XCAPTransaction@ context manager object for running a piece of code within a transaction.

*start_transaction*(_self_)

>This allows multiple operations to be queued and not applied immediately. All operations queued after a call to this method will not be applied until the @commit_transaction@ method is called.

>This does not have the same meaning as a relational database transaction, since there is no @rollback@ operation.

*commit_transaction*(_self_)

>Applies the modifications queued after a call to @start_transaction@. This method needs to be called the exact same number of times the @start_transaction@ method was called. Does not have

>any effect if @start_transaction@ was not previously called.

 The following methods results in XCAP operations being queued on the journal:

*add_group*(_self_, *group*)

>Add a group.

*update_group*(_self_, *group*, *attributes*)

>Update the specified group with the given attributes.

*remove_group*(_self_, *group*)

>Remove the specified group.

*add_contact*(_self_, *contact*)

>Adds a new contact, described by a @Contact@ object. Requests to add a contact to some OMA reserved presence policies (@wp_prs_unlisted@, @wp_prs_allow_unlisted@, @wp_prs_block_anonymous@, @wp_prs_allow_own@) is ignored.

*update_contact*(_self_, *contact*, *attributes*)

>Modifies a contact's properties. The keywords can be any of the @Contact@ attributes, with the same meaning. Requests to add a contact to some OMA reserved presence policies (@wp_prs_unlisted@, @wp_prs_allow_unlisted@, @wp_prs_block_anonymous@,  @wp_prs_allow_own@) is ignored.

*remove_contact*(_self_, *contact*)

>Removes the specified contact.

*add_contact_uri*(_self_, *contact*, *uri*)

> Add the specified URI to the specified contact.

*update_contact_uri*(_self_, *contact*, *uri*, *attributes*)

> Update the specified URI.

*remove_contact_uri*(_self_, *contact*, *uri*)

> Remove the specified URI from the specified contact.

*add_group_member*(_self_, *group*, *contact*)

> Adds the specified contact to the specified group. A contact may be added to multiple groups.

*remove_group_member*(_self_, *group*, *contact*)

> Removes the specified contact from the specified group.

*add_policy*(_self_, *policy*)

>Adds a new policy, described by a @Policy@ object.

*update_policy*(_self_, *policy*, *attributes*)

>Modifies a presence policy's properties. The keywords can be any of the @PresencePolicy@ attributes, with the same meaning. 

*remove_policy*(_self_, *policy*)

>Removes the specified policy.

*set_status_icon*(_self_, *icon*)

>Sets the status icon using the information from the @Icon@ object specified. The @location@ attribute is ignored. The MIME type must be one of @image/gif@, @image/png@ or @image/jpeg@. If the argument is @None@, the status icon is deleted.

*set_offline_status*(_self_, *status*)

>Sets the offline status using the information from the @OfflineStatus@ object specified. If the argument is @None@, the offline status document is deleted.

*notifications*

*XCAPManagerWillStart*

>This notification is sent just after calling the @start@ method.

*XCAPManagerDidStart*

>This notification is sent after the XCAPManager has started doing its tasks (contacting the XCAP server, subscribing to @xcap-diff@ event). This notification does not mean that

>any of these operations were successful, as the XCAPManager will retry them continuously should they fail.

*XCAPManagerWillEnd*

>This notification is sent just after calling the @stop@ method.

*XCAPManagerDidEnd*

>This notification is sent when the XCAPManager has stopped performing any tasks. This also means that any active @xcap-diff@ subscription has been terminated.

*XCAPManagerDidDiscoverServerCapabilities*

>This notification is sent when the XCAPManager contacts an XCAP server for the first time or after the connection is reset due to configuration changes. The data of the notification contains

>information about the server's capabilities (obtained using the @xcap-caps@ application).

>+_auids_+:

>>A list of string representing the AUIDs supported by the server.

*XCAPManagerDidReloadData*

>This notification is sent when the XCAPManager synchronizes with the XCAP server. The data of the notification contains objects representing the data as it is stored on the XCAP server.

>+_addressbook_+:

>>A @sipsimple.account.xcap.Addressbook@ object instance.

>+_presence_rules_+:

>>A @sipsimple.account.xcap.PresenceRules@ object. Currently it only contains the default policy.

>+_dialog_rules_+:

>>A @sipsimple.account.xcap.DialogRules@ object. Currently it only contains the default policy.

>+_status_icon_+:

>>A @StatusIcon@ object if one is stored, @None@ otherwise.

>+_offline_status_+:

>>A @OfflineStatus@ object if offline status information is stored, @None@ otherwise.

*XCAPManagerDidChangeState*

>This notification is sent when the XCAPManager transitions from one state to another.

>+_prev_state_+:

>>The old state of the XCAPManager, a string.

>+_state_+:

>>The new state of the XCAPManager, a string.