1JSONRPCC (jsonrpc client) Module 2 3Matthew Williams 4 5 <matthew@flowroute.com> 6 7Edited by 8 9Jordan Levy 10 11 <jordan@flowroute.com> 12 13 Copyright © 2011 Flowroute LLC (flowroute.com) 14 __________________________________________________________________ 15 16 Table of Contents 17 18 1. Admin Guide 19 20 1. Overview 21 2. Dependencies 22 23 2.1. Kamailio Modules 24 2.2. External Libraries or Applications 25 26 3. Parameters 27 28 3.1. servers (string) 29 3.2. max_conn_attempts (int) 30 31 4. Functions 32 33 4.1. jsonrpc_notification(method, parameters) 34 4.2. jsonrpc_request(method, parameters, return_route, 35 error_route, result_var) 36 37 List of Examples 38 39 1.1. Set servers parameter 40 1.2. Set max_conn_attempts parameter 41 1.3. jsonrpc_notification usage 42 1.4. jsonrpc_request usage 43 44Chapter 1. Admin Guide 45 46 Table of Contents 47 48 1. Overview 49 2. Dependencies 50 51 2.1. Kamailio Modules 52 2.2. External Libraries or Applications 53 54 3. Parameters 55 56 3.1. servers (string) 57 3.2. max_conn_attempts (int) 58 59 4. Functions 60 61 4.1. jsonrpc_notification(method, parameters) 62 4.2. jsonrpc_request(method, parameters, return_route, 63 error_route, result_var) 64 651. Overview 66 67 This module provides access to json-rpc services (operating over 68 TCP/Netstrings). 69 70 This module uses t_suspend() and t_continue() from the TM module. 71 72 Note that after invoking an asynchronous operation, the processing will 73 continue later, in another application process. Therefore, do not rely 74 on variables stored in private memory, use shared memory if you want to 75 get values after the processing is resumed (e.g., $shv(...) or htable 76 $sht(...)). 77 782. Dependencies 79 80 2.1. Kamailio Modules 81 2.2. External Libraries or Applications 82 832.1. Kamailio Modules 84 85 The following modules must be loaded before this module: 86 * tm - transaction management. 87 882.2. External Libraries or Applications 89 90 Note: this module uses Linux specific API, part of glibc library, it 91 might not compile on other types of operating systems. 92 93 The following libraries or applications must be installed before 94 running Kamailio with this module loaded: 95 * libjson (https://github.com/json-c/json-c/wiki) 96 * libevent - http://libevent.org/ 97 * glibc - http://www.gnu.org/software/libc/ (v2.8 or higher) 98 993. Parameters 100 101 3.1. servers (string) 102 3.2. max_conn_attempts (int) 103 1043.1. servers (string) 105 106 The servers providing the remote jsonrpc service. Format is 107 "host1:port1,priority1 host2:port2,priority2". Requests to servers of 108 the same priority will be distributed evenly (round robin). Server 109 groups with higher priority are used first. 110 111 Example 1.1. Set servers parameter 112... 113modparam("jsonrpcc", "servers", "localhost:9999,2 10.10.0.1:9999,2 backup.server 114:9999,1") 115... 116 1173.2. max_conn_attempts (int) 118 119 Max number of connection attempts for a server. -1 will keep 120 reconnecting forever, 0 will skip any attempt to reconnect. 121 122 Example 1.2. Set max_conn_attempts parameter 123... 124modparam("jsonrpcc", "max_conn_attempts", 10) 125... 126 1274. Functions 128 129 4.1. jsonrpc_notification(method, parameters) 130 4.2. jsonrpc_request(method, parameters, return_route, error_route, 131 result_var) 132 1334.1. jsonrpc_notification(method, parameters) 134 135 Invokes the remote 'method' with the given 'parameters' as a 136 notification. Unlike jsonrpc_request (below), notifications do not 137 receive a response. Script processing continues in the usual fashion as 138 soon as the notification has been sent. 139 140 The method and parameters can be a static string or dynamic string 141 value with config variables. 142 143 Example 1.3. jsonrpc_notification usage 144... 145jsonrpc_notification("update_user", "{'id': 1234, 'name': 'Petros'}") 146... 147 1484.2. jsonrpc_request(method, parameters, return_route, error_route, 149result_var) 150 151 Invokes the remote 'method' with the given 'parameters'. When the 152 response is received, continues processing of the SIP request with the 153 route[return_route]. If a timeout occurs, no servers can be reached, or 154 a jsonrpc error message is received, continues process at 155 route[error_route]. In this case, the result_var will contain one of 156 "timeout", "failure", or the error message received back from the 157 jsonrpc server. 158 159 The method, parameters, return_route, and error_route can be a static 160 string or a dynamic string value with config variables. 161 162 Since the SIP request handling is resumed in another process, the 163 config file execution is lost. As mentioned above, only shared 164 variables ($shv, etc) should be used for any value that will be needed 165 when the script is resumed. 166 167 The result is stored in the pseudo-variable 'result_var'. Since this 168 variable is set after the response is received, it is possible to use a 169 $var for this parameter. 170 171 Example 1.4. jsonrpc_request usage 172... 173jsonrpc_request("get_user", "{'id': 1234}", "RESPONSE", "ERROR", "$var(result)") 174; 175... 176route[RESPONSE] { 177 xlog("Result received: $var(result)"); 178 ... 179} 180... 181route[ERROR] { 182 xlog("Error received: $var(result)"); 183 ... 184} 185... 186