TI Utilities API  1.10.00.09
Macros | Typedefs | Enumerations | Functions
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:

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
#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

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.

// 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.

#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.

// 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

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]templateHandletemplate handle
[in]templateStringjson template text
[in]templateStringLenjson 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]templateHandletemplate 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]objHandlejson object handle
[in]templateHandlejson template handle
[in]maxObjectSizejson 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;
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]objHandlejson handle, created by Json_createObject()
Returns
Success: JSON_RC__OK
Failure: negative error code
Example
uint16_t ret;
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]objHandlejson object handle
[in]jsonTextpointer to the json text
[in]jsonTextLenjson 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]objHandlejson object handle
[in]pKeypointer 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]objHandlejson object handle
[in]pKeypointer to the key of the requested value
[out]pValue[optional] pointer to the retrieved value
[in,out]maxValueSizeinput, 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]objHandlejson object handle
[in]pKeypointer to the key of the value to be changed
[in]pValuepointer to the value to be set
[in]valueSizesize 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]objHandlejson object handle
[out]pJsonTextpointer to buffer to output the json text
[in,out]maxTxtLeninput, 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()
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale