Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/agprojects/python-xcaplib

XCAP (RFC4825) client library
https://github.com/agprojects/python-xcaplib

Last synced: 11 days ago
JSON representation

XCAP (RFC4825) client library

Awesome Lists containing this project

README 

        

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/[email protected]/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:[email protected]"]'



  201 Created

  etag: "bfbd38bed7163dd19e6e110d0dfa0876"



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