XCAP_Client Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. periodical_query(int)
              1.3.2. query_period(int)

        1.4. Exported Functions
        1.5. Exported MI Functions

              1.5.1. refreshXcapDoc

   2. Developer Guide

        2.1. bind_xcap_client_api(xcap_client_api_t* api)
        2.2. get_elem
        2.3. register_xcb

   3. Contributors

        3.1. By Commit Statistics
        3.2. By Commit Activity

   4. Documentation

        4.1. Contributors

   List of Tables

   3.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   3.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set periodical_query parameter
   1.2. Set query_period parameter
   2.1. xcap_client_api structure

Chapter 1. Admin Guide

1.1. Overview

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

   The module offers an xcap client interface with general
   functions that allow requesting for an specific element from an
   xcap server. In addition to that it also offers the service of
   storing and update in database 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 MI 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.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * xcap.

1.2.2. External Libraries or Applications

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

1.3. Exported Parameters

1.3.1. 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 MI command
   when a change occurs or when another module in OpenSIPS handles
   updates.

   To disable it set this parameter to 0.

   Default value is “1”.

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

1.3.2. 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.2. Set query_period parameter
...
modparam("xcap_client", "query_period", 50)
...

1.4. Exported Functions

   None to be used in configuration file.

1.5. Exported MI Functions

1.5.1.  refreshXcapDoc

   MI command that should be sent by an xcap server when a stored
   document changes.

   Name: refreshXcapDoc

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

   MI FIFO Command Format:
...
opensips-cli -x mi refreshXcapDoc /xcap-root/resource-lists/users/eyebea
m/buddies-resource-list.xml 8000
...

Chapter 2. Developer Guide

   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 a MI command
   refreshXcapDoc is received and the document in question is
   retrieved.

2.1.  bind_xcap_client_api(xcap_client_api_t* api)

   This function allows binding the needed functions.

   Example 2.1. xcap_client_api structure
...
typedef struct xcap_client_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_client_api_t;
...

2.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.

2.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_LISTS, RLS_SERVICES, OMA_PRES_RULES and
   PIDF_MANIPULATION.

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

Chapter 3. Contributors

3.1. By Commit Statistics

   Table 3.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Anca Vamanu 37 14 2155 193
   2. Bogdan-Andrei Iancu (@bogdan-iancu) 18 15 56 63
   3. Liviu Chircu (@liviuchircu) 12 10 30 50
   4. Razvan Crainea (@razvancrainea) 12 10 18 18
   5. Daniel-Constantin Mierla (@miconda) 9 7 22 19
   6. Henning Westerholt (@henningw) 8 6 60 49
   7. Saúl Ibarra Corretgé (@saghul) 6 3 55 89
   8. Vlad Patrascu (@rvlad-patrascu) 5 3 20 33
   9. Dan Pascu (@danpascu) 4 2 8 9
   10. Peter Lemenkov (@lemenkov) 4 2 4 4

   All remaining contributors: Romanov Vladimir, Ovidiu Sas
   (@ovidiusas), Vlad Paiu (@vladpaiu), Maksym Sobolyev
   (@sobomax), Konstantin Bokarius, UnixDev, Edson Gellert
   Schubert.

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

3.2. By Commit Activity

   Table 3.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Peter Lemenkov (@lemenkov)          Jun 2018 - Oct 2025
   2.  Liviu Chircu (@liviuchircu)         Mar 2014 - May 2024
   3.  Maksym Sobolyev (@sobomax)          Feb 2023 - Feb 2023
   4.  Razvan Crainea (@razvancrainea)     Sep 2011 - Sep 2019
   5.  Bogdan-Andrei Iancu (@bogdan-iancu) Feb 2008 - Apr 2019
   6.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Dec 2018
   7.  Vlad Paiu (@vladpaiu)               Mar 2014 - Mar 2014
   8.  Ovidiu Sas (@ovidiusas)             Jan 2013 - Jan 2013
   9.  Saúl Ibarra Corretgé (@saghul)      Nov 2012 - Jan 2013
   10. Anca Vamanu                         Aug 2007 - Feb 2010

   All remaining contributors: Romanov Vladimir, UnixDev, Henning
   Westerholt (@henningw), Dan Pascu (@danpascu),
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert.

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 4. Documentation

4.1. Contributors

   Last edited by: Razvan Crainea (@razvancrainea), Vlad Patrascu
   (@rvlad-patrascu), Peter Lemenkov (@lemenkov), Liviu Chircu
   (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Saúl
   Ibarra Corretgé (@saghul), Anca Vamanu, Henning Westerholt
   (@henningw), Daniel-Constantin Mierla (@miconda), Konstantin
   Bokarius, Edson Gellert Schubert.

   Documentation Copyrights:

   Copyright © 2007 Voice Sistem SRL
