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.

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 *queryKey, size_t queryKeyLength, char separator, char **outValue, size_t *outValueLength)
	Find a key in a JSON object 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 *	queryKey,
		size_t	queryKeyLength,
		char	separator,
		char **	outValue,
		size_t *	outValueLength
	)

Find a key in a JSON object and output the pointer outValue to its value.

The JSON document must contain an object (e.g., {"key":"value"}). Any value may also be an object and so forth to a maximum depth. A search may descend through nested objects when the queryKey contains matching key strings joined by a separator.

For example, if buf 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 (given separator is specified as '.').

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]	queryKey	The key to search for.
[in]	queryKeyLength	Length of the key.
[in]	separator	A character between a key and a sub-key in queryKey.
[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 queryKey is found and the value output; JSONNullParameter if any pointer parameters are NULL; JSONBadParameter if the queryKey is empty, or any subpart is empty, or max is 0; JSONIllegalDocument if the buffer contents are NOT valid JSON; JSONMaxDepthExceeded if object and array nesting exceeds a threshold; JSONNotFound if the queryKey is NOT found.

Example

// Variables used in this example.
JSONStatus_t result;
char buffer[] = "{\"foo\":\"abc\",\"bar\":{\"foo\":\"xyz\"}}";
size_t bufferLength = sizeof( buffer ) - 1;
char queryKey[] = "bar.foo";
size_t queryKeyLength = sizeof( queryKey ) - 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, queryKey, queryKeyLength, '.',
                          &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", queryKey, value );
    // Restore the original character.
    value[ valueLength ] = save;
}

See core_json.h for docs.

Handle a nested search by iterating over the parts of the queryKey.