XCAP介绍

 

XCAP is a HTTP based protocol for access remote configuration data. Data is stored in XML format and XCAP protocol allows to query, modify or delete parts of such data. This is in detail described in [ xcap ]. XCAP server is server able to handle XCAP requests.

XCAP server may be used for storing “presence interesting ” data. From the SER's point of view are interesting:

• authorization data

• “buddy lists ”

 

2.1.1.�XCAP authorization

Definition of authorization documents and theirs usage is specified in [common auth ] and especially for presence purposes in [presence auth ]. Both documents are quite common and in SER's presence modules implemented only partialy. For more information about XCAP authorization see details in Section�4.3, “XCAP authorization” .

2.1.2.�Buddy lists

XCAP server may be used for storing lists of users too. These lists may be used for presence subscriptions - subscription to such list means subscription to all users on it at once. This reduces number of created subscriptions and may reduce data transfers between server and client too; but presence documents for lists of users may be very big and thus require TCP connection.

There may be not only lists for individual users with their contacts but there may be other sort of lists representing some “logical entities ” such “businessmen ”, “technical support ”, ... which are used in cases like if some customer needs someone from technical support department and doesn't want to remeber all people there. Such customer may simply watch presence state of “technical-support@somewhere.net ” if he needs help from them.

Lists of users - more common resource lists - are defined in [rls ] and their usage with SIP in [sip rls ]. These lists are partialy implemented in RLS module . For more information about resource lists see details in Section�5.2, “RLS and XCAP” .

2.1.3.�Manipulation with XCAP documents

Manipulating with XCAP documents is quite simple because XCAP uses standard HTTP methods like GET, PUT or DELETE. Every web browser may be used to read XCAP data and it is quite simple to write utility to write data to XCAP server. These features allow to use XCAP with SER although there are is not much client software supporting it.

2.2.�XCAP examples

Note

XCAP documents examples published there doesn't use correct XML namespaces due to problems with XCAP server used for tests (probles querying partial documents with namespaces).

Example�1.�Storing XCAP documents

There is a sample script in Python which stores XCAP documents onto a XCAP server. Documents are:

• rls-services document stored under name index

• buddy list for user Smith stored under name smith

• presence authorization document for user Smith stored under name presence-rules.xml

 

#!/usr/bin/python

import httplib, urllib



machine = "localhost"



#

# store rls-services document

#



uri = "/xcap-root/rls-services/global/index"

headers = {"Content-Type": "application/rls-services+xml"}

bf = file("rls.xml", "r")

body = bf.read(65536);

conn = httplib.HTTPConnection(machine)

conn.request("PUT", uri, body, headers)



response = conn.getresponse()

print "Storing rls-services document: ", response.status, response.reason

data = response.read()

conn.close()



#

# store resource-list document for user

#



uri = "/xcap-root/resource-lists/users/smith/resource-list.xml"

headers = {"Content-Type": "application/resource-lists+xml"}

bf = file("list.xml", "r")

body = bf.read(65536);

conn = httplib.HTTPConnection(machine)

conn.request("PUT", uri, body, headers)



response = conn.getresponse()

print "Storing resource-lists document: ", response.status, response.reason

data = response.read()

conn.close()



#

# store presence authorization rules

#



uri = "/xcap-root/pres-rules/users/smith/presence-rules.xml"

headers = {"Content-Type": "application/pres-rules+xml"}

bf = file("presence-rules.xml", "r")

body = bf.read(65536);

conn = httplib.HTTPConnection(machine)

conn.request("PUT", uri, body, headers)



response = conn.getresponse()

print "Storing pres-rules document: ", response.status, response.reason

data = response.read()

conn.close()

Example�2.�Example resource list document (list.xml)

Simple buddy lists which shows the possibility of nested lists.

<?xml version="1.0" ?>

<resource-lists>

	<list name="default">

		<list name="work">

			<entry uri="sip:someone@iptel.org">

				<display-name>Someone</display-name>

			</entry>

			<entry uri="sip:smith@iptel.org">

				<display-name>Jonathan Smith</display-name>

			</entry>

		</list>

		<entry uri="sip:vasek@iptel.org">

			<display-name>Vasek</display-name>

		</entry>

		<entry uri="sip:vaclav.kubart@iptel.org">

			<display-name>Vaclav Kubart</display-name>

		</entry>

	</list>

</resource-lists>

Example�3.�Example rls-services document (rls.xml)

Example document which is processed by Resource List Server (RLS module). This document can contain references to users buddy lists like “smith-list@iptel.org ” which points to buddy list for user smith named “default ” and can contain such lists directly.

<?xml version="1.0" encoding="UTF-8"?>

<rls-services>

	<service uri="sip:smith-list@iptel.org">

		<resource-list>http://localhost/xcap-root/resource-lists/users/smith/resource-list.xml/~~/resource-lists/list[@name=%22default%22]</resource-list>

		<packages>

			<package>presence</package>

		</packages>

	</service>

	<service uri="sip:cz@iptel.org">

		<list name="czech iptel">

			<entry uri="sip:abc@iptel.org">

				<display-name>A B</display-name>

			</entry>

			<entry uri="sip:cde@iptel.org">

				<display-name>C D</display-name>

			</entry>

			<entry uri="sip:efg@iptel.org">

				<display-name>Ef Ge</display-name>

			</entry>

		</list>

		<packages>

			<package>presence</package>

			<package>email</package>

		</packages>

	</service>

</rls-services>

Example�4.�Example presence authorization document (presence-rules.xml)

This document contains two rules:

• “white list ”, which allows access to presence information from all from domain iptel.org

• “black list ”, which denies access for user nemo@somewhere.net

<?xml version="1.0" ?>

<ruleset xmlns="urn:ietf:params:xml:ns:common-policy" xmlns:pr="urn:ietf:params:xml:ns:pres-rules">

	<rule id="blacklist">

		<conditions>

			<identity>

				<id>sip:nemo@somewhere.net</id>

			</identity>

		</conditions>

		<actions>

			<pr:sub-handling>block</pr:sub-handling>

		</actions>

		<transformations/>

	</rule>

	

	<rule id="whitelist">

		<conditions>

			<identity>

				<domain domain="iptel.org"/>

			</identity>

		</conditions>

		<actions>

			<pr:sub-handling>allow</pr:sub-handling>

		</actions>

		<transformations/>

	</rule>

</ruleset>

2.3.�XCAP server simulation

XCAP server is a HTTP server with some features like document validation or ability of working with parts of stored documents. If you have no XCAP server, you can simulate it using standard web server. There are not many XCAP servers available today, thus the simulation may be interesting for - at least - demonstration or testing purposes.

There are some disadvantages when the XCAP server is only simulated:

• no XML document validation

• unable to work with XPointer terms (mainly unable to work with parts of documents)

• possible synchronization problems (!)

  More clients used by one user working with the same document (authorization document, buddy list) may rewrite it to each other. When using regular XCAP server this will be done in one atomic query. In the case of simulation it is needed to download whole document, modify it and put it back.

 

Depending on your needs you can

• create hierarchical directory structure of XML documents according to [xcap ]

• allow upload (handle HTTP PUT method) which stores documents into the directory structure

• improve upload to validate documents according to schema (every sort of XCAP document should have their XSD published)

• allow document removing (handle DELETE method)

• process HTTP GET requests with a CGI-script so it processes queries for partial documents

 

2.3.1.�Directory structure

Presence modules use XCAP documents stored in structure like this:

xcap-root

• pres-rules

  • users

    • smith

      • presence-rules.xml (file containg presence authorization rules for user smith)

    • joe

      • presence-rules.xml (file containing presence authorization rules for user joe)

    • ... (directories for other users)

• resource-lists

  • users

    • smith

      • resource-list.xml (file containing resources lists for user smith)

    • joe

      • resource-list.xml (file containing resource lists for user joe)

    • ... (directories for other users)

• rls-services

  • global

    • index (file containing global rls-services documents)

 

2.3.2.�Usage with SER

You don't need a full XCAP server for presence authorization documents - these are read as standalone documents from directories of standalone users.

For resource lists you have to set RLS module parameters mode and/or reduce_xcap_needs to work as much as possible with XCAP server simulation.

2.3.3.�XCAP simulation examples

Examples presented here can be used as simple XCAP server simulation. It is able to handle PUT method (for whole XML documents).

Example�5.�Apache2 configuration

...

Alias /xcap-root /var/simulated-xcap-root

<Directory /var/simulated-xcap-root>

	Options Indexes FollowSymLinks MultiViews

	Script PUT /cgi-bin/upload

	<Limit PUT DELETE GET>

		Order Allow,Deny

		Deny from none

		Allow from all

	</Limit>

</Directory>

...

If apache is running on machine with SER, you can use as xcap-root http://localhost/xcap-root .

Example�6.�Simple (and dangerous) cgi-script for upload

This code is written in C and it is able to create directories if needed, but its usage in presented form is realy unsafe! You have to compile it and put into directory with other CGI scripts.

#include <stdio.h>

#include <stdlib.h>

#include <string.h>



#include <sys/stat.h>

#include <sys/types.h>



void copy_file(const char *filename)

{

	char buf[2048];

	int r;

	FILE *f;

	

	f = fopen(filename, "wb");

	if (f) {

		while (!feof(stdin)) {

			r = fread(buf, 1, sizeof(buf), stdin);

			fwrite(buf, 1, r, f);

		}

		fclose(f);

	}

}



int main(int argc, char **argv)

{

	char *filename, *x;

	char tmp[1024];

	int res = 0;

	

	filename = getenv ("PATH_TRANSLATED");



	strcpy(tmp, filename);

	x = strrchr(tmp, '/');

	if (x) {

		*x = 0;

		res = mkdir(tmp, 0755);		/* ! dangerous ! */

	}

	else {

		printf("Status: 500/n");

		printf("Content-Type: text/html/n/n");

		printf("<html><head/>/n<body>Incorrect filename</body></html>/n");	

		return -1;

	}

	

	copy_file(filename); /* ! dangerous ! */

		

	printf("Status: 200/n");

	printf("Content-Type: text/html/n/n");

	printf("<html><head><title>Upload</title>/n</head>/n<body>Finished...</body></html>/n");

	

	return 0;

}