Debian Codegraph @

src/modules/rtjson/README

raw
1 RTJSON Module
2
3 Daniel-Constantin Mierla
4
5 <[email protected]>
6
7 Edited by
8
9 Daniel-Constantin Mierla
10
11 <[email protected]>
12
13 Copyright © 2015 asipto.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. xavp_cfg (str)
29
30 4. Functions
31
32 4.1. rtjson_init_routes(rtdoc)
33 4.2. rtjson_push_routes()
34 4.3. rtjson_next_route()
35 4.4. rtjson_update_branch()
36
37 5. JSON Routing Structure
38
39 List of Examples
40
41 1.1. Set xavp_cfg parameter
42 1.2. rtjson_init_routes usage
43 1.3. rtjson_push_routes usage
44 1.4. rtjson_next_route usage
45 1.5. rtjson_update_branch usage
46 1.6. JSON Routing Structure
47
48 Chapter 1. Admin Guide
49
50 Table of Contents
51
52 1. Overview
53 2. Dependencies
54
55 2.1. Kamailio Modules
56 2.2. External Libraries or Applications
57
58 3. Parameters
59
60 3.1. xavp_cfg (str)
61
62 4. Functions
63
64 4.1. rtjson_init_routes(rtdoc)
65 4.2. rtjson_push_routes()
66 4.3. rtjson_next_route()
67 4.4. rtjson_update_branch()
68
69 5. JSON Routing Structure
70
71 1. Overview
72
73 This module facilitates SIP routing based on JSON specifications.
74
75 The values for R-URI ($ru), outbound proxy ($du) and other attributes
76 used for SIP routing can be retrieved in a JSON document. It is able to
77 process attributes for more than one destination and prepare for
78 routing in serial or parallel fashion.
79
80 2. Dependencies
81
82 2.1. Kamailio Modules
83 2.2. External Libraries or Applications
84
85 2.1. Kamailio Modules
86
87 The following modules must be loaded before this module:
88 * tm - (optional) transaction management.
89 uac - (optional) user agent operations.
90
91 2.2. External Libraries or Applications
92
93 The following libraries or applications must be installed before
94 running Kamailio with this module loaded:
95 * None
96
97 3. Parameters
98
99 3.1. xavp_cfg (str)
100
101 3.1. xavp_cfg (str)
102
103 The name of the xavp to be used internally by the module.
104
105 Default value is "rtjson".
106
107 Example 1.1. Set xavp_cfg parameter
108 ...
109 modparam("rtjson", "xavp_cfg", "myxavp")
110 ...
111
112 4. Functions
113
114 4.1. rtjson_init_routes(rtdoc)
115 4.2. rtjson_push_routes()
116 4.3. rtjson_next_route()
117 4.4. rtjson_update_branch()
118
119 4.1. rtjson_init_routes(rtdoc)
120
121 Initialize routing based on JSON document stored in rtdoc parameter.
122
123 The rtdoc parameter can be a static string or a dynamic string value
124 with config variables. It has to result in a valid JSON document with
125 the structure specified in chapter 'JSON Routing Structure'.
126
127 This function can be used from REQUEST_ROUTE.
128
129 Example 1.2. rtjson_init_routes usage
130 ...
131 rtjson_init_routes("$var(json)");
132 ...
133
134 4.2. rtjson_push_routes()
135
136 Push the routes given in JSON document to rtjson_init_routes(rtdoc) to
137 the internal fields used by Kamailio for routing.
138
139 This function can be used from REQUEST_ROUTE.
140
141 Example 1.3. rtjson_push_routes usage
142 ...
143 rtjson_init_routes("$var(json)");
144 rtjson_push_routes();
145 ...
146
147 4.3. rtjson_next_route()
148
149 To be used in failure_route for serial forking, to push the next route
150 to the internal fields used by Kamailio for routing.
151
152 This function can be used from FAILURE_ROUTE.
153
154 Example 1.4. rtjson_next_route usage
155 ...
156 rtjson_init_routes("$var(json)");
157 rtjson_push_routes();
158 t_on_failure("REROUTE");
159 t_relay();
160 ...
161 failure_route[REROUTE] {
162 rtjson_next_route();
163 }
164 ...
165
166 4.4. rtjson_update_branch()
167
168 To be used in branch_route if the JSON document had attributes that
169 needs to be set for each branch.
170
171 This function can be used from BRANCH_ROUTE.
172
173 Example 1.5. rtjson_update_branch usage
174 ...
175 rtjson_init_routes("$var(json)");
176 rtjson_push_routes();
177 t_on_branch("OUTGOING");
178 t_relay();
179 ...
180 branch_route[OUTGOING] {
181 rtjson_update_branch();
182 }
183 ...
184
185 5. JSON Routing Structure
186
187 The format of the JSON document containing routing information.
188
189 Description of the fields in the JSON routing document:
190 * version - intended to enforce versioning checks (not enforced yet),
191 recommended to be set to "1.0".
192 * routing - can be "serial" or "parallel", corresponding to desired
193 routing type: serial or parallel forking.
194 * routes - an array with structures holding the attributes for
195 destinations. The attributes can be:
196 + uri - request URI
197 + dst_uri - outbound proxy URI
198 + path - Path URI vector
199 + socket - local socket
200 + headers - a structure with values for headers From and To
201 specified as display name and URI, plus extra headers to be
202 appended to SIP request. It requires uac module in order to
203 update From and To headers. Set by rtjson_update_branch() only
204 for serial routing.
205 + branch_flags - branch flags. Set by rtjson_update_branch()
206 only for serial routing.
207 + fr_timer - value for fr_timer parameter of tm module. Set by
208 rtjson_update_branch() only for serial routing.
209 + fr_inv_timer - value for fr_inv_timer parameter of tm module.
210 Set by rtjson_update_branch() only for serial routing.
211
212 Other fields can appear in the JSON routing document, being ignored by
213 rtjson functions. They can be processed directly in the configuration
214 files using json or jansson modules. For example, the document can
215 include the transaction identification tuple (index,label) that can be
216 used to resume the execution of a suspended transaction.
217
218 Example 1.6. JSON Routing Structure
219 ...
220 {
221 "version": "1.0",
222 "routing": "serial",
223 "routes": [
224 {
225 "uri": "sip:[email protected]:5060",
226 "dst_uri": "sip:192.0.2.1:5060",
227 "path": "<sip:192.0.2.2:5084>, <sip:192.0.2.2:5086>",
228 "socket": "udp:192.0.2.20:5060",
229 "headers": {
230 "from": {
231 "display": "Alice",
232 "uri": "sip:[email protected]"
233 },
234 "to": {
235 "display": "Bob",
236 "uri": "sip:[email protected]"
237 },
238 "extra": "X-Hdr-A: abc\r\nX-Hdr-B: bcd\r\n"
239 },
240 "branch_flags": 8,
241 "fr_timer": 5000,
242 "fr_inv_timer": 30000
243 },
244 {
245 "uri": "sip:[email protected]:5060",
246 "dst_uri": "sip:192.0.2.10:5060",
247 "path": "<sip:192.0.2.2:5084>, <sip:192.0.2.2:5086>",
248 "socket": "udp:192.0.2.20:5060",
249 "headers": {
250 "from": {
251 "display": "Alice",
252 "uri": "sip:[email protected]"
253 },
254 "to": {
255 "display": "Bob",
256 "uri": "sip:[email protected]"
257 },
258 "extra": "P-Asserted-Identity: <sip:[email protected]>\r\n
259 "
260 },
261 "branch_flags": 8,
262 "fr_timer": 5000,
263 "fr_inv_timer": 30000
264 },
265 ]
266 }
267 ...