JSON Parser/Builder

The JSON library provides APIs to parse and build JSON objects. More...

Macros
#define	JSON_DEFAULT_SIZE   (1024u)

Typedefs
typedef size_t	Json_Handle
typedef enum json_rc_TAG	json_rc_T

Enumerations
enum	json_rc_TAG {   JSON_RC__OK = 0,   JSON_RC__RECOVERED__IGNORED_UNKNOWN_VALUE = -1,   JSON_RC__RECOVERED__NESTING_EXCEEDED__IGNORING_LEAVES =-4,   JSON_RC__RECOVERED__PARSING_FAILURE = -5,   JSON_RC__RECOVERED__INVALID_VALUE = -22,   JSON_RC__RECOVERED__NUMBER_ACCURACY_LOSS = -23,   JSON_RC__RECOVERED__NUMBER_OVERFLOW = -24,   JSON_RC__RECOVERED__ILLEGAL_Q_VALUES = -25,   JSON_RC__RECOVERED__STRING_TRUNCATED = -28,   JSON_RC__REWIND_REQUIRED = -99,   JSON_RC__RECOVERABLE_ERROR__MINIMUM_VALUE = -100,   JSON_RC__PARSING_BUFFER_SIZE_EXCEEDED = -101,   JSON_RC__PARSING_FAILURE = -102,   JSON_RC__PARSING_FAILURE__INCOMPLETE_STRING = -103,   JSON_RC__NO_HASH_FOUND = -104,   JSON_RC__BUILDING_UNKNOWN_ATOM = -105,   JSON_RC__BUILDING_BUFFER_SIZE_EXCEEDED = -106,   JSON_RC__BUILDING_PARSED_DATA_EXHAUSTED = -107,   JSON_RC__WRONG_VALUE_SIZE_FOR_TYPE = -108,   JSON_RC__VALUE_NOT_AN_ARRAY = -109,   JSON_RC__INDEX_FAR_BEYOND_ARRAY_END = -110,   JSON_RC__PARSING_BUFFER_SIZE_WOULD_HAVE_EXCEEDED = -111,   JSON_RC__NOT_SUPPORTED = -128,   JSON_RC__NOT_FOUND = -200,   JSON_RC__VALUE_IS_NULL = -201,   JSON_RC__VALUE_NOT_VALID = -202,   JSON_RC__NESTING_EXCEEDED = -204,   JSON_RC__MEMORY_ALLOCATION_ERROR = -300,   JSON_RC__INVALID_TEMPLATE_HANDLE = -301,   JSON_RC__INVALID_OBJECT_HANDLE = -302,   JSON_RC__UNEXPECTED_ERROR = -16384 }

Functions
int16_t	Json_createTemplate (Json_Handle *templateHandle, const char *templateString, uint16_t templateStringLen)
	This function creates internal template from the template text. More...
int16_t	Json_destroyTemplate (Json_Handle templateHandle)
	This function frees the internal template memory. More...
int16_t	Json_createObject (Json_Handle *objHandle, Json_Handle templateHandle, uint16_t maxObjectSize)
	This function creates an empty Json object. More...
int16_t	Json_destroyObject (Json_Handle objHandle)
	Free the internal json memory. More...
int16_t	Json_parse (Json_Handle objHandle, char *jsonText, uint16_t jsonTextLen)
	This function converts the json text into internal representation. More...
int16_t	Json_getArrayMembersCount (Json_Handle objHandle, const char *pKey)
	Retrieve the number of array elements in the provided key. More...
int16_t	Json_getValue (Json_Handle objHandle, const char *pKey, void *pValue, uint16_t *maxValueSize)
	This function retrieves value from json. More...
int16_t	Json_setValue (Json_Handle objHandle, const char *pKey, void *pValue, uint16_t valueSize)
	Sets the value for the provided key. More...
int16_t	Json_build (Json_Handle objHandle, char *pJsonText, uint16_t *maxTxtLen)
	This function builds the internal json into a text json. More...

Detailed Description

The JSON library provides APIs to parse and build JSON objects.

To access the JSON APIs, the application should include its header file as follows:

#include <ti/utils/json/json.h>

And add the following JSON library to the link line:

.../source/ti/utils/json/{toolchain}/{isa}/json_{profile}.a

Usage

This section provides a basic usage summary and a set of examples in the form of commented code fragments. Detailed descriptions of the JSON APIs are provided in subsequent sections.

Synopsis

// Import the json library
#include <ti/utils/json/json.h>

#define EXAMPLE_JSONBUF     \
"{"                         \
    "\"name\": \"John\","   \
    "\"age\": 32,"          \
    "\"job\": \"Plumber\""  \
"}"

// Define a template that captures the structure of the JSON to be created or parsed
#define JSON_TEMPLATE   \
"{"                     \
    "\"name\": string," \
    "\"age\": int32,"   \
    "\"job\": string"   \
"}"

// Parse the template into memory
Json_createTemplate(&templateHandle, JSON_TEMPLATE, strlen(JSON_TEMPLATE));

// Allocate memory needed for an object matching the generated template
Json_createObject(&objectHandle, templateHandle, 0);

// Parse JSON data into memory
Json_parse(objectHandle, EXAMPLE_JSONBUF, strlen(EXAMPLE_JSONBUF));

// Set values within the JSON object
Json_setValue(objectHandle, "\"name\"", "Bart", strlen("Bart"));

// Get values from within the JSON object
Json_getValue(objectHandle, "\"age\"", outputBuffer, &bufsize);

// Transform the JSON object into a string
Json_build(objectHandle, outputBuffer, &bufsize);

// Destroy the template and free its memory
Json_destroyTemplate(templateHandle);

// Destroy the JSON object and free its memory
Json_destroyObject(objectHandle);

Examples

• Creating JSON Objects
• Parsing JSON Objects
• Editing JSON Objects

The steps of creating a template and allocating memory for a JSON object through Json_createTemplate() and Json_createObject() are required for interacting with JSON objects. The template is what the library uses to know how to parse the JSON it encounters and to format the JSON string it ultimately builds through Json_build().

Creating JSON Objects: The following example demonstrates how to create a JSON object and output it as a string.

#include <ti/utils/json/json.h>

// The template is needed to specify the structure of the json object - its
// field names and types
#define EXAMPLE_TEMPLATE    \
"{"                         \
    "\"name\": string,"     \
    "\"age\": int32,"       \
    "\"job\": string,"      \
    "\"citizen\": boolean"  \
"}"

void mainThread() {
    Json_Handle templateHandle;
    Json_Handle objectHandle;
    bufsize     = 256;
    char        outputBuffer[bufsize];

    // The name must be quoted to access the corresponding JSON field
    char        *fieldName  = "\"age\"";
    int32_t     ageVal      = 42;
    bool        citizenship = true;

    // Create an internal representation of the template for the library's use
    Json_createTemplate(&templateHandle, EXAMPLE_TEMPLATE,
                        strlen(EXAMPLE_TEMPLATE));

    // Allocate memory needed for an object matching the generated template
    Json_createObject(&objectHandle, templateHandle, 0);

    // To fill in the object with actual data, call Json_setValue
    Json_setValue(objectHandle, fieldName, &ageVal, sizeof(ageVal));

    fieldName = "\"citizen\"";
    Json_setValue(objectHandle, fieldName, &citizenship, sizeof(uint16_t));

    // Output data from the JSON objectHandle into the outputBuffer
    Json_build(objectHandle, outputBuffer, &bufsize);
    // Any fields not set will not be part of the output
}

Parsing JSON Objects: The following example demonstrates how to parse a JSON string into memory as a JSON object.

#include <ti/utils/json/json.h>

#define EXAMPLE_JSONBUF     \
"{"                         \
    "\"name\": \"John\","   \
    "\"age\": 32,"          \
    "\"job\": \"Plumber\"," \
    "\"citizen\": true"     \
"}"

// The template is needed to specify the structure of the json object
#define EXAMPLE_TEMPLATE    \
"{"                         \
    "\"name\": string,"     \
    "\"age\": int32,"       \
    "\"job\": string,"      \
    "\"citizen\": boolean"  \
"}"

void mainThread() {
    Json_Handle templateHandle;
    Json_Handle objectHandle;
    uint16_t    bufsize = 32;
    char        outputBuffer[bufsize];
    char        *fieldName = "\"job\"";
    bool        boolBuffer;
    uint16_t    boolBufSize = sizeof(uint16_t);

    // Create an internal representation of the template for the library's use
    Json_createTemplate(&templateHandle, EXAMPLE_TEMPLATE,
                        strlen(EXAMPLE_TEMPLATE));

    // Allocate memory needed for an object matching the generated template
    Json_createObject(&objectHandle, templateHandle, 0);

    // Parse the JSON and fill in the object
    Json_parse(objectHandle, EXAMPLE_JSONBUF, strlen(EXAMPLE_JSONBUF));

    // Retrieve a value from the parsed json
    Json_getValue(objectHandle, fieldName, outputBuffer, &bufsize);

    fieldName = "\"citizen\"";
    Json_getValue(objectHandle, fieldName, &boolBuffer, &boolBufSize);
}

Editing JSON Objects: The following example demonstrates parsing a string containing JSON, editing its values, and outputting the updated object.

#include <ti/utils/json/json.h>

// The template is needed to specify the structure of the json object
#define EXAMPLE_TEMPLATE    \
"{"                         \
    "\"name\": string,"     \
    "\"age\": int32,"       \
    "\"job\": string"       \
"}"

#define EXAMPLE_JSONBUF     \
"{"                         \
    "\"name\": \"John\","   \
    "\"age\": 32,"          \
    "\"job\": \"Plumber\""  \
"}"

void mainThread() {
    Json_Handle templateHandle;
    Json_Handle objectHandle;
    uint16_t    bufsize = 256;
    char        outputBuffer[bufsize];

    // Create an internal representation of the template for the library's use
    Json_createTemplate(&templateHandle, EXAMPLE_TEMPLATE,
                        strlen(EXAMPLE_TEMPLATE));

    // Allocate memory needed for an object matching the generated template
    Json_createObject(&objectHandle, templateHandle, 0);

    // Parse the JSON
    Json_parse(objectHandle, EXAMPLE_JSONBUF, strlen(EXAMPLE_JSONBUF));

    // Set a value in the JSON object
    Json_setValue(objectHandle, "\"job\"", "Contractor", strlen("Contractor"));
    Json_setValue(objectHandle, "\"name\"", "John Sr.", strlen("John Sr."));

    // Output data from the JSON objectHandle into the outputBuffer
    Json_build(objectHandle, outputBuffer, &bufsize);
}

When the JSON objects are no longer needed Json_destroyObject and Json_destroyTemplate should be called:

void snippet() {
    Json_createTemplate(&templateHandle, EXAMPLE_TEMPLATE,
                        strlen(EXAMPLE_TEMPLATE));

    Json_createObject(&objectHandle, templateHandle, 0);

    ...

    Json_destroyObject(objectHandle);

    Json_destroyTemplate(templateHandle);
}

Remarks

Floating point values are not parsed correctly and should not be used. This will be fixed in a future release and is tracked by TIUTILS-8.

---

Macro Definition Documentation

JSON_DEFAULT_SIZE

#define JSON_DEFAULT_SIZE   (1024u)

Typedef Documentation

Json_Handle

typedef size_t Json_Handle

json_rc_T

typedef enum json_rc_TAG json_rc_T

Enumeration Type Documentation

json_rc_TAG

enum json_rc_TAG

Enumerator
JSON_RC__OK
JSON_RC__RECOVERED__IGNORED_UNKNOWN_VALUE
JSON_RC__RECOVERED__NESTING_EXCEEDED__IGNORING_LEAVES
JSON_RC__RECOVERED__PARSING_FAILURE
JSON_RC__RECOVERED__INVALID_VALUE
JSON_RC__RECOVERED__NUMBER_ACCURACY_LOSS
JSON_RC__RECOVERED__NUMBER_OVERFLOW
JSON_RC__RECOVERED__ILLEGAL_Q_VALUES
JSON_RC__RECOVERED__STRING_TRUNCATED
JSON_RC__REWIND_REQUIRED
JSON_RC__RECOVERABLE_ERROR__MINIMUM_VALUE
JSON_RC__PARSING_BUFFER_SIZE_EXCEEDED
JSON_RC__PARSING_FAILURE
JSON_RC__PARSING_FAILURE__INCOMPLETE_STRING
JSON_RC__NO_HASH_FOUND
JSON_RC__BUILDING_UNKNOWN_ATOM
JSON_RC__BUILDING_BUFFER_SIZE_EXCEEDED
JSON_RC__BUILDING_PARSED_DATA_EXHAUSTED
JSON_RC__WRONG_VALUE_SIZE_FOR_TYPE
JSON_RC__VALUE_NOT_AN_ARRAY
JSON_RC__INDEX_FAR_BEYOND_ARRAY_END
JSON_RC__PARSING_BUFFER_SIZE_WOULD_HAVE_EXCEEDED
JSON_RC__NOT_SUPPORTED
JSON_RC__NOT_FOUND
JSON_RC__VALUE_IS_NULL
JSON_RC__VALUE_NOT_VALID
JSON_RC__NESTING_EXCEEDED
JSON_RC__MEMORY_ALLOCATION_ERROR
JSON_RC__INVALID_TEMPLATE_HANDLE
JSON_RC__INVALID_OBJECT_HANDLE
JSON_RC__UNEXPECTED_ERROR

Function Documentation

Json_createTemplate()

int16_t Json_createTemplate	(	Json_Handle *	templateHandle,
		const char *	templateString,
		uint16_t	templateStringLen
	)

This function creates internal template from the template text.

Parameters

[out]	templateHandle	template handle
[in]	templateString	json template text
[in]	templateStringLen	json template text length

Remarks

The user must free the created template using Json_destroyTemplate().

Returns

Success: JSON_RC__OK

Failure: negative error code

Example

uint16_t ret;
Json_Handle templateHandle1;
char *templatestr = "{"
        "\"name\":string,"
        "\"age\":int32,"
        "\"car models\":[string,string,string]}";

ret = Json_createTemplate(&templateHandle1, templatestr,
        strlen(templatestr));

See also

Json_destroyTemplate()

Json_destroyTemplate()

int16_t Json_destroyTemplate

(

Json_Handle

templateHandle

)

This function frees the internal template memory.

Parameters

[in]

templateHandle

template handle

Remarks

After destroying the template, the Json object will have a NULL pointer in it (see the object struct - JSON_templateInternal *jsonTemplate). It is recommended to first destroy the Json object and then the template.

Returns

Success: JSON_RC__OK

Failure: negative error code

Example

uint16_t ret;

ret  = Json_destroyTemplate(templateHandle1);

See also

Json_createTemplate()

Json_createObject()

int16_t Json_createObject	(	Json_Handle *	objHandle,
		Json_Handle	templateHandle,
		uint16_t	maxObjectSize
	)

This function creates an empty Json object.

Parameters

[out]	objHandle	json object handle
[in]	templateHandle	json template handle
[in]	maxObjectSize	json object max size or 0 for JSON_DEFAULT_SIZE

Returns

Success: JSON_RC__OK

Failure: negative error code

Remarks

The user must free the created object using Json_destroyObject()

The user must create a template before its json object

Example

uint16_t ret;
Json_Handle h;

ret = Json_createObject(&h, templateHandle, 1024);

See also

Json_createTemplate()

Json_destroyObject()

Json_destroyObject()

int16_t Json_destroyObject

(

Json_Handle

objHandle

)

Free the internal json memory.

Parameters

[in]

objHandle

json handle, created by Json_createObject()

Returns

Success: JSON_RC__OK

Failure: negative error code

Example

uint16_t ret;

ret = Json_destroyObject(h);

See also

Json_createObject()

Json_parse()

int16_t Json_parse	(	Json_Handle	objHandle,
		char *	jsonText,
		uint16_t	jsonTextLen
	)

This function converts the json text into internal representation.

Parameters

[in]	objHandle	json object handle
[in]	jsonText	pointer to the json text
[in]	jsonTextLen	json text size

Returns

Success: JSON_RC__OK

Failure: negative error code

Example

uint16_t ret;
char *jsonBuf = "{\"name\":\"John\","
        "\"age\":30,"
        "\"car models\":[\"toyota\",\"fiat\",\"volvo\"]}";

ret = Json_parse(h, jsonBuf, strlen(jsonBuf));

See also

Json_createObject()

Json_getArrayMembersCount()

int16_t Json_getArrayMembersCount	(	Json_Handle	objHandle,
		const char *	pKey
	)

Retrieve the number of array elements in the provided key.

Parameters

[in]	objHandle	json object handle
[in]	pKey	pointer to the key of the requested array

Remarks

pKey must be NULL terminated.

Returns

Success: JSON_RC__OK

Failure: negative error code

Example

uint16_t ret;
uint16_t arrayCount;
char *jsonBuf = "{"
        "\"name\":\"John\","
        "\"age\":30,"
        "\"car models\":[\"toyota\",\"fiat\",\"volvo\"]};
char *key =  "\"car models\"";

ret = Json_parse(h, jsonBuf, strlen(jsonBuf));

arrayCount = Json_getArrayMembersCount(h, key);

See also

Json_parse()

Json_getValue()

int16_t Json_getValue	(	Json_Handle	objHandle,
		const char *	pKey,
		void *	pValue,
		uint16_t *	maxValueSize
	)

This function retrieves value from json.

Parameters

[in]	objHandle	json object handle
[in]	pKey	pointer to the key of the requested value
[out]	pValue	[optional] pointer to the retrieved value
[in,out]	maxValueSize	input, number of bytes pValue can hold (if pValue is not NULL). output, number of bytes required to hold requested value.

Remarks

pKey must be NULL terminated

if pValue is NULL, maxValueSize will return the requested value size

Returns

Success: JSON_RC__OK

Failure: negative error code

Example

uint16_t ret;
char *jsonBuf = "{"
        "\"name\":\"John\","
        "\"age\":30,"
        "\"car models\":[\"toyota\",\"fiat\",\"volvo\"]};
char *key =  "\"name\"";
char   value[5];
uint16_t valueSize = 5;

ret = Json_parse(h, jsonBuf, strlen(jsonBuf));

ret = Json_getValue(h, key, value, &valueSize);

See also

Json_parse()

Json_setValue()

int16_t Json_setValue	(	Json_Handle	objHandle,
		const char *	pKey,
		void *	pValue,
		uint16_t	valueSize
	)

Sets the value for the provided key.

Parameters

[in]	objHandle	json object handle
[in]	pKey	pointer to the key of the value to be changed
[in]	pValue	pointer to the value to be set
[in]	valueSize	size of the value

Remarks

pKey must be NULL terminated

Returns

Success: JSON_RC__OK

Failure: negative error code

Example

uint16_t ret;
char *jsonBuf = "{"
        "\"name\":\"John\","
        "\"age\":30,"
        "\"car models\":[\"toyota\",\"fiat\",\"volvo\"]};
char *key =  "\"age\"";
uint16_r value = 29;
uint16_t valueSize = sizeof(value);

ret = Json_parse(h, jsonBuf, strlen(jsonBuf));

ret = Json_setValue(h, key, value, valueSize);

Remarks

For boolean types, valueSize should be set to 2 a.k.a. sizeof(uint16_t). For all other integral types, calling sizeof() on the respective type is sufficient.

See also

Json_parse()

Json_build()

int16_t Json_build	(	Json_Handle	objHandle,
		char *	pJsonText,
		uint16_t *	maxTxtLen
	)

This function builds the internal json into a text json.

Parameters

[in]	objHandle	json object handle
[out]	pJsonText	pointer to buffer to output the json text
[in,out]	maxTxtLen	input, maximum buffer size. output, used buffer size.

Returns

Success: JSON_RC__OK

Failure: negative error code

Example

uint16_t ret;
char *key =  "\"age\"";
uint16_r value = 29;
uint16_t valueSize = sizeof(value);
char builtBuff[100];
uint16_t builtBuffSize = 100;
ret = Json_setValue(h, key, value, valueSize);

ret = Json_build(h, builtBuf, &builtBuffSize);

See also

Json_parse()

Json_setValue()