jansson Update jansson_get doc with return values that was hidden in the source code
[sip-router] / modules / jansson / doc / jansson_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13
14     <title>&adminguide;</title>
15
16     <section>
17     <title>Overview</title>
18     <para>
19                 This module provides operations on JSON strings using JANSSON
20                 library. It has support for JSON-PATH operations.
21     </para>
22     </section>
23
24     <section>
25     <title>Dependencies</title>
26     <section>
27         <title>&kamailio; Modules</title>
28         <para>
29         The following modules must be loaded before this module:
30             <itemizedlist>
31             <listitem>
32             <para>
33                 <emphasis>None</emphasis>
34             </para>
35             </listitem>
36             </itemizedlist>
37         </para>
38     </section>
39     <section>
40         <title>External Libraries or Applications</title>
41         <para>
42         The following libraries or applications must be installed before running
43         &kamailio; with this module loaded:
44             <itemizedlist>
45             <listitem>
46             <para>
47                 <emphasis>jansson (http://www.digip.org/jansson/)</emphasis>, tested with: 2.2+
48             </para>
49             </listitem>
50             </itemizedlist>
51         </para>
52     </section>
53     </section>
54     <section>
55     <title>Parameters</title>
56     <section>
57         <para>
58             <emphasis>None</emphasis>
59         </para>
60     </section>
61     </section>
62
63     <section>
64     <title>Functions</title>
65     <section>
66         <title>
67             <function moreinfo="none">jansson_get(key/path, src, dst)</function>
68         </title>
69         <para>
70             Copy the value at the location 'path' from the json object 'src' and store it in pvar 'dst'. 
71         </para>
72         <para>
73             The path string supports dot delimited notation (e.g. foo.bar.baz), array notation (e.g. [0]), or a combination of the two (e.g. foo.bar[0][1].baz).
74         </para>
75         <para>
76             Returns FALSE if the data can not be parsed, TRUE otherwise.
77         </para>
78         <para>
79             The function can put a string, integer, null, or new json string into destination.
80             If the key/path can't be found in the JSON data structure, the pvar is not changed. If it had a previous
81             value, that value remains unchanged.
82         </para>
83         <example>
84         <title><function>jansson_get</function> usage</title>
85         <programlisting format="linespecific">
86 ...
87 if(!jansson_get("inner.deep.list[3]", $var(myjson), "$var(n)")) {
88         xlog("L_ERR", "Can't parse json data");
89 }
90 xlog("L_INFO", "foo is $var(n)");
91 ...
92         </programlisting>
93         </example>
94     </section>
95     <section>
96         <title>
97             <function moreinfo="none">jansson_set(type, key/path, value, result)</function>
98         </title>
99         <para>
100             Insert 'value' as 'type' at location 'path' into 'result'.
101         </para>
102         <para>
103             The path string works the same as in jansson_get.
104         </para>
105         <para>
106             Valid 'type' parameters are 'integer', 'real', 'string', 'object', 'array', 'true', 'false', and 'null'  as well as
107             abbriviated names such as 'int', 'str', and 'obj'. 'value' is ignored when type is 'true', 'false', or 'null'.
108         </para>
109         <example>
110         <title><function>jansson_set</function> usage</title>
111         <programlisting format="linespecific">
112 ...
113 # create a new json object and put a string in it at key "mystr"
114 jansson_set("string", "mystr", "my input string", "$var(myjson)");
115 # $var(myjson) =='{"mystr":"my input string"}'
116
117 # add other values
118 jansson_set("integer", "count", 9000, "$var(myjson)");
119 jansson_set("true", "mybool", 0, "$var(myjson)");
120 jansson_set("real", "pi", "3.14159", "$var(myjson)");
121 # $var(myjson) == '{"mystr":"my input string", "count":9000, "mybool":true, "pi":3.14159}'
122
123 # add a nested object
124 jansson_set("obj", "myobj", '{"foo":"bar"}', "$var(myjson)");
125 # $var(myjson) =='{"mystr":"my input string", "count":9000, "mybool":true, "pi":3.14159, "myobj":{"foo":"bar"}}'
126
127 # change the nested object
128 jansson_set("str", "myobj.foo", "baz", "$var(myjson)");
129 # $var(myjson) == '{"mystr":"my input string", "count":9000, "mybool":true, "pi":3.14159, "myobj":{"foo":"baz"}}'
130 ...
131         </programlisting>
132         </example>
133     </section>
134     <section>
135         <title>
136             <function moreinfo="none">jansson_append(type, key/path, value, result)</function>
137         </title>
138         <para>
139             Like jansson_set but can be used to append to arrays. It can also be used to combine two json objects.
140         </para>
141         <para>
142             Note that when appending a json object to another json object, if there is a key that is shared between the two objects, that value will be overwritten by the new object.
143         </para>
144         <example>
145         <title><function>jansson_append</function> usage</title>
146         <programlisting format="linespecific">
147 ...
148 # create a new json array and append values to it
149 $var(myarray) = '[]';
150 jansson_append("int", "", 0, "$var(myarray)");
151 jansson_append("int", "", 1, "$var(myarray)");
152 jansson_append("int", "", 2, "$var(myarray)");
153 jansson_append("int", "", 3, "$var(myarray)");
154 jansson_append("int", "", 4, "$var(myarray)");
155 # $var(myarray) == '[0,1,2,3,4]'
156
157 # add that array to an object
158 jansson_set("array", "list", $var(myarray), "$var(myjson)");
159 # $var(myjson) == '{"list":[0,1,2,3,4]}'
160
161 # append another value to the list
162 jansson_append("int", "list", 5, "$var(myjson)");
163 # $var(myjson) == '{"list":[0,1,2,3,4,5]}'
164
165 # combining two json objects
166 $var(newobj) = '{"b":2, "c":3}';
167 jansson_append('obj', "", '{"a":1, "b":100}', "$var(newobj)");
168 # $var(newobj) == '{"a":1,"b":100","c":3}';
169 ...
170         </programlisting>
171         </example>
172     </section>
173     <section>
174         <title>
175             <function moreinfo="none">jansson_array_size(key/path, src, dst)</function>
176         </title>
177         <para>
178             Puts the size of the array in 'src' at location 'path' into the pvar 'dst'.
179         </para>
180         <para>
181             This is particularly useful for looping through an array. See example.
182         </para>
183         <example>
184         <title><function>jansson_array_size</function> usage</title>
185         <programlisting format="linespecific">
186 ...
187 $var(array) = "{\"loopme\":[0,1,2,3,4,5]}";
188 $var(count) = 0;
189 jansson_array_size("loopme", $var(array), "$var(size)");
190 while($var(count) &lt; $var(size)) {
191     jansson_get("loopme[$var(count)]", $var(array), "$var(v)");
192     xlog("loopme[$var(count)] == $var(v)\n");
193     $var(count) = $var(count) + 1;
194 }
195 ...
196         </programlisting>
197         </example>
198         <example>
199         <title>array concatination</title>
200         <programlisting format="linespecific">
201 ...
202 $var(count) = 0;
203 $var(appendme) = '[0,1]';
204 $var(mylist) = '[2,3,4,5]';
205 jansson_array_size("", $var(mylist), "$var(appendme_size)");
206 while($var(count) &lt; $var(appendme_size)) {
207     jansson_get("[$var(count)]", $var(mylist), "$var(tmp)");
208     jansson_append('int', "", $var(tmp), "$var(appendme)");
209     $var(count) = $var(count) + 1;
210 }
211 ...
212         </programlisting>
213         </example>
214     </section>
215     <section>
216         <title>
217             <function moreinfo="none">jansson_get_field(src, field_name, dst)</function>
218         </title>
219         <para>
220             Copy field 'field_name' from json object 'src' and store it in pvar 'dst'.
221         </para>
222         <para>
223             <emphasis>This function is deprecated</emphasis> but kept for backwards compatibility. Right now it is just a wrapper around <function>jansson_get</function>, and its functionality is the same.
224         </para>
225         <example>
226         <title><function>jansson_get_field</function> usage</title>
227         <programlisting format="linespecific">
228 ...
229 jansson_get_field("{'foo':'bar'}", "foo", "$var(foo)");
230 xlog("foo is $var(foo)");
231 ...
232         </programlisting>
233         </example>
234     </section>
235     </section>
236 </chapter>
237