modules/jsonrpc-c/README
044a6b91
 jsonrpc-c (client) Module
 
 Matthew Williams
 
    <matthew@flowroute.com>
 
 Edited by
 
 Jordan Levy
 
    <jordan@flowroute.com>
 
33570d9f
    Copyright � 2011 Flowroute LLC (flowroute.com)
044a6b91
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
         1. Overview
         2. Dependencies
 
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
2d129b55
         3. Parameters
044a6b91
 
               3.1. servers (string)
 
2d129b55
         4. Functions
044a6b91
 
               4.1. jsonrpc_notification(method, parameters)
               4.2. jsonrpc_request(method, parameters, return_route,
                       error_route, result_var)
 
    List of Examples
 
    1.1. Set servers parameter
    1.2. jsonrpc_notification usage
    1.3. jsonrpc_request usage
 
 Chapter 1. Admin Guide
 
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
2d129b55
    3. Parameters
044a6b91
 
         3.1. servers (string)
 
2d129b55
    4. Functions
044a6b91
 
         4.1. jsonrpc_notification(method, parameters)
         4.2. jsonrpc_request(method, parameters, return_route,
                 error_route, result_var)
 
 1. Overview
 
    This module provides access to json-rpc services (operating over
    TCP/Netstrings).
 
    This module uses t_suspend() and t_continue() from the TM module.
 
    Note that after invoking an asyncronous operation, the processing will
    continue later, in another application process. Therefore, do not rely
    on variables stored in private memory, use shared memory if you want to
    get values after the processing is resumend (e.g., $shv(...) or htable
    $sht(...)).
 
 2. Dependencies
 
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
 
    The following modules must be loaded before this module:
      * tm - transaction management.
 
 2.2. External Libraries or Applications
 
11f300f2
    Note: this module uses Linux specific API, part of glibc library, it
    might not compile on other types of operating systems.
 
044a6b91
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
2d129b55
      * libjson (https://github.com/json-c/json-c/wiki)
      * libevent - http://libevent.org/
11f300f2
      * glibc - http://www.gnu.org/software/libc/ (v2.8 or higher)
044a6b91
 
2d129b55
 3. Parameters
044a6b91
 
    3.1. servers (string)
 
 3.1. servers (string)
 
    The servers providing the remote jsonrpc service. Format is
    "host1:port1,priority1 host2:port2,priority2". Requests to servers of
    the same priority will be distributed evenly (round robin). Server
    groups with higher priority are used first.
 
    Example 1.1. Set servers parameter
 ...
 modparam("jsonrpc", "servers", "localhost:9999,2 10.10.0.1:9999,2 backup.server:
 9999,1")
 ...
 
2d129b55
 4. Functions
044a6b91
 
    4.1. jsonrpc_notification(method, parameters)
    4.2. jsonrpc_request(method, parameters, return_route, error_route,
           result_var)
 
33570d9f
 4.1. jsonrpc_notification(method, parameters)
044a6b91
 
    Invokes the remote 'method' with the given 'parameters' as a
    notification. Unlike jsonrpc_request (below), notifications do not
    receive a response. Script processing continues in the usual fashion as
    soon as the notification has been sent.
 
    The method and parameters can be a static string or dynamic string
    value with config variables.
 
    Example 1.2. jsonrpc_notification usage
 ...
 jsonrpc_notification("update_user", "{'id': 1234, 'name': 'Petros'}")
 ...
 
33570d9f
 4.2. jsonrpc_request(method, parameters, return_route, error_route,
044a6b91
 result_var)
 
    Invokes the remote 'method' with the given 'parameters'. When the
    response is received, continues processing of the SIP request with the
    route[return_route]. If a timeout occurs, no servers can be reached, or
    a jsonrpc error message is received, continues process at
    route[error_route]. In this case, the result_var will contain one of
    "timeout", "failure", or the error message received back from the
    jsonrpc server.
 
    The method, parameters, return_route, and error_route can be a static
    string or a dynamic string value with config variables.
 
    Since the SIP request handling is resumed in another process, the
    config file execution is lost. As mentioned above, only shared
    variables ($shv, etc) should be used for any value that will be needed
    when the script is resumed.
 
    The result is stored in the pseudo-variable 'result_var'. Since this
    variable is set after the response is received, it is possible to use a
    $var for this parameter.
 
    Example 1.3. jsonrpc_request usage
 ...
 jsonrpc_request("get_user", "{'id': 1234}", "RESPONSE", "ERROR", "$var(result)")
 ;
 ...
 route[RESPONSE] {
         xlog("Result received: $var(result)");
         ...
 }
 ...
 route[ERROR] {
         xlog("Error received: $var(result)");
         ...
 }
 ...