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" Bill Doe 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.