coreJSON  v3.0.2
Parser library for the ECMA-404 JSON standard

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

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

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

[in]bufThe buffer to search.
[in]maxsize of the buffer.
[in]queryThe object keys and array indexes to search for.
[in]queryLengthLength of the key.
[out]outValueA pointer to receive the address of the value found.
[out]outValueLengthA pointer to receive the length of the value found.
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().
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.


// Variables used in this example.
JSONStatus_t result;
char buffer[] = "{\"foo\":\"abc\",\"bar\":{\"foo\":\"xyz\"}}";
size_t bufferLength = sizeof( buffer ) - 1;
char query[] = "";
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: -> xyz" will be printed.
printf( "Found: %s -> %s\n", query, value );
// Restore the original character.
value[ valueLength ] = save;
The maximum index value is ~2 billion ( 2^31 - 9 ).
@ JSONSuccess
JSON document is valid and complete.
Definition: core_json.h:47
#define JSON_Search(buf, max, query, queryLength, outValue, outValueLength)
Find a key or array index in a JSON document and output the pointer outValue to its value.
Definition: core_json.h:170
JSONStatus_t JSON_Validate(const char *buf, size_t max)
Parse a buffer to determine if it contains a valid JSON document.
Definition: core_json.c:1123
Return codes from coreJSON library functions.
Definition: core_json.h:45