1JANSSON Module
2
3Joe Hillenbrand
4
5 <joe@flowroute.com>
6
7Edited by
8
9Matthew Williams
10
11 <matthew@flowroute.com>
12
13Carsten Bock
14
15 <carsten@ng-voice.com>
16
17 Copyright © 2013 Flowroute LLC (flowroute.com)
18 __________________________________________________________________
19
20 Table of Contents
21
22 1. Admin Guide
23
24 1. Overview
25 2. Dependencies
26
27 2.1. Kamailio Modules
28 2.2. External Libraries or Applications
29
30 3. Functions
31
32 3.1. jansson_get(key/path, src, dst)
33 3.2. jansson_set(type, key/path, value, result)
34 3.3. jansson_append(type, key/path, value, result)
35 3.4. jansson_array_size(key/path, src, dst)
36 3.5. jansson_get_field(src, field_name, dst)
37
38 List of Examples
39
40 1.1. jansson_get usage
41 1.2. jansson_set usage
42 1.3. jansson_append usage
43 1.4. jansson_array_size usage
44 1.5. array concatenation
45 1.6. jansson_get_field usage
46
47Chapter 1. Admin Guide
48
49 Table of Contents
50
51 1. Overview
52 2. Dependencies
53
54 2.1. Kamailio Modules
55 2.2. External Libraries or Applications
56
57 3. Functions
58
59 3.1. jansson_get(key/path, src, dst)
60 3.2. jansson_set(type, key/path, value, result)
61 3.3. jansson_append(type, key/path, value, result)
62 3.4. jansson_array_size(key/path, src, dst)
63 3.5. jansson_get_field(src, field_name, dst)
64
651. Overview
66
67 This module provides operations on JSON strings using JANSSON library.
68 It has support for JSON-PATH operations.
69
702. Dependencies
71
72 2.1. Kamailio Modules
73 2.2. External Libraries or Applications
74
752.1. Kamailio Modules
76
77 The following modules must be loaded before this module:
78 * None
79
802.2. External Libraries or Applications
81
82 The following libraries or applications must be installed before
83 running Kamailio with this module loaded:
84 * jansson (http://www.digip.org/jansson/), tested with: 2.2+
85
863. Functions
87
88 3.1. jansson_get(key/path, src, dst)
89 3.2. jansson_set(type, key/path, value, result)
90 3.3. jansson_append(type, key/path, value, result)
91 3.4. jansson_array_size(key/path, src, dst)
92 3.5. jansson_get_field(src, field_name, dst)
93
943.1. jansson_get(key/path, src, dst)
95
96 Copy the value at the location 'path' from the json object 'src' and
97 store it in pvar 'dst'.
98
99 The path string supports dot delimited notation (e.g. foo.bar.baz),
100 array notation (e.g. [0]), or a combination of the two (e.g.
101 foo.bar[0][1].baz).
102
103 Returns FALSE if the data can not be parsed, TRUE otherwise.
104
105 The function can put a string, integer, null, or new json string into
106 destination. If the key/path can't be found in the JSON data structure,
107 the pvar is not changed. If it had a previous value, that value remains
108 unchanged.
109
110 Note: For JSON-Integer values exceeding the C-Integer boundaries, a
111 String representing the number is returned.
112
113 Example 1.1. jansson_get usage
114...
115if(!jansson_get("inner.deep.list[3]", $var(myjson), "$var(n)")) {
116 xlog("L_ERR", "Can't parse json data");
117}
118xlog("L_INFO", "foo is $var(n)");
119...
120
1213.2. jansson_set(type, key/path, value, result)
122
123 Insert 'value' as 'type' at location 'path' into 'result'.
124
125 The path string works the same as in jansson_get.
126
127 Valid 'type' parameters are 'integer', 'real', 'string', 'object',
128 'array', 'true', 'false', and 'null' as well as abbreviated names such
129 as 'int', 'str', and 'obj'. 'value' is ignored when type is 'true',
130 'false', or 'null'.
131
132 Note: If you want to insert a JSON-Integer value exceeding the
133 C-Integer boundaries (e.g. C-type long), the a the number can be
134 provided as a string.
135
136 Example 1.2. jansson_set usage
137...
138# create a new json object and put a string in it at key "mystr"
139jansson_set("string", "mystr", "my input string", "$var(myjson)");
140# $var(myjson) =='{"mystr":"my input string"}'
141
142# add other values
143jansson_set("integer", "count", 9000, "$var(myjson)");
144jansson_set("true", "mybool", 0, "$var(myjson)");
145jansson_set("real", "pi", "3.14159", "$var(myjson)");
146# $var(myjson) == '{"mystr":"my input string", "count":9000, "mybool":true, "pi"
147:3.14159}'
148
149# add a nested object
150jansson_set("obj", "myobj", '{"foo":"bar"}', "$var(myjson)");
151# $var(myjson) =='{"mystr":"my input string", "count":9000, "mybool":true, "pi":
1523.14159, "myobj":{"foo":"bar"}}'
153
154# change the nested object
155jansson_set("str", "myobj.foo", "baz", "$var(myjson)");
156# $var(myjson) == '{"mystr":"my input string", "count":9000, "mybool":true, "pi"
157:3.14159, "myobj":{"foo":"baz"}}'
158...
159
1603.3. jansson_append(type, key/path, value, result)
161
162 Like jansson_set but can be used to append to arrays. It can also be
163 used to combine two json objects.
164
165 Note that when appending a json object to another json object, if there
166 is a key that is shared between the two objects, that value will be
167 overwritten by the new object.
168
169 Example 1.3. jansson_append usage
170...
171# create a new json array and append values to it
172$var(myarray) = '[]';
173jansson_append("int", "", 0, "$var(myarray)");
174jansson_append("int", "", 1, "$var(myarray)");
175jansson_append("int", "", 2, "$var(myarray)");
176jansson_append("int", "", 3, "$var(myarray)");
177jansson_append("int", "", 4, "$var(myarray)");
178# $var(myarray) == '[0,1,2,3,4]'
179
180# add that array to an object
181jansson_set("array", "list", $var(myarray), "$var(myjson)");
182# $var(myjson) == '{"list":[0,1,2,3,4]}'
183
184# append another value to the list
185jansson_append("int", "list", 5, "$var(myjson)");
186# $var(myjson) == '{"list":[0,1,2,3,4,5]}'
187
188# combining two json objects
189$var(newobj) = '{"b":2, "c":3}';
190jansson_append('obj', "", '{"a":1, "b":100}', "$var(newobj)");
191# $var(newobj) == '{"a":1,"b":100","c":3}';
192...
193
1943.4. jansson_array_size(key/path, src, dst)
195
196 Puts the size of the array in 'src' at location 'path' into the pvar
197 'dst'.
198
199 This is particularly useful for looping through an array. See example.
200
201 Example 1.4. jansson_array_size usage
202...
203$var(array) = "{\"loopme\":[0,1,2,3,4,5]}";
204$var(count) = 0;
205jansson_array_size("loopme", $var(array), "$var(size)");
206while($var(count) < $var(size)) {
207 jansson_get("loopme[$var(count)]", $var(array), "$var(v)");
208 xlog("loopme[$var(count)] == $var(v)\n");
209 $var(count) = $var(count) + 1;
210}
211...
212
213 Example 1.5. array concatenation
214...
215$var(count) = 0;
216$var(appendme) = '[0,1]';
217$var(mylist) = '[2,3,4,5]';
218jansson_array_size("", $var(mylist), "$var(appendme_size)");
219while($var(count) < $var(appendme_size)) {
220 jansson_get("[$var(count)]", $var(mylist), "$var(tmp)");
221 jansson_append('int', "", $var(tmp), "$var(appendme)");
222 $var(count) = $var(count) + 1;
223}
224...
225
2263.5. jansson_get_field(src, field_name, dst)
227
228 Copy field 'field_name' from json object 'src' and store it in pvar
229 'dst'.
230
231 This function is deprecated but kept for backwards compatibility. Right
232 now it is just a wrapper around jansson_get, and its functionality is
233 the same.
234
235 Example 1.6. jansson_get_field usage
236...
237jansson_get_field("{'foo':'bar'}", "foo", "$var(foo)");
238xlog("foo is $var(foo)");
239...
240