core_json.h File Reference

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

#include <stdbool.h>
#include <stddef.h>

Go to the source code of this file.

Data Structures
struct	JSONPair_t
	Structure to represent a key-value pair. More...

Macros
#define	JSON_Search(buf, max, query, queryLength, outValue, outValueLength)    JSON_SearchT( buf, max, query, queryLength, outValue, outValueLength, NULL )
	Find a key or array index in a JSON document and output the pointer outValue to its value. More...
#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...
enum	JSONTypes_t {   JSONInvalid = 0 , JSONString , JSONNumber , JSONTrue ,   JSONFalse , JSONNull , JSONObject , JSONArray }
	Value types from the JSON standard. 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_SearchT (char *buf, size_t max, const char *query, size_t queryLength, char **outValue, size_t *outValueLength, JSONTypes_t *outType)
	Same as JSON_Search(), but also outputs a type for the value found. More...
JSONStatus_t	JSON_SearchConst (const char *buf, size_t max, const char *query, size_t queryLength, const char **outValue, size_t *outValueLength, JSONTypes_t *outType)
	Same as JSON_SearchT(), but with const qualified buf and outValue arguments. More...
JSONStatus_t	JSON_Iterate (const char *buf, size_t max, size_t *start, size_t *next, JSONPair_t *outPair)
	Output the next key-value pair or value from a collection. More...

Detailed Description

Include this header file to use coreJSON in your application.

Macro Definition Documentation

JSON_Search

#define JSON_Search	(		buf,
			max,
			query,
			queryLength,
			outValue,
			outValueLength
	)		JSON_SearchT( buf, max, query, queryLength, outValue, outValueLength, NULL )

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

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_SearchT()

JSONStatus_t JSON_SearchT	(	char *	buf,
		size_t	max,
		const char *	query,
		size_t	queryLength,
		char **	outValue,
		size_t *	outValueLength,
		JSONTypes_t *	outType
	)

Same as JSON_Search(), but also outputs a type for the value found.

See JSON_Search for documentation of common behavior.

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.
[out]	outType	An enum indicating the JSON-specific type of the value.

See core_json.h for docs.

JSON_SearchConst()

JSONStatus_t JSON_SearchConst	(	const char *	buf,
		size_t	max,
		const char *	query,
		size_t	queryLength,
		const char **	outValue,
		size_t *	outValueLength,
		JSONTypes_t *	outType
	)

Same as JSON_SearchT(), but with const qualified buf and outValue arguments.

See JSON_Search for documentation of common behavior.

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.
[out]	outType	An enum indicating the JSON-specific type of the value.

See core_json.h for docs.

JSON_Iterate()

JSONStatus_t JSON_Iterate	(	const char *	buf,
		size_t	max,
		size_t *	start,
		size_t *	next,
		JSONPair_t *	outPair
	)

Output the next key-value pair or value from a collection.

This function may be used in a loop to output each key-value pair from an object, or each value from an array. For the first invocation, the integers pointed to by start and next should be initialized to 0. These will be updated by the function. If another key-value pair or value is present, the output structure is populated and JSONSuccess is returned; otherwise the structure is unchanged and JSONNotFound is returned.

Parameters

[in]	buf	The buffer to search.
[in]	max	size of the buffer.
[in,out]	start	The index at which the collection begins.
[in,out]	next	The index at which to seek the next value.
[out]	outPair	A pointer to receive the next key-value pair.

Note

This function expects a valid JSON document; run JSON_Validate() first.

For an object, the outPair structure will reference a key and its value. For an array, only the value will be referenced (i.e., outPair.key will be NULL).

Returns

JSONSuccess if a value is output; JSONIllegalDocument if the buffer does not contain a collection; JSONNotFound if there are no further values in the collection.

Example

// Variables used in this example.
static char * json_types[] =
{
    "invalid",
    "string",
    "number",
    "true",
    "false",
    "null",
    "object",
    "array"
};
 
void show( const char * json,
           size_t length )
{
    size_t start = 0, next = 0;
    JSONPair_t pair = { 0 };
    JSONStatus_t result;
 
    result = JSON_Validate( json, length );
    if( result == JSONSuccess )
    {
        result = JSON_Iterate( json, length, &start, &next, &pair );
    }
 
    while( result == JSONSuccess )
    {
        if( pair.key != NULL )
        {
            printf( "key: %.*s\t", ( int ) pair.keyLength, pair.key );
        }
 
        printf( "value: (%s) %.*s\n", json_types[ pair.jsonType ],
                ( int ) pair.valueLength, pair.value );
 
        result = JSON_Iterate( json, length, &start, &next, &pair );
    }
}

See core_json.h for docs.