JSON

Topics
	JSON Web Token (JWT)
	JSON Web Token (JWT) - RFC 7519.

Data Structures
struct	json_token
struct	json_lexer
struct	json_obj
struct	json_obj_token
struct	json_obj_descr
struct	json_mixed_arr_descr
	Descriptor for a mixed-type JSON array. More...

Macros
#define	JSON_OBJ_DESCR_PRIM(struct_, field_name_, type_)
	Helper macro to declare a descriptor for supported primitive values.
#define	JSON_OBJ_DESCR_OBJECT(struct_, field_name_, sub_descr_)
	Helper macro to declare a descriptor for an object value.
#define	JSON_OBJ_DESCR_ARRAY(struct_, field_name_, max_len_, len_field_, elem_type_)
	Helper macro to declare a descriptor for an array of primitives.
#define	JSON_OBJ_DESCR_OBJ_ARRAY(struct_, field_name_, max_len_, len_field_, elem_descr_, elem_descr_len_)
	Helper macro to declare a descriptor for an array of objects.
#define	JSON_OBJ_DESCR_ARRAY_ARRAY(struct_, field_name_, max_len_, len_field_, elem_descr_, elem_descr_len_)
	Helper macro to declare a descriptor for an array of array.
#define	JSON_OBJ_DESCR_ARRAY_ARRAY_NAMED(struct_, json_field_name_, struct_field_name_, max_len_, len_field_, elem_descr_, elem_descr_len_)
	Variant of JSON_OBJ_DESCR_ARRAY_ARRAY that can be used when the structure and JSON field names differ.
#define	JSON_OBJ_DESCR_PRIM_NAMED(struct_, json_field_name_, struct_field_name_, type_)
	Variant of JSON_OBJ_DESCR_PRIM that can be used when the structure and JSON field names differ.
#define	JSON_OBJ_DESCR_OBJECT_NAMED(struct_, json_field_name_, struct_field_name_, sub_descr_)
	Variant of JSON_OBJ_DESCR_OBJECT that can be used when the structure and JSON field names differ.
#define	JSON_OBJ_DESCR_ARRAY_NAMED(struct_, json_field_name_, struct_field_name_, max_len_, len_field_, elem_type_)
	Variant of JSON_OBJ_DESCR_ARRAY that can be used when the structure and JSON field names differ.
#define	JSON_OBJ_DESCR_OBJ_ARRAY_NAMED(struct_, json_field_name_, struct_field_name_, max_len_, len_field_, elem_descr_, elem_descr_len_)
	Variant of JSON_OBJ_DESCR_OBJ_ARRAY that can be used when the structure and JSON field names differ.
#define	JSON_MIXED_ARR_DESCR_PRIM(struct_, field_name_, type_, count_field_)
	Helper macro to declare a mixed array primitive element descriptor.
#define	JSON_MIXED_ARR_DESCR_OBJECT(struct_, field_name_, sub_descr_, count_field_)
	Helper macro to declare a mixed array object element descriptor.
#define	JSON_MIXED_ARR_DESCR_ARRAY(struct_, field_name_, max_len_, elem_descr_, count_field_)
	Helper macro to declare a mixed array homogeneous array element descriptor.
#define	JSON_MIXED_ARR_DESCR_MIXED_ARRAY(struct_, field_name_, sub_descr_, count_field_)
	Helper macro to declare a nested mixed array element descriptor.

Typedefs
typedef int(*	json_append_bytes_t) (const char *bytes, size_t len, void *data)
	Function pointer type to append bytes to a buffer while encoding JSON data.

Enumerations

enum

json_tokens {   JSON_TOK_NONE = '_' , JSON_TOK_OBJECT_START = '{' , JSON_TOK_OBJECT_END = '}' , JSON_TOK_ARRAY_START = '[' ,   JSON_TOK_ARRAY_END = ']' , JSON_TOK_STRING = '"' , JSON_TOK_STRING_BUF = 's' , JSON_TOK_COLON = ':' ,   JSON_TOK_COMMA = ',' , JSON_TOK_NUMBER = '0' , JSON_TOK_FLOAT = '1' , JSON_TOK_OPAQUE = '2' ,   JSON_TOK_OBJ_ARRAY = '3' , JSON_TOK_ENCODED_OBJ = '4' , JSON_TOK_INT64 = '5' , JSON_TOK_UINT64 = '6' ,   JSON_TOK_FLOAT_FP = '7' , JSON_TOK_DOUBLE_FP = '8' , JSON_TOK_INT = 'i' , JSON_TOK_UINT = 'u' ,   JSON_TOK_TRUE = 't' , JSON_TOK_FALSE = 'f' , JSON_TOK_MIXED_ARRAY = 'm' , JSON_TOK_NULL = 'n' ,   JSON_TOK_ERROR = '!' , JSON_TOK_EOF = '\0' }

Functions
int64_t	json_obj_parse (char *json, size_t len, const struct json_obj_descr *descr, size_t descr_len, void *val)
	Parses the JSON-encoded object pointed to by json, with size len, according to the descriptor pointed to by descr.
int	json_arr_parse (char *json, size_t len, const struct json_obj_descr *descr, void *val)
	Parses the JSON-encoded array pointed to by json, with size len, according to the descriptor pointed to by descr.
int	json_arr_separate_object_parse_init (struct json_obj *json, char *payload, size_t len)
	Initialize single-object array parsing.
int	json_arr_separate_parse_object (struct json_obj *json, const struct json_obj_descr *descr, size_t descr_len, void *val)
	Parse a single object from array.
ssize_t	json_escape (char *str, size_t *len, size_t buf_size)
	Escapes the string so it can be used to encode JSON objects.
size_t	json_calc_escaped_len (const char *str, size_t len)
	Calculates the JSON-escaped string length.
ssize_t	json_calc_encoded_len (const struct json_obj_descr *descr, size_t descr_len, const void *val)
	Calculates the string length to fully encode an object.
ssize_t	json_calc_encoded_arr_len (const struct json_obj_descr *descr, const void *val)
	Calculates the string length to fully encode an array.
int	json_obj_encode_buf (const struct json_obj_descr *descr, size_t descr_len, const void *val, char *buffer, size_t buf_size)
	Encodes an object in a contiguous memory location.
int	json_arr_encode_buf (const struct json_obj_descr *descr, const void *val, char *buffer, size_t buf_size)
	Encodes an array in a contiguous memory location.
int	json_obj_encode (const struct json_obj_descr *descr, size_t descr_len, const void *val, json_append_bytes_t append_bytes, void *data)
	Encodes an object using an arbitrary writer function.
int	json_arr_encode (const struct json_obj_descr *descr, const void *val, json_append_bytes_t append_bytes, void *data)
	Encodes an array using an arbitrary writer function.
int	json_mixed_arr_parse (char *json, size_t len, const struct json_mixed_arr_descr *descr, size_t descr_len, void *val)
	Parse a JSON mixed array into a C structure.
int	json_mixed_arr_encode (const struct json_mixed_arr_descr *descr, size_t descr_len, void *val, json_append_bytes_t append_bytes, void *data)
	Encode a C structure as a JSON mixed array.
int	json_mixed_arr_encode_buf (const struct json_mixed_arr_descr *descr, size_t descr_len, void *val, char *buffer, size_t buf_size)
	Encode a C structure as a JSON mixed array into a buffer.
ssize_t	json_calc_mixed_arr_len (const struct json_mixed_arr_descr *descr, size_t descr_len, void *val)
	Calculate the length of the encoded JSON mixed array.

Detailed Description

Macro Definition Documentation

JSON_MIXED_ARR_DESCR_ARRAY

#define JSON_MIXED_ARR_DESCR_ARRAY	(		struct_,
			field_name_,
			max_len_,
			elem_descr_,
			count_field_ )

#include <zephyr/data/json.h>

Value:

{ \
        .type = JSON_TOK_ARRAY_START, \
        .count_offset = offsetof(struct_, count_field_), \
        .array = { \
                .element_descr = elem_descr_, \
                .n_elements = (max_len_), \
                .offset = offsetof(struct_, field_name_) \
        } \
}

Helper macro to declare a mixed array homogeneous array element descriptor.

Parameters

struct_	Struct containing the array.
field_name_	Field name in the struct.
max_len_	Maximum number of elements in the array.
elem_descr_	Element descriptor (pointer to json_obj_descr array).
count_field_	Field name in the struct for the number of elements.

Example: struct foo { int arr[4]; size_t arr_count; }; const struct json_obj_descr arr_elem_descr[] = { JSON_OBJ_DESCR_ARRAY(struct foo, arr, 4, arr_count, JSON_TOK_NUMBER), }; const struct json_mixed_arr_descr foo_descr[] = { JSON_MIXED_ARR_DESCR_ARRAY(struct foo, arr, 4, arr_elem_descr, arr_count), };

JSON_MIXED_ARR_DESCR_MIXED_ARRAY

#define JSON_MIXED_ARR_DESCR_MIXED_ARRAY	(		struct_,
			field_name_,
			sub_descr_,
			count_field_ )

#include <zephyr/data/json.h>

Value:

{ \
        .type = JSON_TOK_MIXED_ARRAY, \
        .count_offset = offsetof(struct_, count_field_), \
        .mixed_array = { \
                .sub_descr = sub_descr_, \
                .sub_descr_len = ARRAY_SIZE(sub_descr_), \
                .offset = offsetof(struct_, field_name_) \
        } \
}

Helper macro to declare a nested mixed array element descriptor.

Parameters

struct_	Struct containing the nested mixed array.
field_name_	Field name in the struct.
sub_descr_	Mixed array descriptor for the nested array.
count_field_	Field name in the struct for the number of elements.

Example: struct foo { ...; size_t nested_count; }; const struct json_mixed_arr_descr nested_descr[] = { ... }; const struct json_mixed_arr_descr foo_descr[] = { JSON_MIXED_ARR_DESCR_MIXED_ARRAY(struct foo, nested, nested_descr, nested_count), };

JSON_MIXED_ARR_DESCR_OBJECT

#define JSON_MIXED_ARR_DESCR_OBJECT	(		struct_,
			field_name_,
			sub_descr_,
			count_field_ )

#include <zephyr/data/json.h>

Value:

{ \
        .type = JSON_TOK_OBJECT_START, \
        .count_offset = offsetof(struct_, count_field_), \
        .object = { \
                .sub_descr = sub_descr_, \
                .sub_descr_len = ARRAY_SIZE(sub_descr_), \
                .offset = offsetof(struct_, field_name_) \
        } \
}

Helper macro to declare a mixed array object element descriptor.

Parameters

struct_	Struct containing the object.
field_name_	Field name in the struct.
sub_descr_	Array of json_obj_descr describing the object fields.
count_field_	Field name in the struct for the number of elements.

Example: struct bar { int y; }; struct foo { struct bar b; size_t b_count; }; const struct json_obj_descr bar_descr[] = { ... }; const struct json_mixed_arr_descr foo_descr[] = { JSON_MIXED_ARR_DESCR_OBJECT(struct foo, b, bar_descr, b_count), };

JSON_MIXED_ARR_DESCR_PRIM

#define JSON_MIXED_ARR_DESCR_PRIM	(		struct_,
			field_name_,
			type_,
			count_field_ )

#include <zephyr/data/json.h>

Value:

{ \
        .type = type_, \
        .count_offset = offsetof(struct_, count_field_), \
        .primitive = { \
            .offset = offsetof(struct_, field_name_), \
            .size = SIZEOF_FIELD(struct_, field_name_) \
        } \
}

Helper macro to declare a mixed array primitive element descriptor.

Parameters

struct_	Struct containing the value.
field_name_	Field name in the struct.
type_	Token type for the JSON value (see enum json_tokens).
count_field_	Field name in the struct for the number of elements.

Example: struct foo { int x; size_t x_count; }; const struct json_mixed_arr_descr foo_descr[] = { JSON_MIXED_ARR_DESCR_PRIM(struct foo, x, JSON_TOK_NUMBER, x_count), };

JSON_OBJ_DESCR_ARRAY

#define JSON_OBJ_DESCR_ARRAY	(		struct_,
			field_name_,
			max_len_,
			len_field_,
			elem_type_ )

#include <zephyr/data/json.h>

Value:

        { \
                .field_name = (#field_name_), \
                .align_shift = Z_ALIGN_SHIFT(struct_), \
                .field_name_len = sizeof(#field_name_) - 1, \
                .type = JSON_TOK_ARRAY_START, \
                .offset = offsetof(struct_, field_name_), \
                .array = { \
                        .element_descr = Z_JSON_ELEMENT_DESCR(struct_, len_field_, \
                                elem_type_, \
                                Z_JSON_DESCR_FIELD(struct_, field_name_[0])), \
                        .n_elements = (max_len_), \
                }, \
        }

Helper macro to declare a descriptor for an array of primitives.

Parameters

struct_	Struct packing the values
field_name_	Field name in the struct
max_len_	Maximum number of elements in array
len_field_	Field name in the struct for the number of elements in the array
elem_type_	Element type, must be a primitive type

Here's an example of use:

 struct example {
     int32_t foo[10];
     size_t foo_len;
 };

 struct json_obj_descr array[] = {
      JSON_OBJ_DESCR_ARRAY(struct example, foo, 10, foo_len,
                           JSON_TOK_NUMBER)
 };

JSON_OBJ_DESCR_ARRAY_ARRAY

#define JSON_OBJ_DESCR_ARRAY_ARRAY	(		struct_,
			field_name_,
			max_len_,
			len_field_,
			elem_descr_,
			elem_descr_len_ )

#include <zephyr/data/json.h>

Value:

        { \
                .field_name = (#field_name_), \
                .align_shift = Z_ALIGN_SHIFT(struct_), \
                .field_name_len = sizeof(#field_name_) - 1, \
                .type = JSON_TOK_ARRAY_START, \
                .offset = offsetof(struct_, field_name_), \
                .array = { \
                        .element_descr = Z_JSON_ELEMENT_DESCR( \
                                struct_, len_field_, JSON_TOK_ARRAY_START, \
                                Z_JSON_DESCR_ARRAY( \
                                        elem_descr_, \
                                        1 + ZERO_OR_COMPILE_ERROR(elem_descr_len_ == 1))), \
                        .n_elements = (max_len_), \
                }, \
        }

Helper macro to declare a descriptor for an array of array.

Parameters

struct_	Struct packing the values
field_name_	Field name in the struct containing the array
max_len_	Maximum number of elements in the array
len_field_	Field name in the struct for the number of elements in the array
elem_descr_	Element descriptor, pointer to a descriptor array
elem_descr_len_	Number of elements in elem_descr_

Here's an example of use:

 struct person_height {
     const char *name;
     int32_t height;
 };

 struct person_heights_array {
     struct person_height heights;
 }

 struct people_heights {
     struct person_height_array heights[10];
     size_t heights_len;
 };

 struct json_obj_descr person_height_descr[] = {
     JSON_OBJ_DESCR_PRIM(struct person_height, name, JSON_TOK_STRING),
     JSON_OBJ_DESCR_PRIM(struct person_height, height, JSON_TOK_NUMBER),
 };

 struct json_obj_descr person_height_array_descr[] = {
     JSON_OBJ_DESCR_OBJECT(struct person_heights_array,
                           heights, person_height_descr),
 };

 struct json_obj_descr array_array[] = {
      JSON_OBJ_DESCR_ARRAY_ARRAY(struct people_heights, heights, 10,
                                 heights_len, person_height_array_descr,
                                 ARRAY_SIZE(person_height_array_descr)),
 };

JSON_OBJ_DESCR_ARRAY_ARRAY_NAMED

#define JSON_OBJ_DESCR_ARRAY_ARRAY_NAMED	(		struct_,
			json_field_name_,
			struct_field_name_,
			max_len_,
			len_field_,
			elem_descr_,
			elem_descr_len_ )

#include <zephyr/data/json.h>

Value:

        { \
                .field_name = (#json_field_name_), \
                .align_shift = Z_ALIGN_SHIFT(struct_), \
                .field_name_len = sizeof(#json_field_name_) - 1, \
                .type = JSON_TOK_ARRAY_START, \
                .offset = offsetof(struct_, struct_field_name_), \
                .array = { \
                        .element_descr = Z_JSON_ELEMENT_DESCR( \
                                struct_, len_field_, JSON_TOK_ARRAY_START, \
                                Z_JSON_DESCR_ARRAY( \
                                        elem_descr_, \
                                        1 + ZERO_OR_COMPILE_ERROR(elem_descr_len_ == 1))), \
                        .n_elements = (max_len_), \
                }, \
        }

Variant of JSON_OBJ_DESCR_ARRAY_ARRAY that can be used when the structure and JSON field names differ.

This is useful when the JSON field is not a valid C identifier.

Parameters

struct_	Struct packing the values
json_field_name_	String, field name in JSON strings
struct_field_name_	Field name in the struct containing the array
max_len_	Maximum number of elements in the array
len_field_	Field name in the struct for the number of elements in the array
elem_descr_	Element descriptor, pointer to a descriptor array
elem_descr_len_	Number of elements in elem_descr_

See also

JSON_OBJ_DESCR_ARRAY_ARRAY

JSON_OBJ_DESCR_ARRAY_NAMED

#define JSON_OBJ_DESCR_ARRAY_NAMED	(		struct_,
			json_field_name_,
			struct_field_name_,
			max_len_,
			len_field_,
			elem_type_ )

#include <zephyr/data/json.h>

Value:

        { \
                .field_name = (json_field_name_), \
                .align_shift = Z_ALIGN_SHIFT(struct_), \
                .field_name_len = sizeof(json_field_name_) - 1, \
                .type = JSON_TOK_ARRAY_START, \
                .offset = offsetof(struct_, struct_field_name_), \
                .array = { \
                        .element_descr = Z_JSON_ELEMENT_DESCR(struct_, len_field_, \
                                elem_type_, \
                                Z_JSON_DESCR_FIELD(struct_, struct_field_name_[0])), \
                        .n_elements = (max_len_), \
                }, \
        }

Variant of JSON_OBJ_DESCR_ARRAY that can be used when the structure and JSON field names differ.

This is useful when the JSON field is not a valid C identifier.

Parameters

struct_	Struct packing the values
json_field_name_	String, field name in JSON strings
struct_field_name_	Field name in the struct
max_len_	Maximum number of elements in array
len_field_	Field name in the struct for the number of elements in the array
elem_type_	Element type, must be a primitive type

See also

JSON_OBJ_DESCR_ARRAY

JSON_OBJ_DESCR_OBJ_ARRAY

#define JSON_OBJ_DESCR_OBJ_ARRAY	(		struct_,
			field_name_,
			max_len_,
			len_field_,
			elem_descr_,
			elem_descr_len_ )

#include <zephyr/data/json.h>

Value:

        { \
                .field_name = (#field_name_), \
                .align_shift = Z_ALIGN_SHIFT(struct_), \
                .field_name_len = sizeof(#field_name_) - 1, \
                .type = JSON_TOK_ARRAY_START, \
                .offset = offsetof(struct_, field_name_), \
                .array = { \
                        .element_descr = Z_JSON_ELEMENT_DESCR(struct_, len_field_, \
                                JSON_TOK_OBJECT_START, \
                                Z_JSON_DESCR_OBJ(elem_descr_, elem_descr_len_)), \
                        .n_elements = (max_len_), \
                }, \
        }

Helper macro to declare a descriptor for an array of objects.

Parameters

struct_	Struct packing the values
field_name_	Field name in the struct containing the array
max_len_	Maximum number of elements in the array
len_field_	Field name in the struct for the number of elements in the array
elem_descr_	Element descriptor, pointer to a descriptor array
elem_descr_len_	Number of elements in elem_descr_

Here's an example of use:

 struct person_height {
     const char *name;
     int32_t height;
 };

 struct people_heights {
     struct person_height heights[10];
     size_t heights_len;
 };

 struct json_obj_descr person_height_descr[] = {
      JSON_OBJ_DESCR_PRIM(struct person_height, name, JSON_TOK_STRING),
      JSON_OBJ_DESCR_PRIM(struct person_height, height, JSON_TOK_NUMBER),
 };

 struct json_obj_descr array[] = {
      JSON_OBJ_DESCR_OBJ_ARRAY(struct people_heights, heights, 10,
                               heights_len, person_height_descr,
                               ARRAY_SIZE(person_height_descr)),
 };

JSON_OBJ_DESCR_OBJ_ARRAY_NAMED

#define JSON_OBJ_DESCR_OBJ_ARRAY_NAMED	(		struct_,
			json_field_name_,
			struct_field_name_,
			max_len_,
			len_field_,
			elem_descr_,
			elem_descr_len_ )

#include <zephyr/data/json.h>

Value:

        { \
                .field_name = json_field_name_, \
                .align_shift = Z_ALIGN_SHIFT(struct_), \
                .field_name_len = sizeof(json_field_name_) - 1, \
                .type = JSON_TOK_ARRAY_START, \
                .offset = offsetof(struct_, struct_field_name_), \
                .array = { \
                        .element_descr = Z_JSON_ELEMENT_DESCR(struct_, len_field_, \
                                JSON_TOK_OBJECT_START, \
                                Z_JSON_DESCR_OBJ(elem_descr_, elem_descr_len_)), \
                        .n_elements = (max_len_), \
                }, \
        }

Variant of JSON_OBJ_DESCR_OBJ_ARRAY that can be used when the structure and JSON field names differ.

This is useful when the JSON field is not a valid C identifier.

Parameters

struct_	Struct packing the values
json_field_name_	String, field name of the array in JSON strings
struct_field_name_	Field name in the struct containing the array
max_len_	Maximum number of elements in the array
len_field_	Field name in the struct for the number of elements in the array
elem_descr_	Element descriptor, pointer to a descriptor array
elem_descr_len_	Number of elements in elem_descr_

Here's an example of use:

 struct person_height {
     const char *name;
     int32_t height;
 };

 struct people_heights {
     struct person_height heights[10];
     size_t heights_len;
 };

 struct json_obj_descr person_height_descr[] = {
      JSON_OBJ_DESCR_PRIM(struct person_height, name, JSON_TOK_STRING),
      JSON_OBJ_DESCR_PRIM(struct person_height, height, JSON_TOK_NUMBER),
 };

 struct json_obj_descr array[] = {
      JSON_OBJ_DESCR_OBJ_ARRAY_NAMED(struct people_heights,
                                     "people-heights", heights,
                                     10, heights_len,
                                     person_height_descr,
                                     ARRAY_SIZE(person_height_descr)),
 };

JSON_OBJ_DESCR_OBJECT

#define JSON_OBJ_DESCR_OBJECT	(		struct_,
			field_name_,
			sub_descr_ )

#include <zephyr/data/json.h>

Value:

        { \
                .field_name = (#field_name_), \
                .align_shift = Z_ALIGN_SHIFT(struct_), \
                .field_name_len = (sizeof(#field_name_) - 1), \
                .type = JSON_TOK_OBJECT_START, \
                .offset = offsetof(struct_, field_name_), \
                .object = { \
                        .sub_descr = sub_descr_, \
                        .sub_descr_len = ARRAY_SIZE(sub_descr_), \
                }, \
        }

Helper macro to declare a descriptor for an object value.

Parameters

struct_	Struct packing the values
field_name_	Field name in the struct
sub_descr_	Array of json_obj_descr describing the subobject

Here's an example of use:

 struct nested {
     int32_t foo;
     struct {
        int32_t baz;
     } bar;
 };

 struct json_obj_descr nested_bar[] = {
     { ... declare bar.baz descriptor ... },
 };
 struct json_obj_descr nested[] = {
     { ... declare foo descriptor ... },
     JSON_OBJ_DESCR_OBJECT(struct nested, bar, nested_bar),
 };

JSON_OBJ_DESCR_OBJECT_NAMED

#define JSON_OBJ_DESCR_OBJECT_NAMED	(		struct_,
			json_field_name_,
			struct_field_name_,
			sub_descr_ )

#include <zephyr/data/json.h>

Value:

        { \
                .field_name = (json_field_name_), \
                .align_shift = Z_ALIGN_SHIFT(struct_), \
                .field_name_len = (sizeof(json_field_name_) - 1), \
                .type = JSON_TOK_OBJECT_START, \
                .offset = offsetof(struct_, struct_field_name_), \
                .object = { \
                        .sub_descr = sub_descr_, \
                        .sub_descr_len = ARRAY_SIZE(sub_descr_), \
                }, \
        }

Variant of JSON_OBJ_DESCR_OBJECT that can be used when the structure and JSON field names differ.

This is useful when the JSON field is not a valid C identifier.

Parameters

struct_	Struct packing the values
json_field_name_	String, field name in JSON strings
struct_field_name_	Field name in the struct
sub_descr_	Array of json_obj_descr describing the subobject

See also

JSON_OBJ_DESCR_OBJECT

JSON_OBJ_DESCR_PRIM

#define JSON_OBJ_DESCR_PRIM	(		struct_,
			field_name_,
			type_ )

#include <zephyr/data/json.h>

Value:

        { \
                .field_name = (#field_name_), \
                .align_shift = Z_ALIGN_SHIFT(struct_), \
                .field_name_len = sizeof(#field_name_) - 1, \
                .type = type_, \
                .offset = offsetof(struct_, field_name_), \
                .field = { \
                        .size = SIZEOF_FIELD(struct_, field_name_) \
                }, \
        }

Helper macro to declare a descriptor for supported primitive values.

Parameters

struct_	Struct packing the values
field_name_	Field name in the struct
type_	Token type for JSON value corresponding to a primitive type. Must be one of: JSON_TOK_STRING for strings, JSON_TOK_NUMBER for numbers, JSON_TOK_TRUE (or JSON_TOK_FALSE) for booleans.

Here's an example of use:

struct foo {
    int32_t some_int;
};

struct json_obj_descr foo[] = {
    JSON_OBJ_DESCR_PRIM(struct foo, some_int, JSON_TOK_NUMBER),
};

JSON_OBJ_DESCR_PRIM_NAMED

#define JSON_OBJ_DESCR_PRIM_NAMED	(		struct_,
			json_field_name_,
			struct_field_name_,
			type_ )

#include <zephyr/data/json.h>

Value:

        { \
                .field_name = (json_field_name_), \
                .align_shift = Z_ALIGN_SHIFT(struct_), \
                .field_name_len = sizeof(json_field_name_) - 1, \
                .type = type_, \
                .offset = offsetof(struct_, struct_field_name_), \
                .field = { \
                        .size = SIZEOF_FIELD(struct_, struct_field_name_) \
                }, \
        }

Variant of JSON_OBJ_DESCR_PRIM that can be used when the structure and JSON field names differ.

This is useful when the JSON field is not a valid C identifier.

Parameters

struct_	Struct packing the values.
json_field_name_	String, field name in JSON strings
struct_field_name_	Field name in the struct
type_	Token type for JSON value corresponding to a primitive type.

See also

JSON_OBJ_DESCR_PRIM

Typedef Documentation

json_append_bytes_t

typedef int(* json_append_bytes_t) (const char *bytes, size_t len, void *data)

#include <zephyr/data/json.h>

Function pointer type to append bytes to a buffer while encoding JSON data.

Parameters

bytes	Contents to write to the output
len	Number of bytes to append to output
data	User-provided pointer

Returns

This callback function should return a negative number on error (which will be propagated to the return value of json_obj_encode()), or 0 on success.

Enumeration Type Documentation

json_tokens

enum json_tokens

#include <zephyr/data/json.h>

Enumerator
JSON_TOK_NONE
JSON_TOK_OBJECT_START
JSON_TOK_OBJECT_END
JSON_TOK_ARRAY_START
JSON_TOK_ARRAY_END
JSON_TOK_STRING
JSON_TOK_STRING_BUF
JSON_TOK_COLON
JSON_TOK_COMMA
JSON_TOK_NUMBER
JSON_TOK_FLOAT
JSON_TOK_OPAQUE
JSON_TOK_OBJ_ARRAY
JSON_TOK_ENCODED_OBJ
JSON_TOK_INT64
JSON_TOK_UINT64
JSON_TOK_FLOAT_FP
JSON_TOK_DOUBLE_FP
JSON_TOK_INT
JSON_TOK_UINT
JSON_TOK_TRUE
JSON_TOK_FALSE
JSON_TOK_MIXED_ARRAY
JSON_TOK_NULL
JSON_TOK_ERROR
JSON_TOK_EOF

Function Documentation

json_arr_encode()

int json_arr_encode	(	const struct json_obj_descr *	descr,
		const void *	val,
		json_append_bytes_t	append_bytes,
		void *	data )

#include <zephyr/data/json.h>

Encodes an array using an arbitrary writer function.

Parameters

descr	Pointer to the descriptor array
val	Struct holding the values
append_bytes	Function to append bytes to the output
data	Data pointer to be passed to the append_bytes callback function.

Returns

0 if object has been successfully encoded. A negative value indicates an error.

json_arr_encode_buf()

int json_arr_encode_buf	(	const struct json_obj_descr *	descr,
		const void *	val,
		char *	buffer,
		size_t	buf_size )

#include <zephyr/data/json.h>

Encodes an array in a contiguous memory location.

Parameters

descr	Pointer to the descriptor array
val	Struct holding the values
buffer	Buffer to store the JSON data
buf_size	Size of buffer, in bytes, with space for the terminating NUL character

Returns

0 if object has been successfully encoded. A negative value indicates an error (as defined on errno.h).

json_arr_parse()

int json_arr_parse	(	char *	json,
		size_t	len,
		const struct json_obj_descr *	descr,
		void *	val )

#include <zephyr/data/json.h>

Parses the JSON-encoded array pointed to by json, with size len, according to the descriptor pointed to by descr.

Values are stored in a struct pointed to by val. Set up the descriptor like this:

struct s { int32_t foo; char *bar; } struct json_obj_descr descr[] = { JSON_OBJ_DESCR_PRIM(struct s, foo, JSON_TOK_NUMBER), JSON_OBJ_DESCR_PRIM(struct s, bar, JSON_TOK_STRING), }; struct a { struct s baz[10]; size_t count; } struct json_obj_descr array[] = { JSON_OBJ_DESCR_OBJ_ARRAY(struct a, baz, 10, count, descr, ARRAY_SIZE(descr)), };

Since this parser is designed for machine-to-machine communications, some liberties were taken to simplify the design: (1) strings are not unescaped (but only valid escape sequences are accepted); (2) no UTF-8 validation is performed; and (3) only integer numbers are supported (no strtod() in the minimal libc).

Parameters

json	Pointer to JSON-encoded array to be parsed
len	Length of JSON-encoded array
descr	Pointer to the descriptor array
val	Pointer to the struct to hold the decoded values

Returns

0 if array has been successfully parsed. A negative value indicates an error (as defined on errno.h).

json_arr_separate_object_parse_init()

int json_arr_separate_object_parse_init	(	struct json_obj *	json,
		char *	payload,
		size_t	len )

#include <zephyr/data/json.h>

Initialize single-object array parsing.

JSON-encoded array data is going to be parsed one object at a time. Data is provided by payload with the size of len bytes.

Function validate that Json Array start is detected and initialize json object for Json object parsing separately.

Parameters

json	Provide storage for parser states. To be used when parsing the array.
payload	Pointer to JSON-encoded array to be parsed
len	Length of JSON-encoded array

Returns

0 if array start is detected and initialization is successful or negative error code in case of failure.

json_arr_separate_parse_object()

int json_arr_separate_parse_object	(	struct json_obj *	json,
		const struct json_obj_descr *	descr,
		size_t	descr_len,
		void *	val )

#include <zephyr/data/json.h>

Parse a single object from array.

Parses the JSON-encoded object pointed to by json object array, with size len, according to the descriptor pointed to by descr.

Parameters

json	Pointer to JSON-object message state
descr	Pointer to the descriptor array
descr_len	Number of elements in the descriptor array. Must be less than 31.
val	Pointer to the struct to hold the decoded values

Returns

< 0 if error, 0 for end of message, bitmap of decoded fields on success (bit 0 is set if first field in the descriptor has been properly decoded, etc).

json_calc_encoded_arr_len()

ssize_t json_calc_encoded_arr_len	(	const struct json_obj_descr *	descr,
		const void *	val )

#include <zephyr/data/json.h>

Calculates the string length to fully encode an array.

Parameters

descr	Pointer to the descriptor array
val	Struct holding the values

Returns

Number of bytes necessary to encode the values if >0, an error code is returned.

json_calc_encoded_len()

ssize_t json_calc_encoded_len	(	const struct json_obj_descr *	descr,
		size_t	descr_len,
		const void *	val )

#include <zephyr/data/json.h>

Calculates the string length to fully encode an object.

Parameters

descr	Pointer to the descriptor array
descr_len	Number of elements in the descriptor array
val	Struct holding the values

Returns

Number of bytes necessary to encode the values if >0, an error code is returned.

json_calc_escaped_len()

size_t json_calc_escaped_len	(	const char *	str,
		size_t	len )

#include <zephyr/data/json.h>

Calculates the JSON-escaped string length.

Parameters

str	The string to analyze
len	String size

Returns

The length str would have if it were escaped

json_calc_mixed_arr_len()

ssize_t json_calc_mixed_arr_len	(	const struct json_mixed_arr_descr *	descr,
		size_t	descr_len,
		void *	val )

#include <zephyr/data/json.h>

Calculate the length of the encoded JSON mixed array.

This function calculates the number of bytes required to encode the given structure as a JSON mixed array, according to the provided descriptor.

Parameters

descr	Descriptor array describing the structure of the mixed array.
descr_len	Number of elements in the descriptor array.
val	Pointer to the structure to encode.

Returns

Number of bytes required for encoding, or negative error code.

json_escape()

ssize_t json_escape	(	char *	str,
		size_t *	len,
		size_t	buf_size )

#include <zephyr/data/json.h>

Escapes the string so it can be used to encode JSON objects.

Parameters

str	The string to escape; the escape string is stored the buffer pointed to by this parameter
len	Points to a size_t containing the size before and after the escaping process
buf_size	The size of buffer str points to

Returns

0 if string has been escaped properly, or -ENOMEM if there was not enough space to escape the buffer

json_mixed_arr_encode()

int json_mixed_arr_encode	(	const struct json_mixed_arr_descr *	descr,
		size_t	descr_len,
		void *	val,
		json_append_bytes_t	append_bytes,
		void *	data )

#include <zephyr/data/json.h>

Encode a C structure as a JSON mixed array.

This function encodes a C structure, described by the mixed array descriptor, as a JSON array.

Parameters

descr	Descriptor array describing the structure of the mixed array.
descr_len	Number of elements in the descriptor array.
val	Pointer to the structure to encode.
append_bytes	Function to append bytes to the output
data	Data pointer to be passed to the append_bytes callback function.

Returns

0 if mixed array has been successfully encoded. Negative error code on failure.

json_mixed_arr_encode_buf()

int json_mixed_arr_encode_buf	(	const struct json_mixed_arr_descr *	descr,
		size_t	descr_len,
		void *	val,
		char *	buffer,
		size_t	buf_size )

#include <zephyr/data/json.h>

Encode a C structure as a JSON mixed array into a buffer.

This function encodes a C structure, described by the mixed array descriptor, as a JSON array and writes the result into the provided buffer.

Parameters

descr	Descriptor array describing the structure of the mixed array.
descr_len	Number of elements in the descriptor array.
val	Pointer to the structure to encode.
buffer	Output buffer to write the JSON string.
buf_size	Size of the output buffer.

Returns

0 if mixed array has been successfully encoded. Negative error code on failure.

json_mixed_arr_parse()

int json_mixed_arr_parse	(	char *	json,
		size_t	len,
		const struct json_mixed_arr_descr *	descr,
		size_t	descr_len,
		void *	val )

#include <zephyr/data/json.h>

Parse a JSON mixed array into a C structure.

This function parses a JSON array (which may contain elements of varying types) according to the provided mixed array descriptor and stores the result in the user-supplied structure.

Parameters

json	Pointer to the input JSON string.
len	Length of the input JSON string.
descr	Descriptor array describing the structure of the mixed array.
descr_len	Number of elements in the descriptor array.
val	Pointer to the structure to populate with parsed data.

Returns

< 0 if error, number of elements parsed on success.

json_obj_encode()

int json_obj_encode	(	const struct json_obj_descr *	descr,
		size_t	descr_len,
		const void *	val,
		json_append_bytes_t	append_bytes,
		void *	data )

#include <zephyr/data/json.h>

Encodes an object using an arbitrary writer function.

Parameters

descr	Pointer to the descriptor array
descr_len	Number of elements in the descriptor array
val	Struct holding the values
append_bytes	Function to append bytes to the output
data	Data pointer to be passed to the append_bytes callback function.

Returns

0 if object has been successfully encoded. A negative value indicates an error.

json_obj_encode_buf()

int json_obj_encode_buf	(	const struct json_obj_descr *	descr,
		size_t	descr_len,
		const void *	val,
		char *	buffer,
		size_t	buf_size )

#include <zephyr/data/json.h>

Encodes an object in a contiguous memory location.

Parameters

descr	Pointer to the descriptor array
descr_len	Number of elements in the descriptor array
val	Struct holding the values
buffer	Buffer to store the JSON data
buf_size	Size of buffer, in bytes, with space for the terminating NUL character

Returns

0 if object has been successfully encoded. A negative value indicates an error (as defined on errno.h).

json_obj_parse()

int64_t json_obj_parse	(	char *	json,
		size_t	len,
		const struct json_obj_descr *	descr,
		size_t	descr_len,
		void *	val )

#include <zephyr/data/json.h>

Parses the JSON-encoded object pointed to by json, with size len, according to the descriptor pointed to by descr.

Values are stored in a struct pointed to by val. Set up the descriptor like this:

struct s { int32_t foo; char *bar; } struct json_obj_descr descr[] = { JSON_OBJ_DESCR_PRIM(struct s, foo, JSON_TOK_NUMBER), JSON_OBJ_DESCR_PRIM(struct s, bar, JSON_TOK_STRING), };

Since this parser is designed for machine-to-machine communications, some liberties were taken to simplify the design: (1) strings are not unescaped (but only valid escape sequences are accepted); (2) no UTF-8 validation is performed; and (3) only integer numbers are supported (no strtod() in the minimal libc).

Parameters

json	Pointer to JSON-encoded value to be parsed
len	Length of JSON-encoded value
descr	Pointer to the descriptor array
descr_len	Number of elements in the descriptor array. Must be less than 63 due to implementation detail reasons (if more fields are necessary, use two descriptors)
val	Pointer to the struct to hold the decoded values

Returns

< 0 if error, bitmap of decoded fields on success (bit 0 is set if first field in the descriptor has been properly decoded, etc).