core_json.h File Reference

Include this header file to use coreJSON in your application. More...

#include <stddef.h>

Go to the source code of this file.

Macros
#define	MAX_INDEX_VALUE   ( 0x7FFFFFF7 ) /* 2^31 - 9 */
	The largest value usable as an array index in a query for JSON_Search(), ~2 billion.

Enumerations
enum	JSONStatus_t {   JSONPartial = 0 , JSONSuccess , JSONIllegalDocument , JSONMaxDepthExceeded ,   JSONNotFound , JSONNullParameter , JSONBadParameter }
	Return codes from coreJSON library functions. More...

Functions
JSONStatus_t	JSON_Validate (const char *buf, size_t max)
	Parse a buffer to determine if it contains a valid JSON document. More...
JSONStatus_t	JSON_Search (char *buf, size_t max, const char *query, size_t queryLength, char **outValue, size_t *outValueLength)
	Find a key or array index in a JSON document and output the pointer outValue to its value. More...

Detailed Description

Include this header file to use coreJSON in your application.

Function Documentation

JSON_Validate()

JSONStatus_t JSON_Validate	(	const char *	buf,
		size_t	max
	)

Parse a buffer to determine if it contains a valid JSON document.

Parameters

[in]	buf	The buffer to parse.
[in]	max	The size of the buffer.

Note

The maximum nesting depth may be specified by defining the macro JSON_MAX_DEPTH. The default is 32 of sizeof(char).

By default, a valid JSON document may contain a single element (e.g., string, boolean, number). To require that a valid document contain an object or array, define JSON_VALIDATE_COLLECTIONS_ONLY.

Returns

JSONSuccess if the buffer contents are valid JSON; JSONNullParameter if buf is NULL; JSONBadParameter if max is 0; JSONIllegalDocument if the buffer contents are NOT valid JSON; JSONMaxDepthExceeded if object and array nesting exceeds a threshold; JSONPartial if the buffer contents are potentially valid but incomplete.

Example

// Variables used in this example.
JSONStatus_t result;
char buffer[] = "{\"foo\":\"abc\",\"bar\":{\"foo\":\"xyz\"}}";
size_t bufferLength = sizeof( buffer ) - 1;
 
result = JSON_Validate( buffer, bufferLength );
 
// JSON document is valid.
assert( result == JSONSuccess );

See core_json.h for docs.

Verify that the entire buffer contains exactly one scalar or collection within optional whitespace.

JSON_Search()

JSONStatus_t JSON_Search	(	char *	buf,
		size_t	max,
		const char *	query,
		size_t	queryLength,
		char **	outValue,
		size_t *	outValueLength
	)

Find a key or array index in a JSON document and output the pointer outValue to its value.

Any value may also be an object or an array to a maximum depth. A search may descend through nested objects or arrays when the query contains matching key strings or array indexes joined by a separator.

For example, if the provided buffer contains {"foo":"abc","bar":{"foo":"xyz"}}, then a search for 'foo' would output abc, 'bar' would output {"foo":"xyz"}, and a search for 'bar.foo' would output xyz.

If the provided buffer contains [123,456,{"foo":"abc","bar":[88,99]}], then a search for '[1]' would output 456, '[2].foo' would output abc, and '[2].bar[0]' would output 88.

On success, the pointer outValue points to a location in buf. No null termination is done for the value. For valid JSON it is safe to place a null character at the end of the value, so long as the character replaced is put back before running another search.

Parameters

[in]	buf	The buffer to search.
[in]	max	size of the buffer.
[in]	query	The object keys and array indexes to search for.
[in]	queryLength	Length of the key.
[out]	outValue	A pointer to receive the address of the value found.
[out]	outValueLength	A pointer to receive the length of the value found.

Note

The maximum nesting depth may be specified by defining the macro JSON_MAX_DEPTH. The default is 32 of sizeof(char).

JSON_Search() performs validation, but stops upon finding a matching key and its value. To validate the entire JSON document, use JSON_Validate().

Returns

JSONSuccess if the query is matched and the value output; JSONNullParameter if any pointer parameters are NULL; JSONBadParameter if the query is empty, or the portion after a separator is empty, or max is 0, or an index is too large to convert to a signed 32-bit integer; JSONNotFound if the query has no match.

Example

// Variables used in this example.
JSONStatus_t result;
char buffer[] = "{\"foo\":\"abc\",\"bar\":{\"foo\":\"xyz\"}}";
size_t bufferLength = sizeof( buffer ) - 1;
char query[] = "bar.foo";
size_t queryLength = sizeof( query ) - 1;
char * value;
size_t valueLength;
 
// Calling JSON_Validate() is not necessary if the document is guaranteed to be valid.
result = JSON_Validate( buffer, bufferLength );
 
if( result == JSONSuccess )
{
    result = JSON_Search( buffer, bufferLength, query, queryLength,
                          &value, &valueLength );
}
 
if( result == JSONSuccess )
{
    // The pointer "value" will point to a location in the "buffer".
    char save = value[ valueLength ];
    // After saving the character, set it to a null byte for printing.
    value[ valueLength ] = '\0';
    // "Found: bar.foo -> xyz" will be printed.
    printf( "Found: %s -> %s\n", query, value );
    // Restore the original character.
    value[ valueLength ] = save;
}

Note

The maximum index value is ~2 billion ( 2^31 - 9 ).

See core_json.h for docs.