JANSSON Module

Joe Hillenbrand

   <joe@flowroute.com>

Edited by

Matthew Williams

   <matthew@flowroute.com>

Carsten Bock

   <carsten@ng-voice.com>

   Copyright © 2013 Flowroute LLC (flowroute.com)
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Functions

              3.1. jansson_get(path, src, dst)
              3.2. jansson_pv_get(key/path, srcvar, dst)
              3.3. jansson_set(type, key/path, value, result)
              3.4. jansson_append(type, key/path, value, result)
              3.5. jansson_array_size(key/path, src, dst)
              3.6. jansson_xdecode(json, xavp)
              3.7. jansson_xencode(xavp, pv)
              3.8. jansson_get_field(field_name, src, dst)

   List of Examples

   1.1. jansson_get usage
   1.2. jansson_pv_get usage
   1.3. jansson_set usage
   1.4. jansson_append usage
   1.5. jansson_array_size usage
   1.6. array concatenation
   1.7. jansson_xdecode usage
   1.8. jansson_xencode usage
   1.9. jansson_get_field usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Functions

        3.1. jansson_get(path, src, dst)
        3.2. jansson_pv_get(key/path, srcvar, dst)
        3.3. jansson_set(type, key/path, value, result)
        3.4. jansson_append(type, key/path, value, result)
        3.5. jansson_array_size(key/path, src, dst)
        3.6. jansson_xdecode(json, xavp)
        3.7. jansson_xencode(xavp, pv)
        3.8. jansson_get_field(field_name, src, dst)

1. Overview

   This module provides operations on JSON strings using JANSSON library.
   It has support for JSON-PATH operations.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * None

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * jansson (http://www.digip.org/jansson/), tested with: 2.2+

3. Functions

   3.1. jansson_get(path, src, dst)
   3.2. jansson_pv_get(key/path, srcvar, dst)
   3.3. jansson_set(type, key/path, value, result)
   3.4. jansson_append(type, key/path, value, result)
   3.5. jansson_array_size(key/path, src, dst)
   3.6. jansson_xdecode(json, xavp)
   3.7. jansson_xencode(xavp, pv)
   3.8. jansson_get_field(field_name, src, dst)

3.1.  jansson_get(path, src, dst)

   Copy the value at the location 'path' from the json object 'src' and
   store it in variable 'dst'. The path can also be a simple field name (a
   key), if it does not include any path separator. To retrieve the value
   of a field that includes path separators in the name, use
   jansson_get_field().

   The 'src' can be a static string or a dynamic string with variables.

   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).

   Returns FALSE if the data can not be parsed, TRUE otherwise.

   The function can put a string, integer, null, or new json string into
   destination. If the path can't be found in the JSON data structure, the
   pvar is not changed. If it had a previous value, that value remains
   unchanged.

   Note: For JSON-Integer values exceeding the C-Integer boundaries, a
   String representing the number is returned.

   Example 1.1. jansson_get usage
...
if(!jansson_get("inner.deep.list[3]", "$var(myjson)", "$var(n)")) {
        xlog("L_ERR", "Can't parse json data");
}
xlog("L_INFO", "foo is $var(n)");
...
jansson_get("test", "{\"test\":\"abc\",\"idx\":20}", "$var(n)")
...

3.2.  jansson_pv_get(key/path, srcvar, dst)

   Similar to jansson_get(), but the 'srcvar' parameter can be only a
   variable name.

   Example 1.2. jansson_pv_get usage
...
if(!jansson_pv_get("inner.deep.list[3]", "$var(myjson)", "$var(n)")) {
        xlog("L_ERR", "Can't parse json data");
}
xlog("L_INFO", "foo is $var(n)");
...

3.3.  jansson_set(type, key/path, value, result)

   Insert 'value' as 'type' at location 'path' into 'result'.

   The path string works the same as in jansson_get.

   Valid 'type' parameters are 'integer', 'real', 'string', 'object',
   'array', 'true', 'false', and 'null' as well as abbreviated names such
   as 'int', 'str', and 'obj'. 'value' is ignored when type is 'true',
   'false', or 'null'.

   Note: If you want to insert a JSON-Integer value exceeding the
   C-Integer boundaries (e.g. C-type long), then the number can be
   provided as a string.

   Example 1.3. jansson_set usage
...
# create a new json object and put a string in it at key "mystr"
jansson_set("string", "mystr", "my input string", "$var(myjson)");
# $var(myjson) =='{"mystr":"my input string"}'

# add other values
jansson_set("integer", "count", 9000, "$var(myjson)");
jansson_set("true", "mybool", 0, "$var(myjson)");
jansson_set("real", "pi", "3.14159", "$var(myjson)");
# $var(myjson) == '{"mystr":"my input string", "count":9000, "mybool":true, "pi"
:3.14159}'

# add a nested object
jansson_set("obj", "myobj", '{"foo":"bar"}', "$var(myjson)");
# $var(myjson) =='{"mystr":"my input string", "count":9000, "mybool":true, "pi":
3.14159, "myobj":{"foo":"bar"}}'

# change the nested object
jansson_set("str", "myobj.foo", "baz", "$var(myjson)");
# $var(myjson) == '{"mystr":"my input string", "count":9000, "mybool":true, "pi"
:3.14159, "myobj":{"foo":"baz"}}'
...

3.4.  jansson_append(type, key/path, value, result)

   Like jansson_set but can be used to append to arrays. It can also be
   used to combine two json objects.

   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.

   Example 1.4. jansson_append usage
...
# create a new json array and append values to it
$var(myarray) = '[]';
jansson_append("int", "", 0, "$var(myarray)");
jansson_append("int", "", 1, "$var(myarray)");
jansson_append("int", "", 2, "$var(myarray)");
jansson_append("int", "", 3, "$var(myarray)");
jansson_append("int", "", 4, "$var(myarray)");
# $var(myarray) == '[0,1,2,3,4]'

# add that array to an object
jansson_set("array", "list", $var(myarray), "$var(myjson)");
# $var(myjson) == '{"list":[0,1,2,3,4]}'

# append another value to the list
jansson_append("int", "list", 5, "$var(myjson)");
# $var(myjson) == '{"list":[0,1,2,3,4,5]}'

# combining two json objects
$var(newobj) = '{"b":2, "c":3}';
jansson_append('obj', "", '{"a":1, "b":100}', "$var(newobj)");
# $var(newobj) == '{"a":1,"b":100","c":3}';
...

3.5.  jansson_array_size(key/path, src, dst)

   Puts the size of the array in 'src' at location 'path' into the pvar
   'dst'.

   This is particularly useful for looping through an array. See example.

   Example 1.5. jansson_array_size usage
...
$var(array) = "{\"loopme\":[0,1,2,3,4,5]}";
$var(count) = 0;
jansson_array_size("loopme", $var(array), "$var(size)");
while($var(count) < $var(size)) {
    jansson_get("loopme[$var(count)]", $var(array), "$var(v)");
    xlog("loopme[$var(count)] == $var(v)\n");
    $var(count) = $var(count) + 1;
}
...

   Example 1.6. array concatenation
...
$var(count) = 0;
$var(appendme) = '[0,1]';
$var(mylist) = '[2,3,4,5]';
jansson_array_size("", $var(mylist), "$var(appendme_size)");
while($var(count) < $var(appendme_size)) {
    jansson_get("[$var(count)]", $var(mylist), "$var(tmp)");
    jansson_append('int', "", $var(tmp), "$var(appendme)");
    $var(count) = $var(count) + 1;
}
...

3.6.  jansson_xdecode(json, xavp)

   Parse a JSON string in 'json' and store the elements in xapv 'xavp'.
   Top-level JSON must be an object or an array of objects. Nested arrays
   and objects are not decoded but stored as string.

   Example 1.7. jansson_xdecode usage
...
jansson_xdecode('{"foo":"bar"}', "js");
xlog("foo is $xavp(js=>foo)");
...

3.7.  jansson_xencode(xavp, pv)

   Encode the items in the xavp 'xavp' as JSON and store the result in a
   pv. Nested xavp's are not supported.

   Example 1.8. jansson_xencode usage
...
$xavp(a=>foo) = "bar";
jansson_xencode("a", "$var(js)");
# $var(js) = '{"foo":"bar"}'
...

3.8.  jansson_get_field(field_name, src, dst)

   Copy the value of the field 'field_name' from json object 'src' and
   store it in pvar 'dst'. The field name is not evaluated as JSON path,
   therefore it has a different behaviour than jansson_get() and can be
   used when the field name contains path delimiters.

   Note that till version 5.7.x, this function was similar to
   jansson_get(), after that its behaviour changed to work as described
   above. Also, the order of parameters changed.

   Example 1.9. jansson_get_field usage
...
jansson_get_field("foo", "{'foo':'bar'}", "$var(foo)");
xlog("foo is $var(foo)");
jansson_get_field("foo.foz", "{'foo.foz':'bar.buz'}", "$var(foofoz)");
xlog("foo.foz is $var(foofoz)");
...
