wsjson.h File Reference

#include "ws_symbol_export.h"
#include <inttypes.h>
#include <stdbool.h>
#include "jsmn.h"

Go to the source code of this file.

Functions
WS_DLL_PUBLIC bool	json_validate (const uint8_t *buf, const size_t len)
WS_DLL_PUBLIC int	json_parse (const char *buf, jsmntok_t *tokens, unsigned int max_tokens)
WS_DLL_PUBLIC int	json_parse_len (const char *buf, size_t len, jsmntok_t *tokens, unsigned int max_tokens)
WS_DLL_PUBLIC jsmntok_t *	json_get_object (const char *buf, jsmntok_t *parent, const char *name)
WS_DLL_PUBLIC jsmntok_t *	json_get_array (const char *buf, jsmntok_t *parent, const char *name)
WS_DLL_PUBLIC int	json_get_array_len (jsmntok_t *array)
WS_DLL_PUBLIC jsmntok_t *	json_get_array_index (jsmntok_t *parent, int idx)
WS_DLL_PUBLIC jsmntok_t *	json_get_next_object (jsmntok_t *cur)
WS_DLL_PUBLIC char *	json_get_string (char *buf, jsmntok_t *parent, const char *name)
WS_DLL_PUBLIC bool	json_get_double (char *buf, jsmntok_t *parent, const char *name, double *val)
WS_DLL_PUBLIC bool	json_get_int (char *buf, jsmntok_t *parent, const char *name, int64_t *val)
WS_DLL_PUBLIC bool	json_get_boolean (char *buf, jsmntok_t *parent, const char *name, bool *val)
WS_DLL_PUBLIC bool	json_decode_string_inplace (char *text)

Detailed Description

JSON parsing functions.

Copyright 2016, Dario Lombardo

Wireshark - Network traffic analyzer By Gerald Combs geral.nosp@m.d@wi.nosp@m.resha.nosp@m.rk.o.nosp@m.rg Copyright 1998 Gerald Combs

SPDX-License-Identifier: GPL-2.0-or-later

Function Documentation

json_decode_string_inplace()

WS_DLL_PUBLIC bool json_decode_string_inplace

(

char *

text

)

Decode the contents of a JSON string value by overwriting the input data.

Parameters

text	- JSON string to decode.

Returns

true on success and false if invalid characters were encountered.

json_get_array()

WS_DLL_PUBLIC jsmntok_t * json_get_array	(	const char *	buf,
		jsmntok_t *	parent,
		const char *	name
	)

Get the pointer to an array belonging to the parent object and named as the name variable.

Parameters

buf	- A buffer containing JSON, not necessarily null-terminated.
parent	- JSON object to search within for the name.
name	- The name to search the parent object for.

Returns

Pointer to the array named name within the parent object, or NULL if not found.

json_get_array_index()

WS_DLL_PUBLIC jsmntok_t * json_get_array_index	(	jsmntok_t *	parent,
		int	idx
	)

Get the pointer to idx element of an array.

Note

This requires iterating through the parent's elements and is inefficient for iterating over an array's elements. If accessing array objects in a loop, instead use json_get_next_object.

Parameters

parent	- JSON array.
idx	- index of element.

Returns

Pointer to parent array's element at position idx or NULL if not found.

json_get_array_len()

WS_DLL_PUBLIC int json_get_array_len

(

jsmntok_t *

array

)

Get the number of elements of an array.

Parameters

array

- JSON array.

Returns

The number of elements in an array or -1 if the JSON object is not an array.

json_get_boolean()

WS_DLL_PUBLIC bool json_get_boolean	(	char *	buf,
		jsmntok_t *	parent,
		const char *	name,
		bool *	val
	)

Get the value of a boolean belonging to the parent object and named as the name variable.

Parameters

buf	- A buffer containing JSON, not necessarily null-terminated.
parent	- JSON object to search within for the name.
name	- The name to search the parent object for.
val	- Location to store the retrieved value.

Returns

false if not found.

Note

This modifies the input buffer.

json_get_double()

WS_DLL_PUBLIC bool json_get_double	(	char *	buf,
		jsmntok_t *	parent,
		const char *	name,
		double *	val
	)

Get the value of a number object belonging to the parent object and named as the name variable.

Parameters

buf	- A buffer containing JSON, not necessarily null-terminated.
parent	- JSON object to search within for the name.
name	- The name to search the parent object for.
val	- Location to store the retrieved value.

Returns

false if not found.

Note

This modifies the input buffer. Scientific notation not supported yet.

json_get_int()

WS_DLL_PUBLIC bool json_get_int	(	char *	buf,
		jsmntok_t *	parent,
		const char *	name,
		int64_t *	val
	)

Get the value of a number object belonging to the parent object and named as the name variable.

Parameters

buf	- A buffer containing JSON, not necessarily null-terminated.
parent	- JSON object to search within for the name.
name	- The name to search the parent object for.
val	- Location to store the retrieved value.

Returns

false if not found.

Note

This modifies the input buffer.

json_get_next_object()

WS_DLL_PUBLIC jsmntok_t * json_get_next_object

(

jsmntok_t *

cur

)

Get the pointer to the next JSON element which is a sibling of cur.

This is used for efficiently iterating over elements of a JSON array. For example:

// Given a jsmntok_t* `array_token` for the start of the array (e.g., from `json_get_array`)
const int count = json_get_array_len(array_token);
jsmntok_t* element = json_get_array_index(array_token, 0);
for (int i = 0; i < count; i++, element = json_get_next_object(element)) {
  ... // Do something with `element`
}

Note

This does not perform bounds checking and so can go out of bounds! Be sure to track how many times this is called.

Parameters

cur	- JSON array element.

Returns

Pointer to next sibling element.

json_get_object()

WS_DLL_PUBLIC jsmntok_t * json_get_object	(	const char *	buf,
		jsmntok_t *	parent,
		const char *	name
	)

Get the pointer to an object belonging to the parent object and named as the name variable.

Parameters

buf	- A buffer containing JSON, not necessarily null-terminated.
parent	- JSON object to search within for the name.
name	- The name to search the parent object for.

Returns

Pointer to the object named name within the parent object, or NULL if not found.

json_get_string()

WS_DLL_PUBLIC char * json_get_string	(	char *	buf,
		jsmntok_t *	parent,
		const char *	name
	)

Get the unescaped value of a string object belonging to the parent object and named as the name variable.

Parameters

buf	- A buffer containing JSON, not necessarily null-terminated.
parent	- JSON object to search within for the name.
name	- The name to search the parent object for.

Returns

Pointer to a string belonging to the parent object and named as the name variable or NULL if not found.

Note

This modifies the input buffer.

json_parse()

WS_DLL_PUBLIC int json_parse	(	const char *	buf,
		jsmntok_t *	tokens,
		unsigned int	max_tokens
	)

Parse a JSON string and write the token's addresses into the tokens array.

Parameters

buf	- A null-terminated string containing JSON.
tokens	- An array for storing the parsed tokens. Can be NULL, to validate only.
max_tokens	- The length of tokens. Ignored if tokens is NULL.

Returns

The number of tokens needed, or a jsmnerr (which are negative).

Note

This calls strlen() and requires that buf be a null-terminated string. This can be called with tokens set to NULL to determine the number of tokens necessary.

json_parse_len()

WS_DLL_PUBLIC int json_parse_len	(	const char *	buf,
		size_t	len,
		jsmntok_t *	tokens,
		unsigned int	max_tokens
	)

Parse a JSON buffer and write the token's addresses into the tokens array.

Parameters

buf	- A buffer containing JSON, not necessarily null-terminated.
len	- The length of the JSON data in the buffer.
tokens	- An array for storing the parsed tokens. Can be NULL, to validate only.
max_tokens	- The length of tokens. Ignored if tokens is NULL.

Returns

The number of tokens needed, or a jsmnerr (which are negative).

Note

This still stops parsing after the first '\0' byte, if any. It's useful if a buffer is not null-terminated or if the length is already known. This can be called with tokens set to NULL to determine the number of tokens necessary.

json_validate()

WS_DLL_PUBLIC bool json_validate	(	const uint8_t *	buf,
		const size_t	len
	)

Check if a buffer is valid JSON.

Parameters

buf	- A buffer containing JSON.
len	- The length of the JSON data in the buffer.

Returns

true if the JSON is valid.

Note

This requires that the buffer be complete valid JSON that requires no more than 1024 tokens. For larger objects, or to parse what may be an incomplete string, call json_parse[_len] and check the return value.