Browse code

doc: reorganized the content of doc folder

Daniel-Constantin Mierla authored on 07/12/2016 13:54:42
Showing 1 changed files
1 1
deleted file mode 100644
... ...
@@ -1,458 +0,0 @@
1
-<?xml version='1.0' encoding='UTF-8'?>
2
-<!DOCTYPE section PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'
3
-	'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'>
4
-
5
-<section><title>XCAP</title>
6
-
7
-<section><title>Introduction</title>
8
-
9
-<para>XCAP is a HTTP based protocol for access remote configuration data. Data
10
-is stored in XML format and the XCAP protocol allows to query, modify or delete
11
-parts of such data. This is in detail described in <xref
12
-linkend="pres_rfc_xcap"/>. The XCAP server is server able to handle XCAP requests.
13
-</para>
14
-
15
-<para>The XCAP server may be used for storing <quote>presence interesting</quote>
16
-data. From the SIP_ROUTER's point of view these items are interesting:
17
-<itemizedlist>
18
-	<listitem><para>authorization data</para></listitem>
19
-	<listitem><para><quote>buddy lists</quote></para></listitem>
20
-</itemizedlist>
21
-</para>
22
-
23
-<section><title>XCAP authorization</title>
24
-<para>Definition of authorization documents and theirs usage is specified in <xref 
25
-linkend="pres_draft_common_auth"/> and especially for presence purposes in <xref 
26
-linkend="pres_draft_auth"/>. Both documents are quite common and in SIP_ROUTER's
27
-presence modules implemented only partialy. For more information about XCAP
28
-authorization see details in <xref linkend="pa.xcap"/>.</para>
29
-</section> <!-- XCAP authorization -->
30
-
31
-<section><title>Buddy lists</title>
32
-<para>XCAP server may be used for storing lists of users too. These lists may be
33
-used for presence subscriptions - subscription to such list means subscription
34
-to all users on it at once. This reduces number of created subscriptions and may
35
-reduce data transfers between server and client too; but presence documents for
36
-lists of users may be very big and thus require TCP connection.</para>
37
-
38
-<para>There may be not only lists for individual users with their contacts but 
39
-there may be other sort of lists representing some <quote>logical
40
-entities</quote> such <quote>businessmen</quote>, <quote>technical
41
-support</quote>, ... which are used in cases like if some customer needs someone
42
-from technical support department and doesn't want to remeber all people
43
-there. Such customer may simply watch presence state of
44
-<quote>technical-support@somewhere.net</quote> if he needs help from them.
45
-</para>
46
-
47
-<para>Lists of users - more common resource lists - are defined in <xref
48
-linkend="pres_draft_rls"/> and their usage with SIP in <xref
49
-linkend="pres_draft_rls_sip"/>. These lists are partialy implemented in <link
50
-linkend="pres_rls">RLS module</link>.
51
-For more information about resource lists see details in <xref
52
-linkend="rls.xcap"/>.</para>
53
-</section> <!-- buddy lists -->
54
-
55
-<section><title>Manipulation with XCAP documents</title>
56
-<para>Manipulating with XCAP documents is quite simple because XCAP uses
57
-standard HTTP methods like GET, PUT or DELETE. Every web browser may be
58
-used to read XCAP data and it is quite simple to write utility to write data
59
-to XCAP server. These features allow to use XCAP with SIP_ROUTER although there are is 
60
-not much client software supporting it.
61
-</para>
62
-</section> <!-- manipulating documents -->
63
-
64
-</section> <!-- XCAP introduction -->
65
-
66
-<section id="xcap.examples"><title>XCAP examples</title>
67
-<note><para>XCAP documents examples published there doesn't use correct XML
68
-namespaces due to problems with XCAP server used for tests (problems querying
69
-partial documents with namespaces).</para></note>
70
-
71
-<example><title>Storing XCAP documents</title>
72
-<para>There is a sample script in Python which stores XCAP documents onto a XCAP
73
-server. Documents are:
74
-<itemizedlist>
75
-	<listitem><para><link linkend="rls.xml">rls-services document</link> stored
76
-	under name <filename>index</filename>
77
-	</para></listitem>
78
-	<listitem><para><link linkend="list.xml">buddy list</link> for user Smith
79
-	stored under name <filename>smith</filename></para></listitem>
80
-	<listitem><para><link linkend="pres-rules.xml">presence authorization
81
-	document</link> for user Smith stored under name
82
-	<filename>presence-rules.xml</filename></para></listitem>
83
-</itemizedlist>
84
-</para>
85
-<programlisting>
86
-#!/usr/bin/python
87
-import httplib, urllib
88
-
89
-machine = "localhost"
90
-
91
-#
92
-# store rls-services document
93
-#
94
-
95
-uri = "/xcap-root/rls-services/global/index"
96
-headers = {"Content-Type": "application/rls-services+xml"}
97
-bf = file("rls.xml", "r")
98
-body = bf.read(65536);
99
-conn = httplib.HTTPConnection(machine)
100
-conn.request("PUT", uri, body, headers)
101
-
102
-response = conn.getresponse()
103
-print "Storing rls-services document: ", response.status, response.reason
104
-data = response.read()
105
-conn.close()
106
-
107
-#
108
-# store resource-list document for user
109
-#
110
-
111
-uri = "/xcap-root/resource-lists/users/smith/resource-list.xml"
112
-headers = {"Content-Type": "application/resource-lists+xml"}
113
-bf = file("list.xml", "r")
114
-body = bf.read(65536);
115
-conn = httplib.HTTPConnection(machine)
116
-conn.request("PUT", uri, body, headers)
117
-
118
-response = conn.getresponse()
119
-print "Storing resource-lists document: ", response.status, response.reason
120
-data = response.read()
121
-conn.close()
122
-
123
-#
124
-# store presence authorization rules
125
-#
126
-
127
-uri = "/xcap-root/pres-rules/users/smith/presence-rules.xml"
128
-headers = {"Content-Type": "application/pres-rules+xml"}
129
-bf = file("presence-rules.xml", "r")
130
-body = bf.read(65536);
131
-conn = httplib.HTTPConnection(machine)
132
-conn.request("PUT", uri, body, headers)
133
-
134
-response = conn.getresponse()
135
-print "Storing pres-rules document: ", response.status, response.reason
136
-data = response.read()
137
-conn.close()
138
-</programlisting>
139
-</example>
140
-
141
-<example id="list.xml"><title>Example resource list document (list.xml)</title>
142
-<para>Simple buddy lists which shows the possibility of nested lists.
143
-</para>
144
-<programlisting>
145
-&lt;?xml version="1.0" ?&gt;
146
-&lt;resource-lists&gt;
147
-	&lt;list name="default"&gt;
148
-		&lt;list name="work"&gt;
149
-			&lt;entry uri="sip:someone@someorg.org"&gt;
150
-				&lt;display-name&gt;Someone&lt;/display-name&gt;
151
-			&lt;/entry&gt;
152
-			&lt;entry uri="sip:smith@someorg.org"&gt;
153
-				&lt;display-name&gt;Jonathan Smith&lt;/display-name&gt;
154
-			&lt;/entry&gt;
155
-		&lt;/list&gt;
156
-		&lt;entry uri="sip:vasek@someorg.org"&gt;
157
-			&lt;display-name&gt;Vasek&lt;/display-name&gt;
158
-		&lt;/entry&gt;
159
-		&lt;entry uri="sip:vaclav.picbumprask@someorg.org"&gt;
160
-			&lt;display-name&gt;Vaclav Picbumprask&lt;/display-name&gt;
161
-		&lt;/entry&gt;
162
-	&lt;/list&gt;
163
-&lt;/resource-lists&gt;
164
-</programlisting>
165
-</example>
166
-
167
-<example id="rls.xml"><title>Example rls-services document (rls.xml)</title>
168
-<para>Example document which is processed by Resource List Server (RLS module).
169
-This document can contain references to users buddy lists like
170
-<quote>smith-list@someorg.org</quote> which points to buddy list for user smith
171
-named <quote>default</quote> and can contain such lists directly.
172
-<!--<caution><para>EyeBeam stores user's <quote>buddy list</quote> in 
173
-<filename>&lt;XCAP-root&gt;/users/&lt;username&gt;/resource-list.xml</filename>, 
174
-not in
175
-<filename>&lt;XCAP-root&gt;/users/&lt;username&gt;</filename> which was used in 
176
-these examples.</para></caution>-->
177
-</para>
178
-<programlisting>
179
-&lt;?xml version="1.0" encoding="UTF-8"?&gt;
180
-&lt;rls-services&gt;
181
-	&lt;service uri="sip:smith-list@someorg.org"&gt;
182
-		&lt;resource-list&gt;http://localhost/xcap-root/resource-lists/users/smith/resource-list.xml/~~/resource-lists/list[@name=%22default%22]&lt;/resource-list&gt;
183
-		&lt;packages&gt;
184
-			&lt;package&gt;presence&lt;/package&gt;
185
-		&lt;/packages&gt;
186
-	&lt;/service&gt;
187
-	&lt;service uri="sip:cz@someorg.org"&gt;
188
-		&lt;list name="czech part of some org"&gt;
189
-			&lt;entry uri="sip:abc@someorg.org"&gt;
190
-				&lt;display-name&gt;A B&lt;/display-name&gt;
191
-			&lt;/entry&gt;
192
-			&lt;entry uri="sip:cde@someorg.org"&gt;
193
-				&lt;display-name&gt;C D&lt;/display-name&gt;
194
-			&lt;/entry&gt;
195
-			&lt;entry uri="sip:efg@someorg.org"&gt;
196
-				&lt;display-name&gt;Ef Ge&lt;/display-name&gt;
197
-			&lt;/entry&gt;
198
-		&lt;/list&gt;
199
-		&lt;packages&gt;
200
-			&lt;package&gt;presence&lt;/package&gt;
201
-			&lt;package&gt;email&lt;/package&gt;
202
-		&lt;/packages&gt;
203
-	&lt;/service&gt;
204
-&lt;/rls-services&gt;
205
-</programlisting>
206
-</example>
207
-
208
-<example id="pres-rules.xml"><title>Example presence authorization document (presence-rules.xml)</title>
209
-<para>This document contains two rules: 
210
-<itemizedlist>
211
-	<listitem><para><quote>white list</quote>, which allows
212
-	access to presence information from all from domain someorg.org
213
-	</para></listitem>
214
-	<listitem><para><quote>black list</quote>, which denies access for user
215
-	nemo@somewhere.net</para></listitem>	
216
-</itemizedlist></para>
217
-<programlisting>
218
-&lt;?xml version="1.0" ?&gt;
219
-&lt;ruleset xmlns="urn:ietf:params:xml:ns:common-policy" xmlns:pr="urn:ietf:params:xml:ns:pres-rules"&gt;
220
-	&lt;rule id="blacklist"&gt;
221
-		&lt;conditions&gt;
222
-			&lt;identity&gt;
223
-				&lt;id&gt;sip:nemo@somewhere.net&lt;/id&gt;
224
-			&lt;/identity&gt;
225
-		&lt;/conditions&gt;
226
-		&lt;actions&gt;
227
-			&lt;pr:sub-handling&gt;block&lt;/pr:sub-handling&gt;
228
-		&lt;/actions&gt;
229
-		&lt;transformations/&gt;
230
-	&lt;/rule&gt;
231
-	
232
-	&lt;rule id="whitelist"&gt;
233
-		&lt;conditions&gt;
234
-			&lt;identity&gt;
235
-				&lt;domain domain="someorg.org"/&gt;
236
-			&lt;/identity&gt;
237
-		&lt;/conditions&gt;
238
-		&lt;actions&gt;
239
-			&lt;pr:sub-handling&gt;allow&lt;/pr:sub-handling&gt;
240
-		&lt;/actions&gt;
241
-		&lt;transformations/&gt;
242
-	&lt;/rule&gt;
243
-&lt;/ruleset&gt;
244
-</programlisting>
245
-</example>
246
-
247
-</section>
248
-
249
-<!-- There
250
-exist extensions for particular types of configuration - for purpose of this
251
-document only configuration from presence area will be mentioned.
252
-</para>-->
253
-
254
-<section><title>XCAP server simulation</title>
255
-<para>XCAP server is a HTTP server with some features like document validation
256
-or ability of working with parts of stored documents. If you have no XCAP
257
-server, you can simulate it using standard web server. There are not many XCAP
258
-servers available today, thus the simulation may be interesting for - at least -
259
-demonstration or testing purposes.
260
-</para>
261
-
262
-<para>There are some disadvantages when the XCAP server is only simulated:
263
-<itemizedlist>
264
-	<listitem><para>no XML document validation</para></listitem>
265
-	<listitem><para>unable to work with XPointer terms (mainly unable to work 
266
-	with parts of documents)</para></listitem>
267
-	<listitem><para>possible synchronization problems (!)</para>
268
-		<para>More clients used by one user working with the same document
269
-		 (authorization document, buddy list) may rewrite it to each other.
270
-		 When using regular XCAP server this will be done in one atomic query.
271
-		 In the case of simulation it is needed to download whole document,
272
-		 modify it and put it back.</para>
273
-	 </listitem>
274
-</itemizedlist>
275
-</para>
276
-
277
-<para>Depending on your needs you can
278
-<itemizedlist>
279
-	<listitem><para>create hierarchical directory structure of XML documents according to
280
-	<xref linkend="pres_rfc_xcap"/></para></listitem>
281
-	<listitem><para>allow upload (handle HTTP PUT method) which stores documents into the 
282
-	directory structure</para></listitem>
283
-	<listitem><para>improve upload to validate documents according to schema
284
-	(every sort of XCAP document should have their XSD published)</para></listitem>
285
-	<listitem><para>allow document removing (handle DELETE method)</para></listitem>
286
-	<listitem><para>process HTTP GET requests with a CGI-script so it processes
287
-	queries for partial documents</para></listitem>
288
-</itemizedlist>
289
-</para>
290
-
291
-<section><title>Directory structure</title>
292
-<para>Presence modules use XCAP documents stored in structure like this:
293
-<itemizedlist><title>xcap-root</title>
294
-	<listitem><para><filename>pres-rules</filename></para>
295
-	<itemizedlist>
296
-		<listitem><para><filename>users</filename></para>
297
-		<itemizedlist>
298
-			<listitem><para><filename>smith</filename></para>
299
-			<itemizedlist>
300
-				<listitem><para><filename>presence-rules.xml</filename> (file
301
-				containg presence authorization rules for user smith)</para></listitem>
302
-			</itemizedlist>
303
-			</listitem>
304
-			<listitem><para><filename>joe</filename></para>
305
-			<itemizedlist>
306
-				<listitem><para><filename>presence-rules.xml</filename> (file containing
307
-				presence authorization rules for user joe)</para></listitem>
308
-			</itemizedlist>
309
-			</listitem>
310
-			<listitem><para>... (directories for other users)</para></listitem>
311
-		</itemizedlist>
312
-		</listitem>
313
-	</itemizedlist></listitem>
314
-	
315
-	<listitem><para><filename>resource-lists</filename></para>
316
-	<itemizedlist>
317
-		<listitem><para><filename>users</filename></para>
318
-		<itemizedlist>
319
-			<listitem><para><filename>smith</filename></para>
320
-			<itemizedlist>
321
-				<listitem><para><filename>resource-list.xml</filename> (file
322
-				containing resources lists for user smith)</para></listitem>
323
-			</itemizedlist>
324
-			</listitem>
325
-			<listitem><para><filename>joe</filename></para>
326
-			<itemizedlist>
327
-				<listitem><para><filename>resource-list.xml</filename> (file
328
-				containing resource lists for user joe)</para></listitem>
329
-			</itemizedlist>
330
-			</listitem>
331
-			<listitem><para>... (directories for other users)</para></listitem>
332
-		</itemizedlist>
333
-		</listitem>
334
-		<!-- rls-services globals used instead this
335
-		<listitem><para><filename>global</filename></para>
336
-		<itemizedlist>
337
-			<listitem><para><filename>index</filename> (file containing global
338
-			resource lists)</para></listitem>
339
-		</itemizedlist>
340
-		</listitem>-->
341
-	</itemizedlist></listitem>
342
-	
343
-	<listitem><para><filename>rls-services</filename></para>
344
-	<itemizedlist>
345
-		<listitem><para><filename>global</filename></para>
346
-		<itemizedlist>
347
-			<listitem><para><filename>index</filename> (file containing global
348
-			rls-services documents)</para></listitem>
349
-		</itemizedlist>
350
-		</listitem>
351
-	</itemizedlist></listitem>
352
-	
353
-</itemizedlist>
354
-</para>
355
-</section> <!-- directory structure -->
356
-
357
-<section><title>Usage with SIP_ROUTER</title>
358
-<para>You don't need a full XCAP server for presence authorization documents -
359
-these are read as standalone documents from directories of standalone users.
360
-</para>
361
-
362
-<para>For resource lists you have to set <link linkend="rls.parameters">RLS module 
363
-parameters</link> <varname>mode</varname> and/or
364
-<varname>reduce_xcap_needs</varname> 
365
-to work as much as possible with XCAP server simulation.
366
-</para>
367
-</section>
368
-
369
-<section><title>XCAP simulation examples</title>
370
-<para>Examples presented here can be used as simple XCAP server simulation. It
371
-is able to handle PUT method (for whole XML documents).
372
-</para>
373
-
374
-<example><title>Apache2 configuration</title>
375
-<programlisting><![CDATA[
376
-...
377
-Alias /xcap-root /var/simulated-xcap-root
378
-<Directory /var/simulated-xcap-root>
379
-	Options Indexes FollowSymLinks MultiViews
380
-	Script PUT /cgi-bin/upload
381
-	<Limit PUT DELETE GET>
382
-		Order Allow,Deny
383
-		Deny from none
384
-		Allow from all
385
-	</Limit>
386
-</Directory>
387
-...
388
-]]></programlisting>
389
-<para>If apache is running on machine with SIP_ROUTER, you can use as xcap-root
390
-<literal>http://localhost/xcap-root</literal>.
391
-</para>
392
-</example>
393
-
394
-<example><title>Simple (and dangerous) cgi-script for upload</title>
395
-<para>This code is written in C and it is able to create directories if needed, but its usage in
396
-presented form is realy unsafe! You have to compile it and put into directory
397
-with other CGI scripts.</para>
398
-<programlisting><![CDATA[
399
-#include <stdio.h>
400
-#include <stdlib.h>
401
-#include <string.h>
402
-
403
-#include <sys/stat.h>
404
-#include <sys/types.h>
405
-
406
-void copy_file(const char *filename)
407
-{
408
-	char buf[2048];
409
-	int r;
410
-	FILE *f;
411
-	
412
-	f = fopen(filename, "wb");
413
-	if (f) {
414
-		while (!feof(stdin)) {
415
-			r = fread(buf, 1, sizeof(buf), stdin);
416
-			fwrite(buf, 1, r, f);
417
-		}
418
-		fclose(f);
419
-	}
420
-}
421
-
422
-int main(int argc, char **argv)
423
-{
424
-	char *filename, *x;
425
-	char tmp[1024];
426
-	int res = 0;
427
-	
428
-	filename = getenv ("PATH_TRANSLATED");
429
-
430
-	strcpy(tmp, filename);
431
-	x = strrchr(tmp, '/');
432
-	if (x) {
433
-		*x = 0;
434
-		res = mkdir(tmp, 0755);		/* ! dangerous ! */
435
-	}
436
-	else {
437
-		printf("Status: 500\n");
438
-		printf("Content-Type: text/html\n\n");
439
-		printf("<html><head/>\n<body>Incorrect filename</body></html>\n");	
440
-		return -1;
441
-	}
442
-	
443
-	copy_file(filename); /* ! dangerous ! */
444
-		
445
-	printf("Status: 200\n");
446
-	printf("Content-Type: text/html\n\n");
447
-	printf("<html><head><title>Upload</title>\n</head>\n<body>Finished...</body></html>\n");
448
-	
449
-	return 0;
450
-}
451
-]]></programlisting>
452
-</example>
453
-
454
-</section><!-- XCAP simulation examples -->
455
-
456
-</section> <!-- XCAP server simulation -->
457
-
458
-</section>
Browse code

Updates to presence documentation

oej authored on 22/10/2009 18:44:46
Showing 1 changed files
... ...
@@ -7,13 +7,13 @@
7 7
 <section><title>Introduction</title>
8 8
 
9 9
 <para>XCAP is a HTTP based protocol for access remote configuration data. Data
10
-is stored in XML format and XCAP protocol allows to query, modify or delete
10
+is stored in XML format and the XCAP protocol allows to query, modify or delete
11 11
 parts of such data. This is in detail described in <xref
12
-linkend="pres_draft_xcap"/>. XCAP server is server able to handle XCAP requests.
12
+linkend="pres_rfc_xcap"/>. The XCAP server is server able to handle XCAP requests.
13 13
 </para>
14 14
 
15
-<para>XCAP server may be used for storing <quote>presence interesting</quote>
16
-data. From the SER's point of view are interesting:
15
+<para>The XCAP server may be used for storing <quote>presence interesting</quote>
16
+data. From the SIP_ROUTER's point of view these items are interesting:
17 17
 <itemizedlist>
18 18
 	<listitem><para>authorization data</para></listitem>
19 19
 	<listitem><para><quote>buddy lists</quote></para></listitem>
... ...
@@ -23,7 +23,7 @@ data. From the SER's point of view are interesting:
23 23
 <section><title>XCAP authorization</title>
24 24
 <para>Definition of authorization documents and theirs usage is specified in <xref 
25 25
 linkend="pres_draft_common_auth"/> and especially for presence purposes in <xref 
26
-linkend="pres_draft_auth"/>. Both documents are quite common and in SER's
26
+linkend="pres_draft_auth"/>. Both documents are quite common and in SIP_ROUTER's
27 27
 presence modules implemented only partialy. For more information about XCAP
28 28
 authorization see details in <xref linkend="pa.xcap"/>.</para>
29 29
 </section> <!-- XCAP authorization -->
... ...
@@ -56,7 +56,7 @@ linkend="rls.xcap"/>.</para>
56 56
 <para>Manipulating with XCAP documents is quite simple because XCAP uses
57 57
 standard HTTP methods like GET, PUT or DELETE. Every web browser may be
58 58
 used to read XCAP data and it is quite simple to write utility to write data
59
-to XCAP server. These features allow to use XCAP with SER although there are is 
59
+to XCAP server. These features allow to use XCAP with SIP_ROUTER although there are is 
60 60
 not much client software supporting it.
61 61
 </para>
62 62
 </section> <!-- manipulating documents -->
... ...
@@ -277,7 +277,7 @@ demonstration or testing purposes.
277 277
 <para>Depending on your needs you can
278 278
 <itemizedlist>
279 279
 	<listitem><para>create hierarchical directory structure of XML documents according to
280
-	<xref linkend="pres_draft_xcap"/></para></listitem>
280
+	<xref linkend="pres_rfc_xcap"/></para></listitem>
281 281
 	<listitem><para>allow upload (handle HTTP PUT method) which stores documents into the 
282 282
 	directory structure</para></listitem>
283 283
 	<listitem><para>improve upload to validate documents according to schema
... ...
@@ -354,7 +354,7 @@ demonstration or testing purposes.
354 354
 </para>
355 355
 </section> <!-- directory structure -->
356 356
 
357
-<section><title>Usage with SER</title>
357
+<section><title>Usage with SIP_ROUTER</title>
358 358
 <para>You don't need a full XCAP server for presence authorization documents -
359 359
 these are read as standalone documents from directories of standalone users.
360 360
 </para>
... ...
@@ -386,7 +386,7 @@ Alias /xcap-root /var/simulated-xcap-root
386 386
 </Directory>
387 387
 ...
388 388
 ]]></programlisting>
389
-<para>If apache is running on machine with SER, you can use as xcap-root
389
+<para>If apache is running on machine with SIP_ROUTER, you can use as xcap-root
390 390
 <literal>http://localhost/xcap-root</literal>.
391 391
 </para>
392 392
 </example>
Browse code

cosmetical changes in presence handbook

Vaclav Kubart authored on 28/05/2007 11:33:01
Showing 1 changed files
... ...
@@ -146,18 +146,18 @@ conn.close()
146 146
 &lt;resource-lists&gt;
147 147
 	&lt;list name="default"&gt;
148 148
 		&lt;list name="work"&gt;
149
-			&lt;entry uri="sip:someone@iptel.org"&gt;
149
+			&lt;entry uri="sip:someone@someorg.org"&gt;
150 150
 				&lt;display-name&gt;Someone&lt;/display-name&gt;
151 151
 			&lt;/entry&gt;
152
-			&lt;entry uri="sip:smith@iptel.org"&gt;
152
+			&lt;entry uri="sip:smith@someorg.org"&gt;
153 153
 				&lt;display-name&gt;Jonathan Smith&lt;/display-name&gt;
154 154
 			&lt;/entry&gt;
155 155
 		&lt;/list&gt;
156
-		&lt;entry uri="sip:vasek@iptel.org"&gt;
156
+		&lt;entry uri="sip:vasek@someorg.org"&gt;
157 157
 			&lt;display-name&gt;Vasek&lt;/display-name&gt;
158 158
 		&lt;/entry&gt;
159
-		&lt;entry uri="sip:vaclav.kubart@iptel.org"&gt;
160
-			&lt;display-name&gt;Vaclav Kubart&lt;/display-name&gt;
159
+		&lt;entry uri="sip:vaclav.picbumprask@someorg.org"&gt;
160
+			&lt;display-name&gt;Vaclav Picbumprask&lt;/display-name&gt;
161 161
 		&lt;/entry&gt;
162 162
 	&lt;/list&gt;
163 163
 &lt;/resource-lists&gt;
... ...
@@ -167,7 +167,7 @@ conn.close()
167 167
 <example id="rls.xml"><title>Example rls-services document (rls.xml)</title>
168 168
 <para>Example document which is processed by Resource List Server (RLS module).
169 169
 This document can contain references to users buddy lists like
170
-<quote>smith-list@iptel.org</quote> which points to buddy list for user smith
170
+<quote>smith-list@someorg.org</quote> which points to buddy list for user smith
171 171
 named <quote>default</quote> and can contain such lists directly.
172 172
 <!--<caution><para>EyeBeam stores user's <quote>buddy list</quote> in 
173 173
 <filename>&lt;XCAP-root&gt;/users/&lt;username&gt;/resource-list.xml</filename>, 
... ...
@@ -178,21 +178,21 @@ these examples.</para></caution>-->
178 178
 <programlisting>
179 179
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
180 180
 &lt;rls-services&gt;
181
-	&lt;service uri="sip:smith-list@iptel.org"&gt;
181
+	&lt;service uri="sip:smith-list@someorg.org"&gt;
182 182
 		&lt;resource-list&gt;http://localhost/xcap-root/resource-lists/users/smith/resource-list.xml/~~/resource-lists/list[@name=%22default%22]&lt;/resource-list&gt;
183 183
 		&lt;packages&gt;
184 184
 			&lt;package&gt;presence&lt;/package&gt;
185 185
 		&lt;/packages&gt;
186 186
 	&lt;/service&gt;
187
-	&lt;service uri="sip:cz@iptel.org"&gt;
188
-		&lt;list name="czech iptel"&gt;
189
-			&lt;entry uri="sip:abc@iptel.org"&gt;
187
+	&lt;service uri="sip:cz@someorg.org"&gt;
188
+		&lt;list name="czech part of some org"&gt;
189
+			&lt;entry uri="sip:abc@someorg.org"&gt;
190 190
 				&lt;display-name&gt;A B&lt;/display-name&gt;
191 191
 			&lt;/entry&gt;
192
-			&lt;entry uri="sip:cde@iptel.org"&gt;
192
+			&lt;entry uri="sip:cde@someorg.org"&gt;
193 193
 				&lt;display-name&gt;C D&lt;/display-name&gt;
194 194
 			&lt;/entry&gt;
195
-			&lt;entry uri="sip:efg@iptel.org"&gt;
195
+			&lt;entry uri="sip:efg@someorg.org"&gt;
196 196
 				&lt;display-name&gt;Ef Ge&lt;/display-name&gt;
197 197
 			&lt;/entry&gt;
198 198
 		&lt;/list&gt;
... ...
@@ -209,7 +209,7 @@ these examples.</para></caution>-->
209 209
 <para>This document contains two rules: 
210 210
 <itemizedlist>
211 211
 	<listitem><para><quote>white list</quote>, which allows
212
-	access to presence information from all from domain iptel.org
212
+	access to presence information from all from domain someorg.org
213 213
 	</para></listitem>
214 214
 	<listitem><para><quote>black list</quote>, which denies access for user
215 215
 	nemo@somewhere.net</para></listitem>	
... ...
@@ -232,7 +232,7 @@ these examples.</para></caution>-->
232 232
 	&lt;rule id="whitelist"&gt;
233 233
 		&lt;conditions&gt;
234 234
 			&lt;identity&gt;
235
-				&lt;domain domain="iptel.org"/&gt;
235
+				&lt;domain domain="someorg.org"/&gt;
236 236
 			&lt;/identity&gt;
237 237
 		&lt;/conditions&gt;
238 238
 		&lt;actions&gt;
Browse code

presence handbook updated a bit (still not fully done)

Vaclav Kubart authored on 16/02/2007 07:37:35
Showing 1 changed files
... ...
@@ -65,7 +65,7 @@ not much client software supporting it.
65 65
 
66 66
 <section id="xcap.examples"><title>XCAP examples</title>
67 67
 <note><para>XCAP documents examples published there doesn't use correct XML
68
-namespaces due to problems with XCAP server used for tests (probles querying
68
+namespaces due to problems with XCAP server used for tests (problems querying
69 69
 partial documents with namespaces).</para></note>
70 70
 
71 71
 <example><title>Storing XCAP documents</title>
Browse code

- updated presence handbook and pa and rls documentation - cosmetical changes in rls and pa (removed unused parameters)

Vaclav Kubart authored on 30/03/2006 14:13:23
Showing 1 changed files
... ...
@@ -24,16 +24,16 @@ data. From the SER's point of view are interesting:
24 24
 <para>Definition of authorization documents and theirs usage is specified in <xref 
25 25
 linkend="pres_draft_common_auth"/> and especially for presence purposes in <xref 
26 26
 linkend="pres_draft_auth"/>. Both documents are quite common and in SER's
27
-presence modules implemented only partialy.
28
-</para>
27
+presence modules implemented only partialy. For more information about XCAP
28
+authorization see details in <xref linkend="pa.xcap"/>.</para>
29 29
 </section> <!-- XCAP authorization -->
30 30
 
31 31
 <section><title>Buddy lists</title>
32 32
 <para>XCAP server may be used for storing lists of users too. These lists may be
33 33
 used for presence subscriptions - subscription to such list means subscription
34
-to all users at once. This reduces number of created subscriptions and may
34
+to all users on it at once. This reduces number of created subscriptions and may
35 35
 reduce data transfers between server and client too; but presence documents for
36
-lists of users may be very big.</para>
36
+lists of users may be very big and thus require TCP connection.</para>
37 37
 
38 38
 <para>There may be not only lists for individual users with their contacts but 
39 39
 there may be other sort of lists representing some <quote>logical
... ...
@@ -48,7 +48,8 @@ there. Such customer may simply watch presence state of
48 48
 linkend="pres_draft_rls"/> and their usage with SIP in <xref
49 49
 linkend="pres_draft_rls_sip"/>. These lists are partialy implemented in <link
50 50
 linkend="pres_rls">RLS module</link>.
51
-</para>
51
+For more information about resource lists see details in <xref
52
+linkend="rls.xcap"/>.</para>
52 53
 </section> <!-- buddy lists -->
53 54
 
54 55
 <section><title>Manipulation with XCAP documents</title>
... ...
@@ -62,118 +63,6 @@ not much client software supporting it.
62 63
 
63 64
 </section> <!-- XCAP introduction -->
64 65
 
65
-<section><title>XCAP authorization and SER</title>
66
-
67
-<section><title>Authorization document URI</title>
68
-<para>Authorization documents are read for presentities according to their presentity
69
-URIs. Presentity URI is AOR of SUBSCRIBE request. Resulting URI will be:</para>
70
-<para>
71
-<filename>&lt;xcap-root&gt;/pres-rules/users/&lt;username&gt;/presence-rules.xml</filename>
72
-where <parameter>&lt;xcap-root&gt;</parameter> is set in configuration and
73
-<parameter>&lt;username&gt;</parameter> is username from presentity URI.
74
-</para>
75
-
76
-<example><title>authorization document uri</title>
77
-<para>For example for presentity <literal>sip:smith@iptel.org</literal> and
78
-<parameter>xcap-root</parameter> <literal>http://localhost/xcap-root</literal> will be
79
-the URI for the authorization document
80
-<filename>http://localhost/xcap-root/pres-rules/users/smith/presence-rules.xml</filename>
81
-</para>
82
-</example>
83
-
84
-</section>
85
-
86
-<section><title>Disadvantages</title>
87
-<para>One of the worst disadvantages of XCAP authorization is slowness of XCAP
88
-queries compared to - for example - data stored in local database. This is the
89
-reason for caching XCAP queries and responses, but there is a problem - how to
90
-detect changes in data stored on XCAP server. One of possible solutions is to 
91
-implement client for <quote>XCAP change notifications</quote> described in <xref
92
-linkend="pres_draft_xcap_change"/> and <xref linkend="pres_draft_xcap_profiles"/>
93
-(planned in future versions).</para>
94
-</section>
95
-
96
-<section><title>Standard incompliances</title>
97
-<para>SER's XCAP authorization support is not finished yet, there are some standard
98
-incompliances now:
99
-<itemizedlist>
100
-	<listitem><para>ignored sphere</para></listitem>
101
-	<listitem><para>ignored date and time conditions</para></listitem>
102
-	<listitem><para>ignored transformations</para></listitem>
103
-</itemizedlist>
104
-</para>
105
-</section>
106
-
107
-</section> <!-- XCAP authorization in SER -->
108
-
109
-<section><title>Resource lists and SER</title>
110
-<para>There is a problem of resource lists usage: The draft <xref
111
-linkend="pres_draft_rls"/> describes that a Resource Lists Server operates with
112
-<quote>rls-services</quote> document - NOT directly with the user's buddy list,
113
-but tested client software doesn't store <quote>rls-services</quote> documents,
114
-only <quote>resource list documents</quote> (buddy lists).</para>
115
-
116
-<para>It is possible now to change mode of processing subscriptions (see <link
117
-linkend="rls.parameters">RLS module parameters</link> so it works directly with
118
-resource list documents published by client instead of rls-services document.
119
-</para>
120
-
121
-<section><title>RLS document URI</title>
122
-<para>The construction of rls-services document URI is described in <xref
123
-linkend="pres_draft_rls"/>. Only in short: the AOR from SIP SUBSCRIBE request is
124
-combined with XCAP root given in configuration like this:</para>
125
-<para>
126
-<filename>&lt;xcap-root&gt;/rls-services/global/index/~~/rls-services/service[@uri=%22&lt;AOR&gt;%22]</filename>.
127
-</para>
128
-<para><emphasis>
129
-This URI doesn't not specify namespaces as mentioned in definition, but this is 
130
-due to problems with XCAP server used for tests (problems querying
131
-parts of documents with namespaces).</emphasis></para>
132
-<example><title>rls-services uri example</title>
133
-<itemizedlist>
134
-	<listitem><para><varname>xcap-root</varname> = <literal>http://localhost/xcap-root</literal></para></listitem>
135
-	<listitem><para><varname>AOR</varname> = <literal>sip:smith-list@iptel.org</literal></para></listitem>
136
-</itemizedlist>
137
-<para>Resulting rls-services document describing the list will be get from URI: 
138
-<filename>http://localhost/xcap-root/rls-services/global/index/~~/rls-services/service[@uri=%22&lt;smith-list@iptel.org&gt;%22]</filename>,
139
-which means the <literal>service</literal> element with
140
-<parameter>uri</parameter> parameter value
141
-<literal>smith-list@iptel.org</literal> stored in rls-services document named
142
-index.
143
-</para></example>
144
-
145
-<section><title>Disadvantages</title>
146
-<para>Working with URIs presented in this section have one big disadvantage - it
147
-needs full XCAP server which is able to work with partial documents and able to
148
-process XPointer expressions in XCAP queries.</para>
149
-
150
-<para>Due to unavailability of free XCAP servers is there a possibility to
151
-use SER's RLS server in mode of <emphasis>reduced XCAP server needs</emphasis> 
152
-(see <link linkend="rls.parameters">RLS module parameters</link>). If operating 
153
-in this mode, RLS requests full rls-service document from uri 
154
-<filename>&lt;xcap-root&gt;/rls-services/global/index</filename>, inspects it
155
-and finds requested resource list according to URI and AOR by itself.
156
-(Only if possible! There can't be links 
157
-to partial documents in rls-services document.)
158
-</para>
159
-</section> <!-- disadvantages -->
160
-
161
-</section>
162
-
163
-<section><title>Standard incompliances</title>
164
-<para>SER's resource lists support is not finished yet, there are some standard
165
-incompliances now:
166
-<itemizedlist>
167
-	<listitem><para>uri canonicalization not done yet according to definition</para></listitem>
168
-	<listitem><para>no subscriptions made to external servers (subscriptions
169
-	only within one SER instance)</para></listitem>
170
-	<listitem><para>full status documents only</para></listitem>
171
-</itemizedlist>
172
-</para>
173
-</section>
174
-
175
-</section> <!-- resource lists and SER -->
176
-
177 66
 <section id="xcap.examples"><title>XCAP examples</title>
178 67
 <note><para>XCAP documents examples published there doesn't use correct XML
179 68
 namespaces due to problems with XCAP server used for tests (probles querying
Browse code

added short list of disadvantages of XCAP simulation into presence handbook

Vaclav Kubart authored on 03/02/2006 08:45:48
Showing 1 changed files
... ...
@@ -370,6 +370,21 @@ servers available today, thus the simulation may be interesting for - at least -
370 370
 demonstration or testing purposes.
371 371
 </para>
372 372
 
373
+<para>There are some disadvantages when the XCAP server is only simulated:
374
+<itemizedlist>
375
+	<listitem><para>no XML document validation</para></listitem>
376
+	<listitem><para>unable to work with XPointer terms (mainly unable to work 
377
+	with parts of documents)</para></listitem>
378
+	<listitem><para>possible synchronization problems (!)</para>
379
+		<para>More clients used by one user working with the same document
380
+		 (authorization document, buddy list) may rewrite it to each other.
381
+		 When using regular XCAP server this will be done in one atomic query.
382
+		 In the case of simulation it is needed to download whole document,
383
+		 modify it and put it back.</para>
384
+	 </listitem>
385
+</itemizedlist>
386
+</para>
387
+
373 388
 <para>Depending on your needs you can
374 389
 <itemizedlist>
375 390
 	<listitem><para>create hierarchical directory structure of XML documents according to
Browse code

- presence partialy modified for uuid-zed usrloc callback - modified documentation about XCAP server simulation - added RLS module parameter for better work with XCAP simulation

Vaclav Kubart authored on 22/11/2005 13:18:25
Showing 1 changed files
... ...
@@ -94,7 +94,7 @@ linkend="pres_draft_xcap_change"/> and <xref linkend="pres_draft_xcap_profiles"/
94 94
 </section>
95 95
 
96 96
 <section><title>Standard incompliances</title>
97
-<para>SER's resource lists support is not finished yet, there are some standard
97
+<para>SER's XCAP authorization support is not finished yet, there are some standard
98 98
 incompliances now:
99 99
 <itemizedlist>
100 100
 	<listitem><para>ignored sphere</para></listitem>
... ...
@@ -113,10 +113,10 @@ linkend="pres_draft_rls"/> describes that a Resource Lists Server operates with
113 113
 but tested client software doesn't store <quote>rls-services</quote> documents,
114 114
 only <quote>resource list documents</quote> (buddy lists).</para>
115 115
 
116
-<para>This problem is not solved yet, but it is possible, that the RLS module 
117
-will try both variants in the future. Now it scans and process only
118
-<quote>rls-services</quote> documents (there must be stored links onto user's
119
-buddy lists - as shown in <link linkend="xcap.examples">examples</link>).</para>
116
+<para>It is possible now to change mode of processing subscriptions (see <link
117
+linkend="rls.parameters">RLS module parameters</link> so it works directly with
118
+resource list documents published by client instead of rls-services document.
119
+</para>
120 120
 
121 121
 <section><title>RLS document URI</title>
122 122
 <para>The construction of rls-services document URI is described in <xref
... ...
@@ -141,6 +141,23 @@ which means the <literal>service</literal> element with
141 141
 <literal>smith-list@iptel.org</literal> stored in rls-services document named
142 142
 index.
143 143
 </para></example>
144
+
145
+<section><title>Disadvantages</title>
146
+<para>Working with URIs presented in this section have one big disadvantage - it
147
+needs full XCAP server which is able to work with partial documents and able to
148
+process XPointer expressions in XCAP queries.</para>
149
+
150
+<para>Due to unavailability of free XCAP servers is there a possibility to
151
+use SER's RLS server in mode of <emphasis>reduced XCAP server needs</emphasis> 
152
+(see <link linkend="rls.parameters">RLS module parameters</link>). If operating 
153
+in this mode, RLS requests full rls-service document from uri 
154
+<filename>&lt;xcap-root&gt;/rls-services/global/index</filename>, inspects it
155
+and finds requested resource list according to URI and AOR by itself.
156
+(Only if possible! There can't be links 
157
+to partial documents in rls-services document.)
158
+</para>
159
+</section> <!-- disadvantages -->
160
+
144 161
 </section>
145 162
 
146 163
 <section><title>Standard incompliances</title>
... ...
@@ -438,9 +455,10 @@ demonstration or testing purposes.
438 455
 these are read as standalone documents from directories of standalone users.
439 456
 </para>
440 457
 
441
-<para>For resource lists you have to install a full XCAP server. Only if you use
442
-<quote>simple</quote> mode of list subscription processing (see <link
443
-linkend="rls.parameters">RLS module parameters</link>) you do not need it.
458
+<para>For resource lists you have to set <link linkend="rls.parameters">RLS module 
459
+parameters</link> <varname>mode</varname> and/or
460
+<varname>reduce_xcap_needs</varname> 
461
+to work as much as possible with XCAP server simulation.
444 462
 </para>
445 463
 </section>
446 464
 
... ...
@@ -464,6 +482,9 @@ Alias /xcap-root /var/simulated-xcap-root
464 482
 </Directory>
465 483
 ...
466 484
 ]]></programlisting>
485
+<para>If apache is running on machine with SER, you can use as xcap-root
486
+<literal>http://localhost/xcap-root</literal>.
487
+</para>
467 488
 </example>
468 489
 
469 490
 <example><title>Simple (and dangerous) cgi-script for upload</title>
Browse code

RLS modified to be usable not only with XCAP server, but with standard web server too, with short description in presence handbook about how to simulate XCAP server with web server

Vaclav Kubart authored on 21/11/2005 15:54:37
Showing 1 changed files
... ...
@@ -202,7 +202,7 @@ conn.close()
202 202
 # store resource-list document for user
203 203
 #
204 204
 
205
-uri = "/xcap-root/resource-lists/users/smith"
205
+uri = "/xcap-root/resource-lists/users/smith/resource-list.xml"
206 206
 headers = {"Content-Type": "application/resource-lists+xml"}
207 207
 bf = file("list.xml", "r")
208 208
 body = bf.read(65536);
... ...
@@ -263,17 +263,17 @@ conn.close()
263 263
 This document can contain references to users buddy lists like
264 264
 <quote>smith-list@iptel.org</quote> which points to buddy list for user smith
265 265
 named <quote>default</quote> and can contain such lists directly.
266
-<caution><para>EyeBeam stores user's <quote>buddy list</quote> in 
266
+<!--<caution><para>EyeBeam stores user's <quote>buddy list</quote> in 
267 267
 <filename>&lt;XCAP-root&gt;/users/&lt;username&gt;/resource-list.xml</filename>, 
268 268
 not in
269 269
 <filename>&lt;XCAP-root&gt;/users/&lt;username&gt;</filename> which was used in 
270
-these examples.</para></caution>
270
+these examples.</para></caution>-->
271 271
 </para>
272 272
 <programlisting>
273 273
 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
274 274
 &lt;rls-services&gt;
275 275
 	&lt;service uri="sip:smith-list@iptel.org"&gt;
276
-		&lt;resource-list&gt;http://localhost/xcap-root/resource-lists/users/smith/~~/resource-lists/list[@name=%22default%22]&lt;/resource-list&gt;
276
+		&lt;resource-list&gt;http://localhost/xcap-root/resource-lists/users/smith/resource-list.xml/~~/resource-lists/list[@name=%22default%22]&lt;/resource-list&gt;
277 277
 		&lt;packages&gt;
278 278
 			&lt;package&gt;presence&lt;/package&gt;
279 279
 		&lt;/packages&gt;
... ...
@@ -345,6 +345,189 @@ exist extensions for particular types of configuration - for purpose of this
345 345
 document only configuration from presence area will be mentioned.
346 346
 </para>-->
347 347
 
348
+<section><title>XCAP server simulation</title>
349