kamailio/modules/xcap_client

XCAP_Client Module

Anca-Maria Vamanu

Voice Sistem SRL

Edited by

Anca-Maria Vamanu

Copyright © 2007 Voice Sistem SRL
__________________________________________________________________

Table of Contents

1. Admin Guide

1. Overview
2. Dependencies

2.1. Kamailio Modules
2.2. External Libraries or Applications

3. Parameters

3.1. db_url(str)
3.2. xcap_table(str)
3.3. periodical_query(int)
3.4. query_period(int)

4. Functions
5. Exported Management Functions

5.1. refreshXcapDoc

2. Developer Guide

1. bind_xcap_api(xcap_api_t* api)
2. get_elem
3. register_xcb

List of Examples

1.1. Set db_url parameter
1.2. Set xcap_table parameter
1.3. Set periodical_query parameter
1.4. Set query_period parameter
2.1. xcap_api structure

Chapter 1. Admin Guide

Table of Contents

1. Overview
2. Dependencies

2.1. Kamailio Modules
2.2. External Libraries or Applications

3. Parameters

3.1. db_url(str)
3.2. xcap_table(str)
3.3. periodical_query(int)
3.4. query_period(int)

4. Functions
5. Exported Management Functions

5.1. refreshXcapDoc

1. Overview

The modules is a XCAP client for Kamailio that can be used by other
modules. It fetches XCAP elements, either documents or part of them, by
sending HTTP GET requests to an XCAP server. It also offers support for
conditional queries. It uses the libcurl library as a client-side HTTP
transfer library.

The module offers a XCAP client interface with general functions that
allow requesting for a specific element from a XCAP server. In addition
to that it also offers the service of storing and updating the
documents it receives. In this case only an initial request to the
module is required - xcapGetNewDoc - which is like a request to the
module to handle from that point on the referenced document so as to
promise that the newest version will always be present in database.

The update method is also configurable, either through periodical
queries, applicable to any kind of XCAP server or with an management
command that should be sent by the server upon an update.

The module is currently used by the “presence_xml” module, if the
'integrated_xcap_server' parameter is not set.

2. Dependencies

2.1. Kamailio Modules
2.2. External Libraries or Applications

2.1. Kamailio Modules

The modules is not dependent of any Kamailio module.

2.2. External Libraries or Applications

The following libraries or applications must be installed before
running Kamailio with this module loaded:
* libxml.
* libcurl.

3. Parameters

3.1. db_url(str)
3.2. xcap_table(str)
3.3. periodical_query(int)
3.4. query_period(int)

3.1. db_url(str)

The database url.

Default value is “mysql://openser:openserrw@localhost/openser”.

Example 1.1. Set db_url parameter
...
modparam("xcap_client", "db_url", "dbdriver://username:password@dbhost/dbname")
...

3.2. xcap_table(str)

The name of the db table where XCAP documents are stored.

Default value is “xcap”.

Example 1.2. Set xcap_table parameter
...
modparam("xcap_client", "xcap_table", "xcaps")
...

3.3. periodical_query(int)

A flag to disable periodical query as an update method for the
documents the module is responsible for. It could be disabled when the
XCAP server is capable to send the exported management command when a
change occurs or when another module in Kamailio handles updates.

To disable it set this parameter to 0.

Default value is “1”.

Example 1.3. Set periodical_query parameter
...
modparam("xcap_client", "periodical_query", 0)
...

3.4. query_period(int)

Should be set if periodical query is not disabled. Represents the time
interval the XCAP servers should be queried for an update.

To disable it set this parameter to 0.

Default value is “100”.

Example 1.4. Set query_period parameter
...
modparam("xcap_client", "query_period", 50)
...

4. Functions

None to be used in configuration file.

5. Exported Management Functions

5.1. refreshXcapDoc

5.1. refreshXcapDoc

Management command that should be sent by an XCAP server when a stored
document changes.

Name: refreshXcapDoc

Parameters:
* document uri: the uri of the document
* xcap server port: the port of the xcap server

Management FIFO Command Format:
...
:refreshXcapDoc:fifo_reply
/xcap-root/resource-lists/users/eyebeam/buddies-resource-list.xml
8000
_empty_line_
...

Chapter 2. Developer Guide

Table of Contents

1. bind_xcap_api(xcap_api_t* api)
2. get_elem
3. register_xcb

The module exports a number of functions that allow selecting and
retrieving an element from an xcap server and also registering a
callback to be called when the management command refreshXcapDoc is
received and the document in question is retrieved.

1. bind_xcap_api(xcap_api_t* api)

This function allows binding the needed functions.

Example 2.1. xcap_api structure
...
typedef struct xcap_api {

/* xcap node selection and retrieving functions*/
xcap_get_elem_t get_elem;
xcap_nodeSel_init_t int_node_sel;
xcap_nodeSel_add_step_t add_step;
xcap_nodeSel_add_terminal_t add_terminal;
xcap_nodeSel_free_t free_node_sel;
xcapGetNewDoc_t getNewDoc; /* an initial request for the module
fo fetch this document that does not exist in xcap db table
and handle its update*/

/* function to register a callback to document changes*/
register_xcapcb_t register_xcb;
}xcap_api_t;
...

2. get_elem

Field type:
...
typedef char* (*xcap_get_elem_t)(char* xcap_root,
xcap_doc_sel_t* doc_sel, xcap_node_sel_t* node_sel);
...

This function sends a HTTP request and gets the specified information
from the xcap server.

The parameters signification:
* xcap_root- the XCAP server address;
* doc_sel- structure with document selection info;
Parameter type:
...
typedef struct xcap_doc_sel
{
str auid; /* application defined Unique ID*/
int type; /* the type of the path segment
after the AUID which must either
be GLOBAL_TYPE (for "global") or
USERS_TYPE (for "users") */
str xid; /* the XCAP User Identifier
if type is USERS_TYPE */
str filename;
}xcap_doc_sel_t;
...
* node_sel- structure with node selection info;
Parameter type:
...
typedef struct xcap_node_sel
{
step_t* steps;
step_t* last_step;
int size;
ns_list_t* ns_list;
ns_list_t* last_ns;
int ns_no;

}xcap_node_sel_t;

typedef struct step
{
str val;
struct step* next;
}step_t;

typedef struct ns_list
{
int name;
str value;
struct ns_list* next;
}ns_list_t;
...
The node selector is represented like a list of steps that will be
represented in the path string separated by '/' signs. The
namespaces for the nodes are stored also in a list, as an
association of name and value, where the value is to be included in
the respective string val field of the step.
To construct the node structure the following functions in the
xcap_api structure should be used: 'int_node_sel', 'add_step' and
if needed, 'add_terminal'.
If the intention is to retrieve the whole document this argument
must be NULL.

3. register_xcb

Field type:
...
typedef int (*register_xcapcb_t)(int types, xcap_cb f);
...

- 'types' parameter can have a combined value of PRES_RULES,
RESOURCE_LIST, RLS_SERVICES and PIDF_MANIPULATION.

-the callback function has type :
...
typedef int (xcap_cb)(int doc_type, str xid, char* doc);
...