JSON

JSON parser. More...

Data Structures
struct	sol_json_path_scanner
	Scanner used to go through segments of a JSON Path. More...
struct	sol_json_scanner
	Structure to track a JSON document (or a portion of it) being parsed. More...
struct	sol_json_token
	Type describing a JSON token. More...

Macros
#define	SOL_JSON_PATH_FOREACH(scanner, key, status)
	Go through all segments of a JSON Path. More...
#define	SOL_JSON_SCANNER_ARRAY_LOOP(scanner_, token_, status_)
	Helper macro to iterate over the elements an array in a JSON document, ignoring the elements type. More...
#define	SOL_JSON_SCANNER_ARRAY_LOOP_NESTED(scanner_, token_, status_)
	Helper macro to iterate over the elements of a nested array in a JSON document, ignoring the elements type. More...
#define	SOL_JSON_SCANNER_ARRAY_LOOP_TYPE(scanner_, token_, element_type_, status_)
	Helper macro to iterate over the elements of an array in a JSON document. More...
#define	SOL_JSON_SCANNER_ARRAY_LOOP_TYPE_NESTED(scanner_, token_, element_type_, status_)
	Helper macro to iterate over the elements of a nested array in a JSON document. More...
#define	SOL_JSON_SCANNER_OBJECT_LOOP(scanner_, token_, key_, value_, status_)
	Helper macro to iterate over the elements of an object in a JSON document. More...
#define	SOL_JSON_SCANNER_OBJECT_LOOP_NESTED(scanner_, token_, key_, value_, status_)
	Helper macro to iterate over the elements of a nested object in a JSON document. More...
#define	SOL_JSON_TOKEN_STR_LITERAL_EQ(token_, str_)   sol_json_token_str_eq(token_, str_, sizeof(str_) - 1)
	Helper macro to check if the string pointed by token_ is equal to a string literal. More...

Typedefs
typedef struct sol_json_path_scanner	sol_json_path_scanner
	Scanner used to go through segments of a JSON Path. More...
typedef struct sol_json_scanner	sol_json_scanner
	Structure to track a JSON document (or a portion of it) being parsed. More...
typedef struct sol_json_token	sol_json_token
	Type describing a JSON token. More...

Enumerations
enum	sol_json_loop_status { SOL_JSON_LOOP_REASON_OK = 0, SOL_JSON_LOOP_REASON_INVALID }
	Return values used by the parser 'loop' macros. More...
enum	sol_json_type {   SOL_JSON_TYPE_UNKNOWN = 0, SOL_JSON_TYPE_OBJECT_START = '{', SOL_JSON_TYPE_OBJECT_END = '}', SOL_JSON_TYPE_ARRAY_START = '[',   SOL_JSON_TYPE_ARRAY_END = ']', SOL_JSON_TYPE_ELEMENT_SEP = ',', SOL_JSON_TYPE_PAIR_SEP = ':', SOL_JSON_TYPE_TRUE = 't',   SOL_JSON_TYPE_FALSE = 'f', SOL_JSON_TYPE_NULL = 'n', SOL_JSON_TYPE_STRING = '"', SOL_JSON_TYPE_NUMBER = '1' }
	Token type enumeration. More...

Functions
int	sol_json_array_get_at_index (struct sol_json_scanner *scanner, uint16_t i, struct sol_json_token *value)
	Get the element in position i in JSON Array contained in scanner. More...
size_t	sol_json_calculate_escaped_string_len (const char *str)
	Calculate the size in bytes of the escaped version of a string. More...
int	sol_json_double_to_str (const double value, struct sol_buffer *buf)
	Converts a double into a string suited for use in a JSON Document. More...
char *	sol_json_escape_string (const char *str, struct sol_buffer *buf)
	Escapes JSON special and control characters from the string content. More...
int	sol_json_get_value_by_path (struct sol_json_scanner *scanner, struct sol_str_slice path, struct sol_json_token *value)
	Get the element referenced by the JSON Path path in a JSON Object or Array. More...
bool	sol_json_is_valid_type (struct sol_json_scanner *scanner, enum sol_json_type start_type)
	Check if scanner content is pointing to a valid JSON element of type start_type. More...
int	sol_json_load_memdesc (const struct sol_json_token *token, const struct sol_memdesc *desc, void *memory)
	Loads the members of a memory from JSON according to its description. More...
static bool	sol_json_loop_iterate_array (struct sol_json_scanner *scanner, struct sol_json_token *token, enum sol_json_loop_status *reason, enum sol_json_type element_type)
	Function to help iterate over a JSON array. More...
static bool	sol_json_loop_iterate_generic (struct sol_json_scanner *scanner, struct sol_json_token *token, enum sol_json_type end_type, enum sol_json_loop_status *reason)
	Function to help iterate over a generic JSON sequence. More...
static enum sol_json_loop_status	sol_json_loop_iterate_init (struct sol_json_scanner *scanner, struct sol_json_token *token, enum sol_json_type start_type)
	Function to bootstrap an iteration over a JSON sequence. More...
static bool	sol_json_loop_iterate_object (struct sol_json_scanner *scanner, struct sol_json_token *token, struct sol_json_token *key, struct sol_json_token *value, enum sol_json_loop_status *reason)
	Function to help iterate over a JSON object. More...
static enum sol_json_type	sol_json_mem_get_type (const void *mem)
	Returns the type of the token pointed by mem. More...
int	sol_json_object_get_value_by_key (struct sol_json_scanner *scanner, const struct sol_str_slice key_slice, struct sol_json_token *value)
	Get the value of the JSON Object child element referenced by key_slice. More...
int32_t	sol_json_path_array_get_segment_index (struct sol_str_slice key)
	Get the integer index from a JSON Path array segment. More...
bool	sol_json_path_get_next_segment (struct sol_json_path_scanner *scanner, struct sol_str_slice *slice, enum sol_json_loop_status *status)
	Get next segment from JSON Path in scanner. More...
static bool	sol_json_path_is_array_key (struct sol_str_slice slice)
	Check if slice is a valid JSON Path array segment. More...
int	sol_json_path_scanner_init (struct sol_json_path_scanner *scanner, struct sol_str_slice path)
	Initialize a JSON Path scanner with path. More...
bool	sol_json_scanner_get_dict_pair (struct sol_json_scanner *scanner, struct sol_json_token *key, struct sol_json_token *value)
	Retrieve <key, value> pair currently pointed by scanner. More...
static size_t	sol_json_scanner_get_mem_offset (const struct sol_json_scanner *scanner, const void *mem)
	Returns the offset of mem in the data managed by scanner. More...
static size_t	sol_json_scanner_get_size_remaining (const struct sol_json_scanner *scanner)
	Returns the size of the JSON document that wasn't scanned yet. More...
static void	sol_json_scanner_init (struct sol_json_scanner *scanner, const void *mem, size_t size)
	Initializes a JSON scanner. More...
static void	sol_json_scanner_init_from_scanner (struct sol_json_scanner *scanner, const struct sol_json_scanner *other)
	Initializes a JSON scanner based on the information of a second scanner. More...
static void	sol_json_scanner_init_from_slice (struct sol_json_scanner *scanner, const struct sol_str_slice slice)
	Initialized a JSON scanner from a struct sol_str_slice. More...
static void	sol_json_scanner_init_from_token (struct sol_json_scanner *scanner, const struct sol_json_token *token)
	Initializes a JSON scanner based on the information of a JSON Token. More...
static void	sol_json_scanner_init_null (struct sol_json_scanner *scanner)
	Initializes a JSON scanner with empty information. More...
bool	sol_json_scanner_next (struct sol_json_scanner *scanner, struct sol_json_token *token)
	Advance the scanner to the next JSON token. More...
bool	sol_json_scanner_skip (struct sol_json_scanner *scanner, struct sol_json_token *token)
	Modifies scanner to point to token end, skipping over the token content. More...
int	sol_json_serialize_bool (struct sol_buffer *buffer, bool val)
	Inserts the string of the boolean value val in the end of the JSON document contained in buffer. More...
int	sol_json_serialize_double (struct sol_buffer *buffer, double val)
	Inserts the string of the double val in the end of the JSON document contained in buffer. More...
int	sol_json_serialize_int32 (struct sol_buffer *buffer, int32_t val)
	Inserts the string of the 32-bit integer val in the end of the JSON document contained in buffer. More...
int	sol_json_serialize_int64 (struct sol_buffer *buffer, int64_t val)
	Inserts the string of the 64-bit integer val in the end of the JSON document contained in buffer. More...
int	sol_json_serialize_memdesc (struct sol_buffer *buffer, const struct sol_memdesc *desc, const void *memory, bool detailed_structures)
	Appends the serialization of the given memory based on its description. More...
static int	sol_json_serialize_null (struct sol_buffer *buffer)
	Inserts the string "null" in the end of the JSON document contained in buffer. More...
int	sol_json_serialize_string (struct sol_buffer *buffer, const char *str)
	Inserts the string str in the end of the JSON document contained in buffer. More...
int	sol_json_serialize_uint32 (struct sol_buffer *buffer, uint32_t val)
	Inserts the string of the unsigned 32-bit integer val in the end of the JSON document contained in buffer. More...
int	sol_json_serialize_uint64 (struct sol_buffer *buffer, uint64_t val)
	Inserts the string of the unsigned 64-bit integer val in the end of the JSON document contained in buffer. More...
int	sol_json_token_get_double (const struct sol_json_token *token, double *value) SOL_ATTR_WARN_UNUSED_RESULT
	Get the numeric value of the given token as double-precision floating point. More...
static int	sol_json_token_get_int32 (const struct sol_json_token *token, int32_t *value)
	Get the numeric value of the given token as an 32 bits signed integer. More...
int	sol_json_token_get_int64 (const struct sol_json_token *token, int64_t *value)
	Get the numeric value of the given token as an 64 bits signed integer. More...
static size_t	sol_json_token_get_size (const struct sol_json_token *token)
	Returns the token size. More...
static enum sol_json_type	sol_json_token_get_type (const struct sol_json_token *token)
	Returns the type of the token pointed by token. More...
static int	sol_json_token_get_uint32 (const struct sol_json_token *token, uint32_t *value)
	Get the numeric value of the given token as an 32 bits unsigned integer. More...
int	sol_json_token_get_uint64 (const struct sol_json_token *token, uint64_t *value)
	Get the numeric value of the given token as an 64 bits unsigned integer. More...
int	sol_json_token_get_unescaped_string (const struct sol_json_token *token, struct sol_buffer *buffer)
	Copy to a sol_buffer the string pointed by token. More...
char *	sol_json_token_get_unescaped_string_copy (const struct sol_json_token *value)
	Creates a copy of the unescaped and no-quotes string produced by sol_json_token_get_unescaped_string. More...
static void	sol_json_token_init_from_slice (struct sol_json_token *token, const struct sol_str_slice slice)
	Initialized a JSON token from a struct sol_str_slice. More...
static bool	sol_json_token_str_eq (const struct sol_json_token *token, const char *str, size_t len)
	Checks if the string pointed by token is equal to the string str. More...
static struct sol_str_slice	sol_json_token_to_slice (const struct sol_json_token *token)
	Converts a JSON token to a string slice. More...

Detailed Description

JSON parser.

Macro Definition Documentation

#define SOL_JSON_PATH_FOREACH	(		scanner,
			key,
			status
	)

Value:

for (status = SOL_JSON_LOOP_REASON_OK; \
        sol_json_path_get_next_segment(&scanner, &key_slice, &status);)

Go through all segments of a JSON Path.

Macro used to visit all segments of a JSON Path. If the need of visiting a JSON Path is accessing JSON Objects or JSON Array elements, prefer using function sol_json_get_value_by_path().

Parameters

scanner	An initialized struct sol_json_path_scanner.
key	A pointer to struct sol_str_slice, that is going to be filled with the current key being visited.
status	A pointer to the field to be filled with the reason this macro termination. SOL_JSON_LOOP_REASON_INVALID if an error occurred when parsing the JSON Path. SOL_JSON_LOOP_REASON_OK if we reached the end of the JSON Path.

Usage example:

const char *path = "$.my_key[3].other_key"; //Replace path here
struct sol_json_path_scanner path_scanner;
enum sol_json_loop_status reason;
struct sol_str_slice key_slice;

sol_json_path_scanner_init(&path_scanner, path);
SOL_JSON_PATH_FOREACH(path_scanner, key_slice, reason) {
    printf("%*s\n", SOL_STR_SLICE_PRINT(key_slice));
    //Do something else
}

if (status != SOL_JSON_LOOP_REASON_OK) {
    //Error Handling
}

For the path in example, we would print:

my_key
[3]
other_key

#define SOL_JSON_SCANNER_ARRAY_LOOP	(		scanner_,
			token_,
			status_
	)

Value:

for (status_ = sol_json_loop_iterate_init(scanner_, token_, SOL_JSON_TYPE_ARRAY_START); \
        sol_json_loop_iterate_generic(scanner_, token_, SOL_JSON_TYPE_ARRAY_END, &status_);)

Helper macro to iterate over the elements an array in a JSON document, ignoring the elements type.

Parameters

scanner_	JSON scanner
token_	Current token on each iteration
status_	Loop exit status

#define SOL_JSON_SCANNER_ARRAY_LOOP_NESTED	(		scanner_,
			token_,
			status_
	)

Value:

for (status_ = SOL_JSON_LOOP_REASON_OK; \
        sol_json_loop_iterate_generic(scanner_, token_, SOL_JSON_TYPE_ARRAY_END, &status_);)

Helper macro to iterate over the elements of a nested array in a JSON document, ignoring the elements type.

When iterating over nested objects and arrays, you don't want to call sol_json_loop_iterate_init, that is why you need to use this macro for nested stuff.

Parameters

scanner_	JSON scanner
token_	Current token on each iteration
status_	Loop exit status

#define SOL_JSON_SCANNER_ARRAY_LOOP_TYPE	(		scanner_,
			token_,
			element_type_,
			status_
	)

Value:

for (status_ = sol_json_loop_iterate_init(scanner_, token_, SOL_JSON_TYPE_ARRAY_START); \
        sol_json_loop_iterate_array(scanner_, token_, &status_, element_type_);)

Helper macro to iterate over the elements of an array in a JSON document.

Parameters

scanner_	JSON scanner
token_	Current token on each iteration
element_type_	Token type of the elements in the array
status_	Loop exit status

See Also

sol_json_scanner_init

#define SOL_JSON_SCANNER_ARRAY_LOOP_TYPE_NESTED	(		scanner_,
			token_,
			element_type_,
			status_
	)

Value:

for (status_ = SOL_JSON_LOOP_REASON_OK; \
        sol_json_loop_iterate_array(scanner_, token_, &status_, element_type_);)

Helper macro to iterate over the elements of a nested array in a JSON document.

When iterating over nested objects and arrays, you don't want to call sol_json_loop_iterate_init, that is why you need to use this macro for nested stuff.

Parameters

scanner_	JSON scanner
token_	Current token on each iteration
element_type_	Token type of the elements in the array
status_	Loop exit status

#define SOL_JSON_SCANNER_OBJECT_LOOP	(		scanner_,
			token_,
			key_,
			value_,
			status_
	)

Value:

for (status_ = sol_json_loop_iterate_init(scanner_, token_, SOL_JSON_TYPE_OBJECT_START); \
        sol_json_loop_iterate_object(scanner_, token_, key_, value_, &status_);)

Helper macro to iterate over the elements of an object in a JSON document.

Parameters

scanner_	JSON scanner
token_	Current token on each iteration
key_	Token to the current pair's key on each iteration
value_	Token to the current pair's value on each iteration
status_	Loop exit status

See Also

sol_json_scanner_init

#define SOL_JSON_SCANNER_OBJECT_LOOP_NESTED	(		scanner_,
			token_,
			key_,
			value_,
			status_
	)

Value:

for (status_ = SOL_JSON_LOOP_REASON_OK; \
        sol_json_loop_iterate_object(scanner_, token_, key_, value_, &status_);)

Helper macro to iterate over the elements of a nested object in a JSON document.

When iterating over nested objects and arrays, you don't want to call sol_json_loop_iterate_init, that is why you need to use this macro for nested stuff.

Parameters

scanner_	JSON scanner
token_	Current token on each iteration
key_	Token to the current pair's key on each iteration
value_	Token to the current pair's value on each iteration
status_	Loop exit status

#define SOL_JSON_TOKEN_STR_LITERAL_EQ	(		token_,
			str_
	)		sol_json_token_str_eq(token_, str_, sizeof(str_) - 1)

Helper macro to check if the string pointed by token_ is equal to a string literal.

Parameters

token_	Token of type string
str_	String literal

Returns

true if the contents are equal, false otherwise

Note

The JSON string pointed by token may be escaped, so take this into consideration to compare compatible strings.

Typedef Documentation

typedef struct sol_json_path_scanner sol_json_path_scanner

Scanner used to go through segments of a JSON Path.

Note

JSONPath syntax is available at http://goessner.net/articles/JsonPath/.

See Also

sol_json_path_scanner_init()

sol_json_path_get_next_segment()

SOL_JSON_PATH_FOREACH()

typedef struct sol_json_scanner sol_json_scanner

Structure to track a JSON document (or a portion of it) being parsed.

typedef struct sol_json_token sol_json_token

Type describing a JSON token.

Used to point and delimit JSON element while parsing a JSON document.

Enumeration Type Documentation

enum sol_json_loop_status

Return values used by the parser 'loop' macros.

Used to inform if the macro successfully parsed the provided content or not. Invalid may be returned when an invalid JSON construct is found, but also when what was parsed doesn't match the requirements provided through 'loop' parameters.

Enumerator
SOL_JSON_LOOP_REASON_OK	Content successfully parsed.
SOL_JSON_LOOP_REASON_INVALID	Failed to parse the content.

enum sol_json_type

Token type enumeration.

Enumerator
SOL_JSON_TYPE_UNKNOWN	Unknown token.
SOL_JSON_TYPE_OBJECT_START	JSON Object start.
SOL_JSON_TYPE_OBJECT_END	JSON Object end.
SOL_JSON_TYPE_ARRAY_START	JSON Array start.
SOL_JSON_TYPE_ARRAY_END	JSON Array end.
SOL_JSON_TYPE_ELEMENT_SEP	JSON Element separator.
SOL_JSON_TYPE_PAIR_SEP	JSON Pair separator.
SOL_JSON_TYPE_TRUE	'true' value
SOL_JSON_TYPE_FALSE	'false' value
SOL_JSON_TYPE_NULL	'null' value
SOL_JSON_TYPE_STRING	JSON string token.
SOL_JSON_TYPE_NUMBER	JSON number token.

Function Documentation

int sol_json_array_get_at_index	(	struct sol_json_scanner *	scanner,
		uint16_t	i,
		struct sol_json_token *	value
	)

Get the element in position i in JSON Array contained in scanner.

Parameters

scanner	An initialized scanner, which is pointing to a JSON Array.
value	A pointer to the structure that will be filled with the value of the element at position i.
i	The position of the desired element.

Returns

If any parameter is invalid, or if scanner is not pointing to a JSON Array, return -EINVAL. If i is larger than the array's length, -ENOENT. If value was updated successfully with the value in position i, return 0.

See Also

sol_json_object_get_value_by_key()

size_t sol_json_calculate_escaped_string_len

(

const char *

str

)

Calculate the size in bytes of the escaped version of a string.

Parameters

str	Input string

Returns

Size necessary to hold the escaped version of str

int sol_json_double_to_str	(	const double	value,
		struct sol_buffer *	buf
	)

Converts a double into a string suited for use in a JSON Document.

Parameters

value	Value to be converted
buf	Where to append the converted value - It must be already initialized.

Returns

0 on success, error code (always negative) otherwise

char* sol_json_escape_string	(	const char *	str,
		struct sol_buffer *	buf
	)

Escapes JSON special and control characters from the string content.

Parameters

str	String to escape
buf	Where to append the escaped string - It must be already initialized.

Returns

The escaped string

int sol_json_get_value_by_path	(	struct sol_json_scanner *	scanner,
		struct sol_str_slice	path,
		struct sol_json_token *	value
	)

Get the element referenced by the JSON Path path in a JSON Object or Array.

Parameters

scanner	An initialized scanner, which is pointing to a JSON Object or a JSON Array.
path	The JSON Path of the desired element.
value	A pointer to the structure that will be filled with the value of the element referenced by path.

Returns

If any parameter is invalid, or if scanner is not pointing to a JSON Object or JSON Array, or if path is not a valid JSON Path, return -EINVAL. If path is pointing to an invalid position in a JSON Object or in a JSON Array, -ENOENT. If value was successfully updated with the value of the element referenced by path, return 0.

See Also

sol_json_path_scanner

bool sol_json_is_valid_type	(	struct sol_json_scanner *	scanner,
		enum sol_json_type	start_type
	)

Check if scanner content is pointing to a valid JSON element of type start_type.

Note

May or may not be NULL terminated.

Parameters

scanner	JSON scanner
start_type	Token type of the desired JSON element

Returns

true if JSON element is valid, false otherwise

int sol_json_load_memdesc	(	const struct sol_json_token *	token,
		const struct sol_memdesc *	desc,
		void *	memory
	)

Loads the members of a memory from JSON according to its description.

If the SOL_MEMDESC_TYPE_STRUCTURE or SOL_MEMDESC_TYPE_PTR with children, then it will be loaded from an object with keys being the description name.

If defaults are desired, then call sol_memdesc_init_defaults() before calling this function.

If not all required members of a structure where provided, then -ENODATA is returned. The code will try to load as much as possible before returning.

Parameters

token	the token to convert to memory using description.
desc	the memory description to use when loading.
memory	the memory described by desc.

Returns

0 on success, error code (always negative) otherwise. Note that -ENODATA will be returned if required structure members were missing.

See Also

sol_json_serialize_memdesc()

static bool sol_json_loop_iterate_array ( struct sol_json_scanner *  scanner, struct sol_json_token *  token, enum sol_json_loop_status *  reason, enum sol_json_type  element_type  )

inlinestatic

Function to help iterate over a JSON array.

Parameters

scanner	JSON scanner
token	Current token after the iteration
reason	Exit status of an iteration
element_type	Token type of the elements in the array

Returns

true if successfully iterated over the sequence, false otherwise

References sol_json_loop_iterate_generic(), SOL_JSON_LOOP_REASON_INVALID, SOL_JSON_LOOP_REASON_OK, sol_json_token_get_type(), and SOL_JSON_TYPE_ARRAY_END.

static bool sol_json_loop_iterate_generic ( struct sol_json_scanner *  scanner, struct sol_json_token *  token, enum sol_json_type  end_type, enum sol_json_loop_status *  reason  )

inlinestatic

Function to help iterate over a generic JSON sequence.

Parameters

scanner	JSON scanner
token	Current token after the iteration
end_type	Token type that ends the sequence
reason	Exit status of an iteration

Returns

true if successfully iterated over the sequence, false otherwise

References SOL_JSON_LOOP_REASON_INVALID, SOL_JSON_LOOP_REASON_OK, sol_json_scanner_next(), sol_json_token_get_type(), and SOL_JSON_TYPE_ELEMENT_SEP.

Referenced by sol_json_loop_iterate_array(), and sol_json_loop_iterate_object().

static enum sol_json_loop_status sol_json_loop_iterate_init ( struct sol_json_scanner *  scanner, struct sol_json_token *  token, enum sol_json_type  start_type  )

inlinestatic

Function to bootstrap an iteration over a JSON sequence.

Parameters

scanner	JSON scanner
token	Current token after initialization
start_type	Token type that starts the sequence

Returns

Exit status of the initialization

References SOL_JSON_LOOP_REASON_INVALID, SOL_JSON_LOOP_REASON_OK, sol_json_scanner_next(), and sol_json_token_get_type().

static bool sol_json_loop_iterate_object ( struct sol_json_scanner *  scanner, struct sol_json_token *  token, struct sol_json_token *  key, struct sol_json_token *  value, enum sol_json_loop_status *  reason  )

inlinestatic

Function to help iterate over a JSON object.

Parameters

scanner	JSON scanner
token	Current token after the iteration
key	Token to the key of the current object pair
value	Token to the value of the current object pair
reason	Exit status of an iteration

Returns

true if successfully iterated over the sequence, false otherwise

References sol_json_loop_iterate_generic(), SOL_JSON_LOOP_REASON_INVALID, SOL_JSON_LOOP_REASON_OK, sol_json_scanner_get_dict_pair(), and SOL_JSON_TYPE_OBJECT_END.

static enum sol_json_type sol_json_mem_get_type ( const void *  mem )

inlinestatic

Returns the type of the token pointed by mem.

Parameters

mem	Pointer to JSON Document data

Returns

JSON type of the token pointed by mem

References SOL_JSON_TYPE_NUMBER, and SOL_JSON_TYPE_UNKNOWN.

Referenced by sol_json_token_get_type().

int sol_json_object_get_value_by_key	(	struct sol_json_scanner *	scanner,
		const struct sol_str_slice	key_slice,
		struct sol_json_token *	value
	)

Get the value of the JSON Object child element referenced by key_slice.

Parameters

scanner	An initialized scanner, which is pointing to a JSON Object.
key_slice	The key of the desired element.
value	A pointer to the structure that will be filled with the value of the element referenced by key_slice.

Returns

If any parameter is invalid, or if scanner is not pointing to a JSON Object, return -EINVAL. If key_slice is not present in the JSON Object, -ENOENT. If key was found, and value was update successfully with the value referenced by key, return 0.

See Also

sol_json_array_get_at_index()

int32_t sol_json_path_array_get_segment_index

(

struct sol_str_slice

key

)

Get the integer index from a JSON Path array segment.

This function expects a valid JSON Path segment with format: [NUMBER], where NUMBER is an integer and returns NUMBER converted to an integer variable.

Parameters

key	The key to extract the integer index.

Returns

If key is a valid array segment in the format expecified, returns the converted index. If key is invalid, returns -EINVAL and if number is out of range, returns -ERANGE.

See Also

SOL_JSON_PATH_FOREACH()

bool sol_json_path_get_next_segment	(	struct sol_json_path_scanner *	scanner,
		struct sol_str_slice *	slice,
		enum sol_json_loop_status *	status
	)

Get next segment from JSON Path in scanner.

Update slice with the next valid JSON Path segment in scanner.

Parameters

scanner	An initialized JSON Path scanner.
slice	A pointer to the slicer structure to be filled with next JSON Path segment.
status	A pointer to the field to be filled with the reason this function termination. SOL_JSON_LOOP_REASON_INVALID if an error occurred when parsing the JSON Path. SOL_JSON_LOOP_REASON_OK if the next segment was updated in slice or if there is no more segments in this JSON Path.

Returns

True if next segment was updated in value. False if an error occurred or if there is no more segments available.

static bool sol_json_path_is_array_key ( struct sol_str_slice  slice )

inlinestatic

Check if slice is a valid JSON Path array segment.

Parameters

slice

A JSON Path segment.

Returns

True if slice is a valid JSON Path array segment. False otherwise.

See Also

SOL_JSON_PATH_FOREACH()

References sol_str_slice::data, and sol_str_slice::len.

int sol_json_path_scanner_init	(	struct sol_json_path_scanner *	scanner,
		struct sol_str_slice	path
	)

Initialize a JSON Path scanner with path.

JSON path scanner can be used to go through segments of a JSON Path using SOL_JSON_PATH_FOREACH() or sol_json_path_get_next_segment() functions.

Parameters

scanner	An uninitialized JSON Path scanner.
path	A valid JSON Path string.

Returns

0 on success, -EINVAL if scanner is NULL.

See Also

sol_json_path_scanner

bool sol_json_scanner_get_dict_pair	(	struct sol_json_scanner *	scanner,
		struct sol_json_token *	key,
		struct sol_json_token *	value
	)

Retrieve <key, value> pair currently pointed by scanner.

Retrieve the key and value tokens from scanner's current position and update the scanner position to point to after the pair.

Parameters

scanner	JSON scanner
key	Token of the pair's key
value	Token of the pair's value

Returns

true if a pair is successfully retrieved, false otherwise

Referenced by sol_json_loop_iterate_object().

static size_t sol_json_scanner_get_mem_offset ( const struct sol_json_scanner *  scanner, const void *  mem  )

inlinestatic

Returns the offset of mem in the data managed by scanner.

Offset relative to the start of the JSON document portion handled by scanner.

Parameters

scanner	JSON scanner
mem	Pointer to JSON Document data

Returns

Offset in bytes, -1 in case of error.

References sol_json_scanner::mem, and sol_json_scanner::mem_end.

static size_t sol_json_scanner_get_size_remaining ( const struct sol_json_scanner *  scanner )

inlinestatic

Returns the size of the JSON document that wasn't scanned yet.

Parameters

scanner

JSON scanner

Returns

Remaining size in bytes

References sol_json_scanner::current, and sol_json_scanner::mem_end.

static void sol_json_scanner_init ( struct sol_json_scanner *  scanner, const void *  mem, size_t  size  )

inlinestatic

Initializes a JSON scanner.

Parameters

scanner	JSON scanner
mem	Pointer to the memory containing the JSON document
size	Memory size in bytes

Note

May or may not be NULL terminated.

References sol_json_scanner::current, sol_json_scanner::mem, and sol_json_scanner::mem_end.

Referenced by sol_json_scanner_init_from_slice().

static void sol_json_scanner_init_from_scanner ( struct sol_json_scanner *  scanner, const struct sol_json_scanner *  other  )

inlinestatic

Initializes a JSON scanner based on the information of a second scanner.

Useful to offload some segments of the JSON document to different parser routines.

Parameters

scanner	JSON scanner
other	Base JSON scanner

References sol_json_scanner::current, sol_json_scanner::mem, and sol_json_scanner::mem_end.

static void sol_json_scanner_init_from_slice ( struct sol_json_scanner *  scanner, const struct sol_str_slice  slice  )

inlinestatic

Initialized a JSON scanner from a struct sol_str_slice.

Parameters

scanner	JSON scanner
slice	The slice to initialized the JSON scanner

References sol_str_slice::data, sol_str_slice::len, and sol_json_scanner_init().

static void sol_json_scanner_init_from_token ( struct sol_json_scanner *  scanner, const struct sol_json_token *  token  )

inlinestatic

Initializes a JSON scanner based on the information of a JSON Token.

Useful to offload some segments of the JSON document to different parser routines.

Parameters

scanner	JSON scanner
token	JSON token

References sol_json_scanner::current, sol_json_token::end, sol_json_scanner::mem, sol_json_scanner::mem_end, and sol_json_token::start.

static void sol_json_scanner_init_null ( struct sol_json_scanner *  scanner )

inlinestatic

Initializes a JSON scanner with empty information.

Parameters

scanner

JSON scanner

References sol_json_scanner::current, sol_json_scanner::mem, and sol_json_scanner::mem_end.

bool sol_json_scanner_next	(	struct sol_json_scanner *	scanner,
		struct sol_json_token *	token
	)

Advance the scanner to the next JSON token.

Parameters

scanner	JSON scanner to advance
token	Current token after the advance

Returns

true if successfully advanced, false otherwise

Referenced by sol_json_loop_iterate_generic(), and sol_json_loop_iterate_init().

bool sol_json_scanner_skip	(	struct sol_json_scanner *	scanner,
		struct sol_json_token *	token
	)

Modifies scanner to point to token end, skipping over the token content.

If object/array start, it will be the matching end token. otherwise it will be the given token (as there is no nesting).

In every case the scanner->current position is reset to given token->end and as it iterates the scanner->position is updated to match the new token's end (sol_json_scanner_next() behavior).

Parameters

scanner	JSON scanner to advance
token	Current token after the advance

Returns

true if successfully skipped the token, false otherwise

int sol_json_serialize_bool	(	struct sol_buffer *	buffer,
		bool	val
	)

Inserts the string of the boolean value val in the end of the JSON document contained in buffer.

Parameters

buffer	Buffer containing the new JSON document
val	Value to be inserted in the JSON document

Returns

0 on success, error code (always negative) otherwise

int sol_json_serialize_double	(	struct sol_buffer *	buffer,
		double	val
	)

Inserts the string of the double val in the end of the JSON document contained in buffer.

Parameters

buffer	Buffer containing the new JSON document
val	Value to be inserted in the JSON document

Returns

0 on success, error code (always negative) otherwise

int sol_json_serialize_int32	(	struct sol_buffer *	buffer,
		int32_t	val
	)

Inserts the string of the 32-bit integer val in the end of the JSON document contained in buffer.

Parameters

buffer	Buffer containing the new JSON document
val	Value to be inserted in the JSON document

Returns

0 on success, error code (always negative) otherwise

int sol_json_serialize_int64	(	struct sol_buffer *	buffer,
		int64_t	val
	)

Inserts the string of the 64-bit integer val in the end of the JSON document contained in buffer.

Parameters

buffer	Buffer containing the new JSON document
val	Value to be inserted in the JSON document

Returns

0 on success, error code (always negative) otherwise

int sol_json_serialize_memdesc	(	struct sol_buffer *	buffer,
		const struct sol_memdesc *	desc,
		const void *	memory,
		bool	detailed_structures
	)

Appends the serialization of the given memory based on its description.

If the SOL_MEMDESC_TYPE_STRUCTURE or SOL_MEMDESC_TYPE_PTR with children, then it will be serialized as an object with keys being the description name.

Parameters

buffer	Buffer containing the new JSON document.
desc	the memory description to use when serializing.
memory	the memory described by desc.
detailed_structures	if false, all members of struct marked as detailed will be omitted.

Returns

0 on success, error code (always negative) otherwise.

See Also

sol_json_load_memdesc()

static int sol_json_serialize_null ( struct sol_buffer *  buffer )

inlinestatic

Inserts the string "null" in the end of the JSON document contained in buffer.

Parameters

buffer

Buffer containing the new JSON document

Returns

0 on success, error code (always negative) otherwise

References sol_buffer_append_slice(), and SOL_STR_SLICE_LITERAL.

int sol_json_serialize_string	(	struct sol_buffer *	buffer,
		const char *	str
	)

Inserts the string str in the end of the JSON document contained in buffer.

Parameters

buffer	Buffer containing the new JSON document
str	String to be inserted in the JSON document

Returns

0 on success, error code (always negative) otherwise

Note

The inserted string may be different of the original since this function will call sol_json_escape_string on it.

int sol_json_serialize_uint32	(	struct sol_buffer *	buffer,
		uint32_t	val
	)

Inserts the string of the unsigned 32-bit integer val in the end of the JSON document contained in buffer.

Parameters

buffer	Buffer containing the new JSON document
val	Value to be inserted in the JSON document

Returns

0 on success, error code (always negative) otherwise

int sol_json_serialize_uint64	(	struct sol_buffer *	buffer,
		uint64_t	val
	)

Inserts the string of the unsigned 64-bit integer val in the end of the JSON document contained in buffer.

Parameters

buffer	Buffer containing the new JSON document
val	Value to be inserted in the JSON document

Returns

0 on success, error code (always negative) otherwise

int sol_json_token_get_double	(	const struct sol_json_token *	token,
		double *	value
	)

Get the numeric value of the given token as double-precision floating point.

Parameters

token	the token to convert to number
value	where to return the converted number

Returns

0 on success, -errno on failure (EINVAL or ERANGE). On errors value will be set to a best-match, such as 0.0 if EINVAL, DBL_MAX or -DBL_MAX if ERANGE

See Also

sol_json_token_get_uint64()

sol_json_token_get_int64()

sol_json_token_get_uint32()

sol_json_token_get_int32()

static int sol_json_token_get_int32 ( const struct sol_json_token *  token, int32_t *  value  )

inlinestatic

Get the numeric value of the given token as an 32 bits signed integer.

Parameters

token	the token to convert to number
value	where to return the converted number

Returns

0 on success, -errno on failure (EINVAL or ERANGE). On errors value will be set to a best-match, such as 0 if EINVAL, INT32_MAX or INT32_MIN if ERANGE

See Also

sol_json_token_get_uint64()

sol_json_token_get_int32()

sol_json_token_get_double()

References sol_json_token_get_int64().

int sol_json_token_get_int64	(	const struct sol_json_token *	token,
		int64_t *	value
	)

Get the numeric value of the given token as an 64 bits signed integer.

Parameters

token	the token to convert to number
value	where to return the converted number

Returns

0 on success, -errno on failure (EINVAL or ERANGE). On errors value will be set to a best-match, such as 0 if EINVAL, INT64_MAX or INT64_MIN if ERANGE

See Also

sol_json_token_get_uint64()

sol_json_token_get_int32()

sol_json_token_get_double()

Referenced by sol_json_token_get_int32().

static size_t sol_json_token_get_size ( const struct sol_json_token *  token )

inlinestatic

Returns the token size.

Parameters

token

Token

Returns

Token size in bytes

References sol_json_token::end, and sol_json_token::start.

Referenced by sol_json_token_str_eq().

static enum sol_json_type sol_json_token_get_type ( const struct sol_json_token *  token )

inlinestatic

Returns the type of the token pointed by token.

Parameters

token

Token

Returns

JSON type of token

References sol_json_mem_get_type(), and sol_json_token::start.

Referenced by sol_json_loop_iterate_array(), sol_json_loop_iterate_generic(), sol_json_loop_iterate_init(), and sol_json_token_str_eq().

static int sol_json_token_get_uint32 ( const struct sol_json_token *  token, uint32_t *  value  )

inlinestatic

Get the numeric value of the given token as an 32 bits unsigned integer.

Parameters

token	the token to convert to number
value	where to return the converted number

Returns

0 on success, -errno on failure (EINVAL or ERANGE). On errors value will be set to a best-match, such as 0 if EINVAL or UINT32_MAX if ERANGE

See Also

sol_json_token_get_uint64()

sol_json_token_get_int32()

sol_json_token_get_double()

References sol_json_token_get_uint64().

int sol_json_token_get_uint64	(	const struct sol_json_token *	token,
		uint64_t *	value
	)

Get the numeric value of the given token as an 64 bits unsigned integer.

Parameters

token	the token to convert to number
value	where to return the converted number

Returns

0 on success, -errno on failure (EINVAL or ERANGE). On errors value will be set to a best-match, such as 0 if EINVAL or UINT64_MAX if ERANGE

See Also

sol_json_token_get_int64()

sol_json_token_get_uint32()

sol_json_token_get_double()

Referenced by sol_json_token_get_uint32().

int sol_json_token_get_unescaped_string	(	const struct sol_json_token *	token,
		struct sol_buffer *	buffer
	)

Copy to a sol_buffer the string pointed by token.

If token is of type string, quotes are removed and string is unescaped. If not, the full token value is returned as a string.

If necessary memory will be allocated to place unescaped string, so caller is responsible to call sol_buffer_fini after using the buffer content.

Note

sol_buffer_init will be called internally to initialize the buffer.

Parameters

token	Token to get the string from
buffer	Uninitialized buffer

Returns

0 on success, a negative error code on failure

char* sol_json_token_get_unescaped_string_copy

(

const struct sol_json_token *

value

)

Creates a copy of the unescaped and no-quotes string produced by sol_json_token_get_unescaped_string.

Caller is responsible to free the string memory.

Parameters

value

A string type token

Returns

A copy of the unescaped string on success, NULL otherwise

static void sol_json_token_init_from_slice ( struct sol_json_token *  token, const struct sol_str_slice  slice  )

inlinestatic

Initialized a JSON token from a struct sol_str_slice.

Parameters

token	JSON token
slice	The slice to initialized the JSON scanner

References sol_str_slice::data, sol_json_token::end, sol_str_slice::len, and sol_json_token::start.

static bool sol_json_token_str_eq ( const struct sol_json_token *  token, const char *  str, size_t  len  )

inlinestatic

Checks if the string pointed by token is equal to the string str.

Parameters

token	Token of type string
str	The string to compare
len	Size of str

Returns

true if the contents are equal, false otherwise

Note

The JSON string pointed by token may be escaped, so take this into consideration to compare compatible strings.

References sol_json_token_get_size(), sol_json_token_get_type(), SOL_JSON_TYPE_STRING, and sol_json_token::start.

static struct sol_str_slice sol_json_token_to_slice ( const struct sol_json_token *  token )

static

Converts a JSON token to a string slice.

Parameters

token

the token to convert to string slice

Returns

A string slice struct

See Also

sol_str_slice

References sol_json_token::end, SOL_STR_SLICE_STR, and sol_json_token::start.