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