SipXCAPApi

Version 3 (Oliver Bril, 03/31/2009 03:47 pm)

1 1 Adrian Georgescu
= XCAP API =
2 1 Adrian Georgescu
3 1 Adrian Georgescu
[[TOC(WikiStart, Sip*, depth=3)]]
4 1 Adrian Georgescu
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 clients using HTTP protocol. An XCAP server is used by XCAP clients to store data like buddy lists and presence policy in combination with a SIP Presence server that supports PUBLISH, SUBSCRIBE and NOTIFY methods to provide a complete SIP SIMPLE solution.
5 2 Oliver Bril
6 2 Oliver Bril
XCAP client is implemented by [http://devel.ag-projects.com/cgi-bin/darcsweb.cgi?r=python-xcaplib;a=summary python-xcaplib]. The library provides {{{xcaplib.client.XCAPClient}}} class which is an HTTP client with an interface better suited for XCAP servers. The library also provides
7 2 Oliver Bril
a version of XCAPClient ({{{xcaplib.green.XCAPClient}}}) built on top of eventlet, which may be used in twisted reactor.
8 2 Oliver Bril
9 2 Oliver Bril
Here a few examples on how to use {{{XCAPClient}}}:
10 2 Oliver Bril
{{{
11 2 Oliver Bril
client = XCAPClient(xcap_root, xcap_user_id, password=password)
12 2 Oliver Bril
document = file('examples/resource-lists.xml').read()
13 2 Oliver Bril
14 2 Oliver Bril
# put the document on the server
15 2 Oliver Bril
client.put('resource-lists', document)
16 2 Oliver Bril
17 2 Oliver Bril
# read the document from the server
18 2 Oliver Bril
got = client.get('resource-lists')
19 2 Oliver Bril
20 2 Oliver Bril
# get a specific element within a document
21 2 Oliver Bril
element = client.get('resource-lists', '/resource-lists/list/entry/display-name')
22 2 Oliver Bril
23 2 Oliver Bril
# get an attribute:
24 2 Oliver Bril
res = client.get('resource-lists', '/resource-lists/list/entry/@uri')
25 2 Oliver Bril
26 2 Oliver Bril
# replace an element conditionally, based on the etag
27 3 Oliver Bril
client.put('resource-lists', '<entry uri="sip:bob@example.com"><display-name>The Bob</display-name></entry>',
28 3 Oliver Bril
           '/resource-lists/list/entry[@uri="sip:bob@example.com"]', etag=stored_etag)
29 2 Oliver Bril
30 2 Oliver Bril
# delete an element
31 2 Oliver Bril
client.delete('resource-lists', node_selector, etag=res.etag)
32 1 Adrian Georgescu
}}}
33 3 Oliver Bril
34 3 Oliver Bril
35 3 Oliver Bril
=== XCAPClient interface ===
36 3 Oliver Bril
37 3 Oliver Bril
 '''get'''(''self'', ''application'', ''node''={{{None}}}, ''etag''={{{None}}}, ''headers''={{{None}}})::
38 3 Oliver Bril
 Make an HTTP GET request to the resource identified by ''application'' and ''node''. Return a Resource instance on success.
39 3 Oliver Bril
 Raise HTTPError if the operation was unsuccessful.
40 3 Oliver Bril
41 3 Oliver Bril
 '''put'''(''self'', ''application'', ''resource'', ''node''={{{None}}}, ''etag''={{{None}}}, ''headers''={{{None}}})::
42 3 Oliver Bril
 Make an HTTP PUT request to the resource identified by ''application'' and ''node''. Use ''resource'' as a request body.
43 3 Oliver Bril
 Raise HTTPError is the operation was unsuccessful.
44 3 Oliver Bril
45 3 Oliver Bril
 '''delete'''(''self'', ''application'', ''node''={{{None}}}, ''etag''={{{None}}}, ''headers''={{{None}}})::
46 3 Oliver Bril
 Make an HTTP DELETE request to the resource identified by ''application'' and ''node''.
47 3 Oliver Bril
 Raise HTTPError if the operation was unsuccessful.