JSON Library

JSON is a data interchange format that can be used to transmit data objects as human readable text. The innovaphone apps use JSON for all websocket protocols. This library can be used to encode and decode JSON in C++.

File information

Overview

JSON uses the following primitive data types.

• string
• integer
• unsigned
• boolean
• null

JSON uses the following constructed data types.

• object
• array

Here are some hints how JSON messages are build up.

• The top level element of a JSON string can be either a primitive or a constructed data type.
• When a JSON document is created using this library, you need to add elements to the json_io instance in the order as they appear in the JSON document.
• Strings are encoded using quotes.
  

  "some text"

  All other primitive data style are encoded without quotes.
  

  -4
  17
  true
  null

• Arrays use brackets as delimiters. The elements of an array are 0..n comma-separated unnamed values. The values can be any primitive or constructed data type.
  

  [ "a", "b", -5, false ]

• Objects use curly braces as delimiters. The elements of an object are 0..n comma-separated name-value-pairs. The names use quoted encoding. The values can be any primitive or constructed data type.
  

  { "name": "John Doe", "age": 30, "interests": [ "programming", "tv series", "cooking" ] }

• Line breaks and extra white space can be inserted, but is ignored by JSON decoders.
  

  { 
      "name": "John Doe", 
      "age": 30, 
      "interests": [ 
          "programming", 
          "tv series", 
          "cooking"
      ] 
  }

  Note that the library does not insert any extra white space.
  

  {"name":"John Doe","age": 30,"interests":["programming","tv series","cooking"]}

Classes

class json_io {
    public:
    json_io(char * buffer);

    void reset();
    bool decode();
    dword encode();
    dword encode(word handle, char * buffer);
    void write(word current, char * & p, word incomplete = 0xffff);

    word add_object(word base, const char * name);
    word add_array(word base, const char * name);
    void add_string(word base, const char * name, const char * value, dword len=0xffffffff);
    void add_string(word base, const char * name, const word * value, dword len, char * & tmp);
    void add_string(word base, const char * name, const word * value, char * & tmp) { add_string(base, name, value, 0xffffffff, tmp); };
    void add_replace_string(word base, const char * name, const char * value, dword len=0xffffffff);
    void add_int(word base, const char * name, int c, char * & tmp);
    void add_unsigned(word base, const char * name, dword c, char * & tmp);
    void add_long64(word base, const char * name, long64 c, char * & tmp);
    void add_ulong64(word base, const char * name, ulong64 c, char * & tmp);
    void add_bool(word base, const char * name, bool value);
    void add_null(word base, const char * name);
    void add_double(word base, const char * name, double c, char *& tmp, byte decimalPlaces = 6);

    void add_printf(word base, const char * name, char * & tmp, const char * format, ...);
    void add_hexstring(word base, const char * name, const byte * hex, word hex_len, char * & tmp);
    void add_json(word base, const char * name, const char * value, dword len=0xffffffff);

    word get_object(word base, const char * name);
    word get_object(word base, word & last);
    word get_array(word base, const char * name);
    word get_array(word base, word & last);
    const char * get_string(word base, const char * name, bool * present=0);
    const char * get_string(word base, word & last, bool * present=0);
    int get_int(word base, const char * name, bool * present=0);
    int get_int(word base, word & last, bool * present=0);
    dword get_unsigned(word base, const char * name, bool * present=0);
    dword get_unsigned(word base, word & last, bool * present=0);
    long64 get_long64(word base, const char * name, bool * present = 0);
    long64 get_long64(word base, word & last, bool * present = 0);
    ulong64 get_ulong64(word base, const char * name, bool * present = 0);
    ulong64 get_ulong64(word base, word & last, bool * present = 0);
    bool get_bool(word base, const char * name, bool * present=0);
    bool get_bool(word base, word & last, bool * present=0);
    bool get_bool_int(word base, const char * name, int & iret, byte * present=0);
    double get_double(word base, const char * name, bool * present = 0);
    double get_double(word base, word & last, bool * present = 0);

    byte get_flags(word handle);

    word to_url(word base, char * b, word l, const char * prefix = 0, bool cont = false);

    // advanced functions currently not documented
    word get_next(word base, word last, byte & type, byte & flags, const char * & name, const char * & info);
    word get_index();
    const char * get_name(word handle);
    const char * get_info(word handle);
    const char* get_value(word base, byte flags, const char* name, bool * present=0);
    const char* get_value(word base, byte flags, word& last, bool * present=0);

    char * last;
    char * name_last;
    char * incomplete;
};

Overview

The json_io class can be used for encoding and decoding JSON messages to or from a char buffer.

Each element has a unique numeric ID word base. JSON_ID_ROOT represents the root element. It can be no or a single element. Often the root is an object that holds all the other data. Normally json_io can be used as a stack variable. A typical encoding flow looks like that:

char message[512];
json_io json(message);
word base = json.add_object(JSON_ID_ROOT, 0);
// add elements
json.encode();

Decoding is usually done like that:

json_io json(message);
json.decode();
word base = recv.get_object(JSON_ID_ROOT, 0);
// read elements

There are two different methods for traversing the JSON structure. Inside objects the elements are referenced by their name.

// adding elements
json.add_string(base, "name", "John Doe");
// reading elements
const char * name = json.get_string(base, "name");

Inside arrays the elements are enumerated.

// adding elements
json.add_string(base, 0, "programming");
json.add_string(base, 0, "tv series");
json.add_string(base, 0, "cooking");
// reading elements
word last = 0;
do {
    const char * interest = json.get_string(base, last);
}
while (last != JSON_ID_NONE);

Some add functions need an additional buffer for storing the values temporarily. Those buffers are called char * & tmp in the interface. Note that the buffer pointer reference is increased when adding an element.

char temp[128];
char * t = temp;
json.add_attrib_printf(base, "name", t, "%s %s", "John", "Doe");
json.add_unsigned(base, "age", 30, t);

Chunked decoding

Sometimes JSON objects exceed the limits of json_io, so that they cannot be decoded completely in one step. In this case chuncked decoding can be used. Chunked decoding works if on some level of the JSON object a list exists, either as array or as object, which each element of this list not exceeding the limits.

The chunked decoding works with the following steps:

• Decode the data. The decoding returns an error, because the JSON data is incomplete
• Find the list within the decoded data using get_array or get_object
• Walk thru the list, until an element with the flag JSON_FLAG_INCOMPLETE is encountered.
• Do an encode incomplete of the data, using write with the incomplete parameter set to the list (object or array). This only encodes the elements, which are not yet complete, together with the element into which they are embedded
• Get the next chunk and append it to the encoded data and repeat the prevous steps until decoding does not return an error

Sample code for chunked decoding

// data is received/read in "buf" with a lenght of len. fill is initialized to 0
// and stores the length of the remaining incomplete data
if (len) {
    // decode
    buf[fill + len] = 0;
    class json_io json(buf);
    json.decode();

    // get array of objects
    word a = json.get_array(JSON_ID_NONE, 0);
    if (a != JSON_ID_NONE) {
        for (word base = json.get_object(a, 0); base != JSON_ID_NONE && !(json.get_flags(base) &JSON_FLAG_INCOMPLETE); base = json.get_object(a, base)) {
            word object = json.get_object(base, "object");
            // process the data
        }
        // write incomplete data to buf
        char * x = buf;
        json.write(0, x, a);
        fill = x - buf;
    }
}
// append next chunk to the end of the incomplete data
Recv(&buf[fill])

Public functions

Data types

Defines

Code Examples

The following examples demonstrate the library on the following JSON structure.

{ 
    "name": "John Doe", 
    "age": 30, 
    "interests": [ 
        "programming", 
        "tv series", 
        "cooking"
    ],
    "email": "john.doe@aol.com"
}

char message[256];
json_io json(message);

word base = json.add_object(JSON_ID_ROOT, 0);
json.add_string(base, "name", "John Doe");
json.add_unsigned(base, "age", 30);

word interests = json.add_array(base, "interests");
json.add_string(interests, "programming");
json.add_string(interests, "tv series");
json.add_string(interests, "cooking");
json.add_string(base, "email", "john.doe@aol.com");
json.add_string(interests, "fishing"); // this will have no effect, cause "interests" handle is not valid any more

json.encode();

json_io json(message);
json.decode();

word base = json.get_object(JSON_ID_ROOT, 0);
const char * name = json.get_string(base, "name");
dword age = json.get_unsigned(base, "age");

const char * interest_values[4];
word interest_count = 0;
word interests = json.get_array(base, "interests");
word last = 0;

while (last != JSON_ID_NONE && interest_count < 4) {
    const char * value = = json.get_string(interests, last);
    if (value) {
        interest_values[interest_count++] = value;
    }
}