TI Utilities API  1.00.00.05
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.

Library Usage

To use 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
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]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;
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]objHandlejson 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]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);
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