Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS

Data Structures

struct  json_obj_descr
 

Macros

#define JSON_OBJ_DESCR_PRIM(struct_, field_name_, type_)
 Helper macro to declare a descriptor for supported primitive values. More...
 
#define JSON_OBJ_DESCR_OBJECT(struct_, field_name_, sub_descr_)
 Helper macro to declare a descriptor for an object value. More...
 
#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. More...
 
#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. More...
 
#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. More...
 
#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. More...
 
#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. More...
 
#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. More...
 
#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. More...
 

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

Enumerations

enum  json_tokens {
  JSON_TOK_NONE = '_' , JSON_TOK_OBJECT_START = '{' , JSON_TOK_OBJECT_END = '}' , JSON_TOK_LIST_START = '[' ,
  JSON_TOK_LIST_END = ']' , JSON_TOK_STRING = '"' , JSON_TOK_COLON = ':' , JSON_TOK_COMMA = ',' ,
  JSON_TOK_NUMBER = '0' , JSON_TOK_TRUE = 't' , JSON_TOK_FALSE = 'f' , JSON_TOK_NULL = 'n' ,
  JSON_TOK_ERROR = '!' , JSON_TOK_EOF = '\0'
}
 

Functions

int 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 pointer 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: More...
 
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. More...
 
size_t json_calc_escaped_len (const char *str, size_t len)
 Calculates the JSON-escaped string length. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

Detailed Description

Macro Definition Documentation

◆ JSON_OBJ_DESCR_ARRAY

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

#include <include/data/json.h>

Value:
{ \
.field_name = (#field_name_), \
.align_shift = Z_ALIGN_SHIFT(struct_), \
.field_name_len = sizeof(#field_name_) - 1, \
.offset = offsetof(struct_, field_name_), \
{ \
.array = { \
.element_descr = (struct json_obj_descr[]) { { \
.align_shift = \
Z_ALIGN_SHIFT(struct_), \
.type = elem_type_, \
.offset = \
offsetof(struct_, \
len_field_), \
} }, \
.n_elements = (max_len_), \
}, \
}, \
}
@ JSON_TOK_LIST_START
Definition: json.h:40
Definition: json.h:53

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 {
     int 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 <include/data/json.h>

Value:
{ \
.field_name = (#field_name_), \
.align_shift = Z_ALIGN_SHIFT(struct_), \
.field_name_len = sizeof(#field_name_) - 1, \
.offset = offsetof(struct_, field_name_), \
{ \
.array = { \
.element_descr = (struct json_obj_descr[]) { { \
.align_shift = \
Z_ALIGN_SHIFT(struct_), \
.offset = offsetof(struct_, \
len_field_), \
{ \
.array = { \
.element_descr = \
elem_descr_, \
.n_elements = \
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;
     int 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_heigth_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_NAMED

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

#include <include/data/json.h>

Value:
{ \
.field_name = (json_field_name_), \
.align_shift = Z_ALIGN_SHIFT(struct_), \
.field_name_len = sizeof(json_field_name_) - 1, \
.offset = offsetof(struct_, struct_field_name_), \
{ \
.array = { \
.element_descr = (struct json_obj_descr[]) { { \
.align_shift = \
Z_ALIGN_SHIFT(struct_), \
.type = elem_type_, \
.offset = offsetof(struct_, \
len_field_), \
} }, \
.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 <include/data/json.h>

Value:
{ \
.field_name = (#field_name_), \
.align_shift = Z_ALIGN_SHIFT(struct_), \
.field_name_len = sizeof(#field_name_) - 1, \
.offset = offsetof(struct_, field_name_), \
{ \
.array = { \
.element_descr = (struct json_obj_descr[]) { { \
.align_shift = \
Z_ALIGN_SHIFT(struct_), \
.offset = offsetof(struct_, \
len_field_), \
{ \
.object = { \
.sub_descr = \
elem_descr_, \
.sub_descr_len = \
elem_descr_len_, \
}, \
}, \
} }, \
.n_elements = (max_len_), \
}, \
}, \
}
@ JSON_TOK_OBJECT_START
Definition: json.h:38

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;
     int 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 <include/data/json.h>

Value:
{ \
.field_name = json_field_name_, \
.align_shift = Z_ALIGN_SHIFT(struct_), \
.field_name_len = sizeof(json_field_name_) - 1, \
.offset = offsetof(struct_, struct_field_name_), \
{ \
.array = { \
.element_descr = (struct json_obj_descr[]) { { \
.align_shift = \
Z_ALIGN_SHIFT(struct_), \
.offset = offsetof(struct_, \
len_field_), \
{ \
.object = { \
.sub_descr = \
elem_descr_, \
.sub_descr_len = \
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;
     int 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 <include/data/json.h>

Value:
{ \
.field_name = (#field_name_), \
.align_shift = Z_ALIGN_SHIFT(struct_), \
.field_name_len = (sizeof(#field_name_) - 1), \
.offset = offsetof(struct_, field_name_), \
{ \
.object = { \
.sub_descr = sub_descr_, \
.sub_descr_len = ARRAY_SIZE(sub_descr_), \
}, \
}, \
}
#define ARRAY_SIZE(array)
Number of elements in the given array.
Definition: util.h:92

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 {
     int foo;
     struct {
        int 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 <include/data/json.h>

Value:
{ \
.field_name = (json_field_name_), \
.align_shift = Z_ALIGN_SHIFT(struct_), \
.field_name_len = (sizeof(json_field_name_) - 1), \
.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 <include/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_), \
}

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 {
    int 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 <include/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_), \
}

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 <include/data/json.h>

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

Parameters
bytesContents to write to the output
lenNumber of bytes to append to output
dataUser-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

#include <include/data/json.h>

Enumerator
JSON_TOK_NONE 
JSON_TOK_OBJECT_START 
JSON_TOK_OBJECT_END 
JSON_TOK_LIST_START 
JSON_TOK_LIST_END 
JSON_TOK_STRING 
JSON_TOK_COLON 
JSON_TOK_COMMA 
JSON_TOK_NUMBER 
JSON_TOK_TRUE 
JSON_TOK_FALSE 
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 <include/data/json.h>

Encodes an array using an arbitrary writer function.

Parameters
descrPointer to the descriptor array
valStruct holding the values
append_bytesFunction to append bytes to the output
dataData 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 <include/data/json.h>

Encodes an array in a contiguous memory location.

Parameters
descrPointer to the descriptor array
valStruct holding the values
bufferBuffer to store the JSON data
buf_sizeSize 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_calc_encoded_len()

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

#include <include/data/json.h>

Calculates the string length to fully encode an object.

Parameters
descrPointer to the descriptor array
descr_lenNumber of elements in the descriptor array
valStruct 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 <include/data/json.h>

Calculates the JSON-escaped string length.

Parameters
strThe string to analyze
lenString size
Returns
The length str would have if it were escaped

◆ json_escape()

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

#include <include/data/json.h>

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

Parameters
strThe string to escape; the escape string is stored the buffer pointed to by this parameter
lenPoints to a size_t containing the size before and after the escaping process
buf_sizeThe 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_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 <include/data/json.h>

Encodes an object using an arbitrary writer function.

Parameters
descrPointer to the descriptor array
descr_lenNumber of elements in the descriptor array
valStruct holding the values
append_bytesFunction to append bytes to the output
dataData 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 <include/data/json.h>

Encodes an object in a contiguous memory location.

Parameters
descrPointer to the descriptor array
descr_lenNumber of elements in the descriptor array
valStruct holding the values
bufferBuffer to store the JSON data
buf_sizeSize 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()

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

#include <include/data/json.h>

Parses the JSON-encoded object pointer 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 { int 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
jsonPointer to JSON-encoded value to be parsed
lenLength of JSON-encoded value
descrPointer to the descriptor array
descr_lenNumber of elements in the descriptor array. Must be less than 31 due to implementation detail reasons (if more fields are necessary, use two descriptors)
valPointer 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).