-
Notifications
You must be signed in to change notification settings - Fork 2
/
README
176 lines (102 loc) · 4.58 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
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"
<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:[email protected]"]'
201 Created
etag: "bfbd38bed7163dd19e6e110d0dfa0876"
This will shift Bill's entry to the second position.