root/README

OpenXCAP
--------

Copyright (c) 2007-2008 AG Projects 
http://ag-projects.com

Authors: Mircea Amarascu, Lucian Stanescu, Denis Bilenko


License
-------

See LICENSE file.


Project description
-------------------

XCAP protocol allows a client to read, write, and modify application
configuration data stored in XML format on a server. XCAP maps XML document
sub-trees and element attributes to HTTP URIs, so that these components can
be directly accessed by HTTP. An XCAP server is used by the XCAP clients to
store data like Presence policy in combination with a SIP Presence server
that supports PUBLISH/SUBSCRIBE/NOTIFY methods to provide a complete
[http://www.tech-invite.com/Ti-sip-WGs.html#wg-simple SIP SIMPLE] server
solution.

The XCAP server is used as a policy decision maker by the SIP Presence
server to manage the subscriptions and notifications of presence information
based on end-user controlled preferences. The XCAP server can also be used
to publish to SIP devices information retrieved from external sources and
using different APIs acting like a bridge between real-time communications
based on SIP protocol and other web technologies like SOAP/XML.

OpenXCAP is an open source, easy extensible, fully featured XCAP server with
TLS security and support for multiple realms. The server is written in
Python programming language and is based on the following RFCs:

    - The Extensible Markup Language Configuration Access Protocol (RFC 4825)

    - Formats for Representing Resource Lists (RFC 4826)

    - Usage for Manipulating Presence Document Contents (RFC 4827)

    - Presence Authorization Rules (draft-ietf-simple-presence-rules-10)


Features
--------

Supported XCAP applications

    - Resource lists (auid = resource-lists). A resource lists application
    is any application that needs access to a list of resources, identified
    by a URI, to which operations, such as subscriptions, can be applied.

    - RLS Services (auid = rls-services). A Resource List Server (RLS)
    services application is Session Initiation Protocol (SIP) application
    whereby a server receives SIP SUBSCRIBE requests for resource, and
    generates subscriptions towards the resource list. For practical
    purposes, uri attributes in <service> do not have global scope, i.e. 
    several users may have services defined with the same uris, which is the
    opposite of the RFC. Each user can maintain the same service uris, the
    server identifies the right document from the XCAP Request URL.
    Requesting rls-services/global/index as described in the RFC does not
    seem to add any value and it was not implemented.

    - PIDF Manipulation (auid = pidf-manipulation). Pidf-manipulation
    application usage defines how XCAP is used to manipulate the contents of
    PIDF based presence documents.

    - Presence Rules (auid = presence-rules). A Presence Rules application
    is an application which uses authorization policies, also known as
    authorization rules, to specify what presence information can be given
    to which watchers, and when.

    - Watchers (auid = watchers). This this a custom application that queries
    the sip proxy database for a list of presence watchers and their status.
    The XML schema for this application can be found in
    xcap/xml-schemas/watchers.xsd. This application is read-only.


Data storage

OpenXCAP server supports multiple back-end storage systems and works out of
the box with OpenSER Proxy/Registrar/Presence server


Publishing xcap-diff events

OpenXCAP server can publish xcap-diff when a change occurs as described
in http://tools.ietf.org/html/draft-ietf-simple-xcap-diff-09

Generated event is published via OpenSER's management interface (function
'publish' from pua_mi module). Checkout out sample openser.cfg in openser dir.
OpenSER module presence_xcapdiff registers 'xcap-diff' event with presence in pua.

To enable this feature in OpenXCAP backend 'OpenSER' must be used and
enable_publish_xcapdiff parameter must be set to 'yes'.

OpenXCAP doesn't put diff information into events, only uris and etags of
affected documents. Client must use then external document retrieval.
(This corresponds to rows 2, 4 and 5 in Figure 1 of the draft)

There's no way to indicate what uris client has interest in, all changes
to the documents belonging to given user are published.


XCAP clients
------------

No server is useful without clients supporting their features. Here is list
with XCAP clients known to be working with OpenXCAP:

    - OpenSER from http://openser.org

    - simple-soap-proxy. This client allows publication of arbitrary
      information and policy management using an easy to use SOAP/XML
      interface
    
    - Eyebeam from http://www.counterpath.com


Support
-------

The project is supported via this wiki collaboration system provided at:

http://openxcap.org

    - To open ticket please Register first. The ticketing support system is
      available only for registered users. Please beware that the support is
      provided by the community on a best-effort basis.

Commercial support or other licensing options are available from:
AG Projects http://ag-projects.com