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();
    word encode();
    word 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, word len=0xffff);
    void add_string(word base, const char * name, const word * value, word len=0xffff);
    void add_replace_string(word base, const char * name, const char * value, word len=0xffff);
    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, word len=0xffff);

    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);
    const char * get_string(word base, word & last);
    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, word & last, bool * present = 0);

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

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;
    }
}