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.

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

__init__(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.

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

__init__(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.

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

__init__(self, id, name, contacts, **attributes)

Initializes a new Group instance.

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

__init__(self, contacts, groups, policies)

Initializes a new Addressbook instance.

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 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

__init__(self, data, mime_type, description=None, location=None)

Initializes a new Icon instance.

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

__init__(self, pidf)

Initializes a new OfflineStatus instance.

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:

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:

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

SIPSimpleSettings.sip.transport_list

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

methods

__init__(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.