Python XCAP client library
--------------------------

Author: Denis Bilenko, Saul Ibarra
Homepage: http://download.ag-projects.com/XCAP/


License
-------

See LICENSE file.


Description
-----------

XCAP protocol, defined in RFC 4825, 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 used by
XCAP clients to store data like presence policy in combination with a SIP
Presence server that supports PUBLISH/SUBSCRIBE/NOTIFY SIP methods can
provide a complete SIP SIMPLE solution.

The XCAP client example script provided by this package can be used to
manage documents on an XCAP server.


Debian package installation
--------------------------- 

Add the following lines to /etc/apt/sources.list

# AG Projects software
deb     http://ag-projects.com/debian unstable main
deb-src http://ag-projects.com/debian unstable main

Install the AG Projects debian software signing key:

wget http://download.ag-projects.com/agp-debian-gpg.key
apt-key add agp-debian-gpg.key

After that, run:

sudo apt-get update
sudo apt-get install python-xcaplib


Manual installation
-------------------

Download the tar archive from http://download.ag-projects.com/XCAP.

Extract the tar archive and run under the newly created directory:

sudo python setup.py install


Development version
-------------------

The source code is managed using darcs version control tool. The darcs
repository can be fetched with:

darcs get http://devel.ag-projects.com/repositories/python-xcaplib

To obtain the incremental changes after the initial get, go to the
python-xcaplib directory and run:         

cd python-xcaplib
darcs pull -a



Usage
-----

This software has been tested against OpenXCAP server http://openxcap.org

To test this script you can also register a SIP SIMPLE account on
http://sip2sip.info, which provides a fully functional XCAP server.

Copy xcapclient.ini.sample to ~/.xcapclient.ini and change it accordingly to
your XCAP server location and credentials. You may set the sip_address,
password and xcap root in the configuration file.

For argument and node-selector bash completion: 

sudo cp bash_completion.d/xcapclient /etc/bash_completion.d/


1. Operating on XCAP documents (full document handling)

  In the examples folder there are sample XCAP XML documents used for the
  examples below:

  a. PUT

  To a document, for example, presence rules:

  xcapclient -i pres-rules.xml put

  On success, the command prints '201 Created' if a new document was created on the
  server or '200 OK' if an existing document was replaced. You should something like this:

  url: http://xcap.example.com/xcap-root/resource-lists/users/alice@example.com/index.xml
  201 Created
  etag: "856bdac9012ee28e46cebb81e51ac2a0"

  b. GET

  xcapclient --app resource-lists get

  or

  xcapclient --app pres-rules get

  or

  xcapclient --app rls-services get

  This will print the document you've just put, along with its tag.

  or
  
  xcapclient --app xcap-caps get

  will print the capabilities of the XCAP server.	


  c. DELETE

  xcapclient --app resource-lists delete

  and

  xcapclient --app pres-rules delete

  and

  xcapclient --app rls-services  delete


2. Operating on XML elements (partial document handling)

  It is possible to retrieve a single element in XCAP document, to
  replace it, to insert a new one or to remove one. To address an element, a
  node selector is required, which is an XPATH-like expression, defined in
  http://tools.ietf.org/html/rfc4825#section-6.3.

  Let's put the document in section 1 again to server, so we can fetch some elements from it.

  xcapclient --app resource-lists get '/resource-lists/list[@name="friends"]/entry[1]/display-name'

  etag: "856bdac9012ee28e46cebb81e51ac2a0"
  <display-name>Bill Doe</display-name>

  Specifying application with --app, is no longer necessary as it may be
  guessed from the node selector.

  To replace an element, use the node selector you would have used for
  retrieving the element but do PUT instead. For example if we want to fix
  Bill's display name:

  xcapclient -i bill_display_name_fixed.xml put '/resource-lists/list[@name="friends"]/entry[1]/display-name'

  To insert a new element one must construct a node selector that doesn't
  point to an existing element.

  xcapclient -i alice.xml put '/resource-lists/list[@name="friends"]/entry[1][@uri="sip:alice@example.com"]'

  201 Created
  etag: "bfbd38bed7163dd19e6e110d0dfa0876"

  This will shift Bill's entry to the second position.