Debian Codegraph @

src/modules/xcap_client/README

raw
1 XCAP_Client Module
2
3 Anca-Maria Vamanu
4
5 Voice Sistem SRL
6
7 Edited by
8
9 Anca-Maria Vamanu
10
11 Copyright © 2007 Voice Sistem SRL
12 __________________________________________________________________
13
14 Table of Contents
15
16 1. Admin Guide
17
18 1. Overview
19 2. Dependencies
20
21 2.1. Kamailio Modules
22 2.2. External Libraries or Applications
23
24 3. Parameters
25
26 3.1. db_url(str)
27 3.2. xcap_table(str)
28 3.3. periodical_query(int)
29 3.4. query_period(int)
30
31 4. RPC Commands
32
33 4.1. xcap_client.refreshXcapDoc
34
35 5. Remarks
36
37 2. Developer Guide
38
39 1. bind_xcap_api(xcap_api_t* api)
40 2. get_elem
41 3. register_xcb
42
43 List of Examples
44
45 1.1. Set db_url parameter
46 1.2. Set xcap_table parameter
47 1.3. Set periodical_query parameter
48 1.4. Set query_period parameter
49 2.1. xcap_api structure
50
51 Chapter 1. Admin Guide
52
53 Table of Contents
54
55 1. Overview
56 2. Dependencies
57
58 2.1. Kamailio Modules
59 2.2. External Libraries or Applications
60
61 3. Parameters
62
63 3.1. db_url(str)
64 3.2. xcap_table(str)
65 3.3. periodical_query(int)
66 3.4. query_period(int)
67
68 4. RPC Commands
69
70 4.1. xcap_client.refreshXcapDoc
71
72 5. Remarks
73
74 1. Overview
75
76 The module is a XCAP client for Kamailio that can be used by other
77 modules. It fetches XCAP elements, either documents or part of them, by
78 sending HTTP GET requests to an XCAP server. It also offers support for
79 conditional queries. It uses the libcurl library as a client-side HTTP
80 transfer library.
81
82 The module offers a XCAP client interface with general functions that
83 allow requesting for a specific element from a XCAP server. In addition
84 to that it also offers the service of storing and updating the
85 documents it receives. In this case only an initial request to the
86 module is required - xcapGetNewDoc - which is like a request to the
87 module to handle from that point on the referenced document so as to
88 promise that the newest version will always be present in database.
89
90 The update method is also configurable, either through periodical
91 queries, applicable to any kind of XCAP server or with a management
92 command that should be sent by the server upon an update.
93
94 The module is currently used by the “presence_xml” module, if the
95 'integrated_xcap_server' parameter is not set.
96
97 2. Dependencies
98
99 2.1. Kamailio Modules
100 2.2. External Libraries or Applications
101
102 2.1. Kamailio Modules
103
104 The module is not dependent of any Kamailio module.
105
106 2.2. External Libraries or Applications
107
108 The following libraries or applications must be installed before
109 running Kamailio with this module loaded:
110 * libxml.
111 * libcurl.
112
113 3. Parameters
114
115 3.1. db_url(str)
116 3.2. xcap_table(str)
117 3.3. periodical_query(int)
118 3.4. query_period(int)
119
120 3.1. db_url(str)
121
122 The database url.
123
124 Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.
125
126 Example 1.1. Set db_url parameter
127 ...
128 modparam("xcap_client", "db_url", "dbdriver://username:password@dbhost/dbname")
129 ...
130
131 3.2. xcap_table(str)
132
133 The name of the db table where XCAP documents are stored.
134
135 Default value is “xcap”.
136
137 Example 1.2. Set xcap_table parameter
138 ...
139 modparam("xcap_client", "xcap_table", "xcaps")
140 ...
141
142 3.3. periodical_query(int)
143
144 A flag to disable periodical query as an update method for the
145 documents the module is responsible for. It could be disabled when the
146 XCAP server is capable to send the exported management command when a
147 change occurs or when another module in Kamailio handles updates.
148
149 To disable it set this parameter to 0.
150
151 Default value is “1”.
152
153 Example 1.3. Set periodical_query parameter
154 ...
155 modparam("xcap_client", "periodical_query", 0)
156 ...
157
158 3.4. query_period(int)
159
160 Should be set if periodical query is not disabled. Represents the time
161 interval the XCAP servers should be queried for an update.
162
163 To disable it set this parameter to 0.
164
165 Default value is “100”.
166
167 Example 1.4. Set query_period parameter
168 ...
169 modparam("xcap_client", "query_period", 50)
170 ...
171
172 4. RPC Commands
173
174 4.1. xcap_client.refreshXcapDoc
175
176 4.1. xcap_client.refreshXcapDoc
177
178 Management command that should be sent by an XCAP server when a stored
179 document changes.
180
181 Name: xcap_client.refreshXcapDoc
182
183 Parameters:
184 * document uri: the uri of the document
185 * xcap server port: the port of the xcap server
186
187 RPC Command Example:
188 ...
189 # execute in a single line command
190 kamctl rpc xcap_client.refreshXcapDoc
191 /xcap-root/resource-lists/users/eyebeam/buddies-resource-list.xml 8000
192 ...
193
194 5. Remarks
195
196 Note: libcurl leak in CentOS 6 - this module uses libcurl library and
197 in case if you are using CentOS 6, be aware that standard
198 libcurl-7.19.7-52 has a memory leak. To fix this memory, install
199 libcurl from city-fan repository. More details at:
200 https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in
201 -centos6
202
203 Chapter 2. Developer Guide
204
205 Table of Contents
206
207 1. bind_xcap_api(xcap_api_t* api)
208 2. get_elem
209 3. register_xcb
210
211 The module exports a number of functions that allow selecting and
212 retrieving an element from an xcap server and also registering a
213 callback to be called when the management command refreshXcapDoc is
214 received and the document in question is retrieved.
215
216 1. bind_xcap_api(xcap_api_t* api)
217
218 This function allows binding the needed functions.
219
220 Example 2.1. xcap_api structure
221 ...
222 typedef struct xcap_api {
223
224 /* xcap node selection and retrieving functions*/
225 xcap_get_elem_t get_elem;
226 xcap_nodeSel_init_t int_node_sel;
227 xcap_nodeSel_add_step_t add_step;
228 xcap_nodeSel_add_terminal_t add_terminal;
229 xcap_nodeSel_free_t free_node_sel;
230 xcapGetNewDoc_t getNewDoc; /* an initial request for the module
231 to fetch this document that does not exist in xcap db table
232 and handle its update*/
233
234 /* function to register a callback to document changes*/
235 register_xcapcb_t register_xcb;
236 }xcap_api_t;
237 ...
238
239 2. get_elem
240
241 Field type:
242 ...
243 typedef char* (*xcap_get_elem_t)(char* xcap_root,
244 xcap_doc_sel_t* doc_sel, xcap_node_sel_t* node_sel);
245 ...
246
247 This function sends a HTTP request and gets the specified information
248 from the xcap server.
249
250 The parameters signification:
251 * xcap_root- the XCAP server address;
252 * doc_sel- structure with document selection info;
253 Parameter type:
254 ...
255 typedef struct xcap_doc_sel
256 {
257 str auid; /* application defined Unique ID*/
258 int type; /* the type of the path segment
259 after the AUID which must either
260 be GLOBAL_TYPE (for "global") or
261 USERS_TYPE (for "users") */
262 str xid; /* the XCAP User Identifier
263 if type is USERS_TYPE */
264 str filename;
265 }xcap_doc_sel_t;
266 ...
267 * node_sel- structure with node selection info;
268 Parameter type:
269 ...
270 typedef struct xcap_node_sel
271 {
272 step_t* steps;
273 step_t* last_step;
274 int size;
275 ns_list_t* ns_list;
276 ns_list_t* last_ns;
277 int ns_no;
278
279 }xcap_node_sel_t;
280
281 typedef struct step
282 {
283 str val;
284 struct step* next;
285 }step_t;
286
287 typedef struct ns_list
288 {
289 int name;
290 str value;
291 struct ns_list* next;
292 }ns_list_t;
293 ...
294 The node selector is represented like a list of steps that will be
295 represented in the path string separated by '/' signs. The
296 namespaces for the nodes are stored also in a list, as an
297 association of name and value, where the value is to be included in
298 the respective string val field of the step.
299 To construct the node structure the following functions in the
300 xcap_api structure should be used: 'int_node_sel', 'add_step' and
301 if needed, 'add_terminal'.
302 If the intention is to retrieve the whole document this argument
303 must be NULL.
304
305 3. register_xcb
306
307 Field type:
308 ...
309 typedef int (*register_xcapcb_t)(int types, xcap_cb f);
310 ...
311
312 - 'types' parameter can have a combined value of PRES_RULES,
313 RESOURCE_LIST, RLS_SERVICES and PIDF_MANIPULATION.
314
315 -the callback function has type :
316 ...
317 typedef int (xcap_cb)(int doc_type, str xid, char* doc);
318 ...