"Fossies" - the Fresh Open Source Software Archive

Member "opensips-3.0.1/modules/xcap_client/README" (1 Oct 2019, 10198 Bytes) of package /linux/misc/opensips-3.0.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 3.0.0_vs_3.0.1.

    1 XCAP_Client Module
    2      __________________________________________________________
    3 
    4    Table of Contents
    5 
    6    1. Admin Guide
    7 
    8         1.1. Overview
    9         1.2. Dependencies
   10 
   11               1.2.1. OpenSIPS Modules
   12               1.2.2. External Libraries or Applications
   13 
   14         1.3. Exported Parameters
   15 
   16               1.3.1. periodical_query(int)
   17               1.3.2. query_period(int)
   18 
   19         1.4. Exported Functions
   20         1.5. Exported MI Functions
   21 
   22               1.5.1. refreshXcapDoc
   23 
   24    2. Developer Guide
   25 
   26         2.1. bind_xcap_client_api(xcap_client_api_t* api)
   27         2.2. get_elem
   28         2.3. register_xcb
   29 
   30    3. Contributors
   31 
   32         3.1. By Commit Statistics
   33         3.2. By Commit Activity
   34 
   35    4. Documentation
   36 
   37         4.1. Contributors
   38 
   39    List of Tables
   40 
   41    3.1. Top contributors by DevScore^(1), authored commits^(2) and
   42           lines added/removed^(3)
   43 
   44    3.2. Most recently active contributors^(1) to this module
   45 
   46    List of Examples
   47 
   48    1.1. Set periodical_query parameter
   49    1.2. Set query_period parameter
   50    2.1. xcap_client_api structure
   51 
   52 Chapter 1. Admin Guide
   53 
   54 1.1. Overview
   55 
   56    The modules is an XCAP client for OpenSIPS that can be used by
   57    other modules. It fetches XCAP elements, either documents or
   58    part of them, by sending HTTP GET requests. It also offers
   59    support for conditional queries. It uses libcurl library as a
   60    client-side HTTP transfer library.
   61 
   62    The module offers an xcap client interface with general
   63    functions that allow requesting for an specific element from an
   64    xcap server. In addition to that it also offers the service of
   65    storing and update in database the documents it receives. In
   66    this case only an initial request to the module is required -
   67    xcapGetNewDoc-which is like a request to the module to handle
   68    from that point on the referenced document so as to promise
   69    that the newest version will always be present in database.
   70 
   71    The update method is also configurable, either through
   72    periodical queries, applicable to any kind of xcap server or
   73    with an MI command that should be sent by the server upon an
   74    update.
   75 
   76    The module is currently used by the presence_xml module, if the
   77    'integrated_xcap_server' parameter is not set.
   78 
   79 1.2. Dependencies
   80 
   81 1.2.1. OpenSIPS Modules
   82 
   83    The following modules must be loaded before this module:
   84      * xcap.
   85 
   86 1.2.2. External Libraries or Applications
   87 
   88    The following libraries or applications must be installed
   89    before running OpenSIPS with this module loaded:
   90      * libxml-dev.
   91      * libcurl-dev.
   92 
   93 1.3. Exported Parameters
   94 
   95 1.3.1. periodical_query(int)
   96 
   97    A flag to disable periodical query as an update method for the
   98    documents the module is responsible for. It could be disabled
   99    when the xcap server is capable to send the exported MI command
  100    when a change occurs or when another module in OpenSIPS handles
  101    updates.
  102 
  103    To disable it set this parameter to 0.
  104 
  105    Default value is “1”.
  106 
  107    Example 1.1. Set periodical_query parameter
  108 ...
  109 modparam("xcap_client", "periodical_query", 0)
  110 ...
  111 
  112 1.3.2. query_period(int)
  113 
  114    Should be set if periodical query is not disabled. Represents
  115    the time interval the xcap servers should be queried for an
  116    update
  117 
  118    To disable it set this parameter to 0.
  119 
  120    Default value is “100”.
  121 
  122    Example 1.2. Set query_period parameter
  123 ...
  124 modparam("xcap_client", "query_period", 50)
  125 ...
  126 
  127 1.4. Exported Functions
  128 
  129    None to be used in configuration file.
  130 
  131 1.5. Exported MI Functions
  132 
  133 1.5.1.  refreshXcapDoc
  134 
  135    MI command that should be sent by an xcap server when a stored
  136    document changes.
  137 
  138    Name: refreshXcapDoc
  139 
  140    Parameters:
  141      * doc_uri: the uri of the document
  142      * port: the port of the xcap server
  143 
  144    MI FIFO Command Format:
  145 ...
  146 opensips-cli -x mi refreshXcapDoc /xcap-root/resource-lists/users/eyebea
  147 m/buddies-resource-list.xml 8000
  148 ...
  149 
  150 Chapter 2. Developer Guide
  151 
  152    The module exports a number of functions that allow selecting
  153    and retrieving an element from an xcap server and also
  154    registering a callback to be called when a MI command
  155    refreshXcapDoc is received and the document in question is
  156    retrieved.
  157 
  158 2.1.  bind_xcap_client_api(xcap_client_api_t* api)
  159 
  160    This function allows binding the needed functions.
  161 
  162    Example 2.1. xcap_client_api structure
  163 ...
  164 typedef struct xcap_client_api {
  165 
  166         /* xcap node selection and retrieving functions*/
  167         xcap_get_elem_t get_elem;
  168         xcap_nodeSel_init_t int_node_sel;
  169         xcap_nodeSel_add_step_t add_step;
  170         xcap_nodeSel_add_terminal_t add_terminal;
  171         xcap_nodeSel_free_t free_node_sel;
  172         xcapGetNewDoc_t getNewDoc; /* an initial request for the module
  173         fo fetch this document that does not exist in xcap db table
  174         and handle its update*/
  175 
  176         /* function to register a callback to document changes*/
  177         register_xcapcb_t register_xcb;
  178 }xcap_client_api_t;
  179 ...
  180 
  181 2.2.  get_elem
  182 
  183    Field type:
  184 ...
  185 typedef char* (*xcap_get_elem_t)(char* xcap_root,
  186 xcap_doc_sel_t* doc_sel, xcap_node_sel_t* node_sel);
  187 ...
  188 
  189    This function sends a HTTP request and gets the specified
  190    information from the xcap server.
  191 
  192    The parameters signification:
  193      * xcap_root- the XCAP server address;
  194      * doc_sel- structure with document selection info;
  195 Parameter type:
  196 ...
  197 typedef struct xcap_doc_sel
  198 {
  199         str auid; /* application defined Unique ID*/
  200         int type; /* the type of the path segment
  201                                 after the AUID  which must either
  202                                 be GLOBAL_TYPE (for "global") or
  203                                 USERS_TYPE (for "users") */
  204         str xid; /* the XCAP User Identifier
  205                                 if type is USERS_TYPE */
  206         str filename;
  207 }xcap_doc_sel_t;
  208 ...
  209 
  210      * node_sel- structure with node selection info;
  211 Parameter type:
  212 ...
  213 typedef struct xcap_node_sel
  214 {
  215         step_t* steps;
  216         step_t* last_step;
  217         int size;
  218         ns_list_t* ns_list;
  219         ns_list_t* last_ns;
  220         int ns_no;
  221 
  222 }xcap_node_sel_t;
  223 
  224 typedef struct step
  225 {
  226         str val;
  227         struct step* next;
  228 }step_t;
  229 
  230 typedef struct ns_list
  231 {
  232         int name;
  233         str value;
  234         struct ns_list* next;
  235 }ns_list_t;
  236 ...
  237 
  238 
  239        The node selector is represented like a list of steps that
  240        will be represented in the path string separated by '/'
  241        signs. The namespaces for the nodes are stored also in a
  242        list, as an association of name and value, where the value
  243        is to be included in the respective string val field of the
  244        step.
  245        To construct the node structure the following functions in
  246        the xcap_api structure should be used: 'int_node_sel',
  247        'add_step' and if needed, 'add_terminal'.
  248        If the intention is to retrieve the whole document this
  249        argument must be NULL.
  250 
  251 2.3.  register_xcb
  252 
  253    Field type:
  254 ...
  255 typedef int (*register_xcapcb_t)(int types, xcap_cb f);
  256 ...
  257 
  258    - 'types' parameter can have a combined value of PRES_RULES,
  259    RESOURCE_LISTS, RLS_SERVICES, OMA_PRES_RULES and
  260    PIDF_MANIPULATION.
  261 
  262    -the callback function has type :
  263 ...
  264 typedef int (xcap_cb)(int doc_type, str xid, char* doc);
  265 ...
  266 
  267 Chapter 3. Contributors
  268 
  269 3.1. By Commit Statistics
  270 
  271    Table 3.1. Top contributors by DevScore^(1), authored
  272    commits^(2) and lines added/removed^(3)
  273      Name DevScore Commits Lines ++ Lines --
  274    1. Anca Vamanu 35 14 2155 193
  275    2. Bogdan-Andrei Iancu (@bogdan-iancu) 18 15 56 63
  276    3. Razvan Crainea (@razvancrainea) 12 10 18 18
  277    4. Liviu Chircu (@liviuchircu) 11 9 30 48
  278    5. Daniel-Constantin Mierla (@miconda) 9 7 22 19
  279    6. Henning Westerholt (@henningw) 8 6 60 49
  280    7. Saúl Ibarra Corretgé (@saghul) 6 3 55 89
  281    8. Vlad Patrascu (@rvlad-patrascu) 5 3 20 33
  282    9. Dan Pascu (@danpascu) 4 2 8 9
  283    10. Romanov Vladimir 3 1 29 21
  284 
  285    All remaining contributors: Ovidiu Sas (@ovidiusas), Vlad Paiu
  286    (@vladpaiu), Konstantin Bokarius, Peter Lemenkov (@lemenkov),
  287    UnixDev, Edson Gellert Schubert.
  288 
  289    (1) DevScore = author_commits + author_lines_added /
  290    (project_lines_added / project_commits) + author_lines_deleted
  291    / (project_lines_deleted / project_commits)
  292 
  293    (2) including any documentation-related commits, excluding
  294    merge commits. Regarding imported patches/code, we do our best
  295    to count the work on behalf of the proper owner, as per the
  296    "fix_authors" and "mod_renames" arrays in
  297    opensips/doc/build-contrib.sh. If you identify any
  298    patches/commits which do not get properly attributed to you,
  299    please submit a pull request which extends "fix_authors" and/or
  300    "mod_renames".
  301 
  302    (3) ignoring whitespace edits, renamed files and auto-generated
  303    files
  304 
  305 3.2. By Commit Activity
  306 
  307    Table 3.2. Most recently active contributors^(1) to this module
  308                       Name                   Commit Activity
  309    1.  Razvan Crainea (@razvancrainea)     Sep 2011 - Sep 2019
  310    2.  Bogdan-Andrei Iancu (@bogdan-iancu) Feb 2008 - Apr 2019
  311    3.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Dec 2018
  312    4.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
  313    5.  Liviu Chircu (@liviuchircu)         Mar 2014 - Jun 2018
  314    6.  Vlad Paiu (@vladpaiu)               Mar 2014 - Mar 2014
  315    7.  Ovidiu Sas (@ovidiusas)             Jan 2013 - Jan 2013
  316    8.  Saúl Ibarra Corretgé (@saghul)      Nov 2012 - Jan 2013
  317    9.  Anca Vamanu                         Aug 2007 - Feb 2010
  318    10. Romanov Vladimir                    Mar 2009 - Mar 2009
  319 
  320    All remaining contributors: UnixDev, Henning Westerholt
  321    (@henningw), Dan Pascu (@danpascu), Daniel-Constantin Mierla
  322    (@miconda), Konstantin Bokarius, Edson Gellert Schubert.
  323 
  324    (1) including any documentation-related commits, excluding
  325    merge commits
  326 
  327 Chapter 4. Documentation
  328 
  329 4.1. Contributors
  330 
  331    Last edited by: Razvan Crainea (@razvancrainea), Vlad Patrascu
  332    (@rvlad-patrascu), Peter Lemenkov (@lemenkov), Liviu Chircu
  333    (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Saúl
  334    Ibarra Corretgé (@saghul), Anca Vamanu, Henning Westerholt
  335    (@henningw), Daniel-Constantin Mierla (@miconda), Konstantin
  336    Bokarius, Edson Gellert Schubert.
  337 
  338    Documentation Copyrights:
  339 
  340    Copyright © 2007 Voice Sistem SRL