mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
313 lines
7.9 KiB
313 lines
7.9 KiB
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);
|
|
...
|