src/modules/jansson/README
2e6af40e
 JANSSON Module
 
 Joe Hillenbrand
 
    <joe@flowroute.com>
 
 Edited by
 
 Matthew Williams
 
    <matthew@flowroute.com>
 
691e088f
 Carsten Bock
 
    <carsten@ng-voice.com>
 
    Copyright © 2013 Flowroute LLC (flowroute.com)
2e6af40e
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
         1. Overview
         2. Dependencies
 
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
92dcec82
         3. Functions
2e6af40e
 
92dcec82
               3.1. jansson_get(key/path, src, dst)
               3.2. jansson_set(type, key/path, value, result)
               3.3. jansson_append(type, key/path, value, result)
               3.4. jansson_array_size(key/path, src, dst)
               3.5. jansson_get_field(src, field_name, dst)
2e6af40e
 
    List of Examples
 
    1.1. jansson_get usage
    1.2. jansson_set usage
    1.3. jansson_append usage
    1.4. jansson_array_size usage
8868e624
    1.5. array concatenation
2e6af40e
    1.6. 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
 
92dcec82
    3. Functions
2e6af40e
 
92dcec82
         3.1. jansson_get(key/path, src, dst)
         3.2. jansson_set(type, key/path, value, result)
         3.3. jansson_append(type, key/path, value, result)
         3.4. jansson_array_size(key/path, src, dst)
         3.5. jansson_get_field(src, field_name, dst)
2e6af40e
 
 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+
 
92dcec82
 3. Functions
2e6af40e
 
92dcec82
    3.1. jansson_get(key/path, src, dst)
    3.2. jansson_set(type, key/path, value, result)
    3.3. jansson_append(type, key/path, value, result)
    3.4. jansson_array_size(key/path, src, dst)
    3.5. jansson_get_field(src, field_name, dst)
2e6af40e
 
691e088f
 3.1.  jansson_get(key/path, src, dst)
2e6af40e
 
    Copy the value at the location 'path' from the json object 'src' and
    store it in pvar 'dst'.
 
    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).
 
b424214e
    Returns FALSE if the data can not be parsed, TRUE otherwise.
 
2e6af40e
    The function can put a string, integer, null, or new json string into
2471d1db
    destination. If the key/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.
2e6af40e
 
691e088f
    Note: For JSON-Integer values exceeding the C-Integer boundaries, a
    String representing the number is returned.
 
2e6af40e
    Example 1.1. jansson_get usage
 ...
b424214e
 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)");
2e6af40e
 ...
 
691e088f
 3.2.  jansson_set(type, key/path, value, result)
2e6af40e
 
    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',
8868e624
    'array', 'true', 'false', and 'null' as well as abbreviated names such
2e6af40e
    as 'int', 'str', and 'obj'. 'value' is ignored when type is 'true',
    'false', or 'null'.
 
691e088f
    Note: If you want to insert a JSON-Integer value exceeding the
    C-Integer boundaries (e.g. C-type long), the a the number can be
    provided as a string.
 
2e6af40e
    Example 1.2. 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"}}'
 ...
 
691e088f
 3.3.  jansson_append(type, key/path, value, result)
2e6af40e
 
    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.3. 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}';
 ...
 
691e088f
 3.4.  jansson_array_size(key/path, src, dst)
2e6af40e
 
    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.4. 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;
 }
 ...
 
8868e624
    Example 1.5. array concatenation
2e6af40e
 ...
 $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;
 }
 ...
 
691e088f
 3.5.  jansson_get_field(src, field_name, dst)
2e6af40e
 
    Copy field 'field_name' from json object 'src' and store it in pvar
    'dst'.
 
    This function is deprecated but kept for backwards compatibility. Right
    now it is just a wrapper around jansson_get, and its functionality is
    the same.
 
    Example 1.6. jansson_get_field usage
 ...
 jansson_get_field("{'foo':'bar'}", "foo", "$var(foo)");
 xlog("foo is $var(foo)");
 ...