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