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

For information about the JSON structure and semantic, please refer to the RFC8259 article.
This current article explains the concepts of the JSON library by innovaphone

This library requires you to follow a specific order when adding properties to a JSON document. The document can be visualized as a tree structure, with each level representing either an object or an array. To add properties to an object, you must first add the object to the current level of the tree. Then, add all the properties to the object before moving to the next level. It's not possible to add another property to the same level as the object until all the properties have been added to the object.

Most code explaination will be refering to this JSON Object

{ 
    "name": "John Doe", 
    "age": 30, 
    "interests": [ 
        "programming", 
        "tv series", 
        "cooking"
    ],
    "address": {
        "street": "123 Street",
        "city": "City of New State",
        "state": "New State"
    },
    "email": "john.doe@aol.com"
}

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 top level 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 this:

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 this:

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.

Please check the JSON chunked decoding tutorial for more information.

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);
    void dump();

    word add(byte type, byte flags, word base, const char* name, const char* info, dword len = 0xffffffff);
    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_printfv(word base, const char * name, char * & tmp, const char * format, va_list ap);
    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);

    char* get_buffer()
    void set_buffer(char* buffer)

    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 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);
    word get_count(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);

    void trace(class debug_printf * dbg, word base, word level = 0);
    word to_url(word base, char * b, word l, const char * prefix = 0, bool cont = false);

    char * last;
    char * name_last;
    char * incomplete;
    unsigned max_item;

    };

Public functions

json.dump();
OUTPUT:
base=65535 count=11 flags=0 OBJECT=(NULL)/(NULL)
base=0 count=8 flags=1 VALUE=name/John Doe
base=0 count=2 flags=0 VALUE=age/30
base=0 count=3 flags=0 ARRAY=interests/(NULL)
base=3 count=11 flags=1 VALUE=(NULL)/programming
base=3 count=9 flags=1 VALUE=(NULL)/tv series
base=3 count=7 flags=1 VALUE=(NULL)/cooking
base=0 count=3 flags=0 OBJECT=address/(NULL)
base=7 count=10 flags=1 VALUE=street/123 Street
base=7 count=17 flags=1 VALUE=city/City of New State
base=7 count=9 flags=1 VALUE=state/New State
base=0 count=16 flags=1 VALUE=email/john.doe@aol.com

Variables

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"
    ],
    "address": {
        "street": "123 Street",
        "city": "City of New State",
        "state": "New State"
    },
    "email": "john.doe@aol.com"
}

char message[512];
char temp[64];
json_io json(message);
char* t = temp;
word base = json.add_object(JSON_ID_ROOT, 0);
json.add_string(base, "name", "John Doe");
json.add_unsigned(base, "age", 30, t);

word interests = json.add_array(base, "interests");
json.add_string(interests, nullptr, "programming");
json.add_string(interests, nullptr, "tv series");
json.add_string(interests, nullptr, "cooking");
    
word address = json.add_object(base, "address");
json.add_string(address, "street", "123 Street");
json.add_string(address, "city", "City of New State");
json.add_string(address, "state", "New State");

json.add_string(base, "email", "john.doe@aol.com");

json.add_string(interests, nullptr, "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;
    }
}

word address = json.get_object(base, "address");
const char* street = json.get_string(address, "street");
const char* city = json.get_string(address, "city");
const char* state = json.get_string(address, "state");

const char* email = json.get_string(base, "email");