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