Miscellaneous APIs

Checksum APIs

CRC16

group crc16

Functions

u16_t crc16(const u8_t *src, size_t len, u16_t polynomial, u16_t initial_value, bool pad)

Generic function for computing CRC 16.

Compute CRC 16 by passing in the address of the input, the input length and polynomial used in addition to the initial value.

Return
The computed CRC16 value
Parameters
  • src: Input bytes for the computation
  • len: Length of the input in bytes
  • polynomial: The polynomial to use omitting the leading x^16 coefficient
  • initial_value: Initial value for the CRC computation
  • pad: Adds padding with zeros at the end of input bytes

u16_t crc16_ccitt(u16_t seed, const u8_t *src, size_t len)

Compute the CRC-16/CCITT checksum of a buffer.

See ITU-T Recommendation V.41 (November 1988). Uses 0x1021 as the polynomial, reflects the input, and reflects the output.

To calculate the CRC across non-contiguous blocks use the return value from block N-1 as the seed for block N.

For CRC-16/CCITT, use 0 as the initial seed. Other checksums in the same family can be calculated by changing the seed and/or XORing the final value. Examples include:

  • X-25 (used in PPP): seed=0xffff, xor=0xffff, residual=0xf0b8

Note
API changed in Zephyr 1.11.
Return
The computed CRC16 value
Parameters
  • seed: Value to seed the CRC with
  • src: Input bytes for the computation
  • len: Length of the input in bytes

u16_t crc16_itu_t(u16_t seed, const u8_t *src, size_t len)

Compute the CRC-16/XMODEM checksum of a buffer.

The MSB first version of ITU-T Recommendation V.41 (November 1988). Uses 0x1021 as the polynomial with no reflection.

To calculate the CRC across non-contiguous blocks use the return value from block N-1 as the seed for block N.

For CRC-16/XMODEM, use 0 as the initial seed. Other checksums in the same family can be calculated by changing the seed and/or XORing the final value. Examples include:

  • CCIITT-FALSE: seed=0xffff
  • GSM: seed=0, xorout=0xffff, residue=0x1d0f

Return
The computed CRC16 value
Parameters
  • seed: Value to seed the CRC with
  • src: Input bytes for the computation
  • len: Length of the input in bytes

static u16_t crc16_ansi(const u8_t *src, size_t len)

Compute ANSI variant of CRC 16.

ANSI variant of CRC 16 is using 0x8005 as its polynomial with the initial value set to 0xffff.

Return
The computed CRC16 value
Parameters
  • src: Input bytes for the computation
  • len: Length of the input in bytes

Structured Data APIs

JSON

group json

Defines

JSON_OBJ_DESCR_PRIM(struct_, field_name_, type_)

Helper macro to declare a descriptor for supported primitive values.

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),
};
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.

JSON_OBJ_DESCR_OBJECT(struct_, field_name_, sub_descr_)

Helper macro to declare a descriptor for an object value.

Here’s an example of use: struct nested { int foo; struct { int baz; } bar; };

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

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_ARRAY(struct_, field_name_, max_len_, len_field_, elem_type_)

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

Here’s an example of use: struct example { int foo[10]; size_t foo_len; };

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

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

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.

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)),
 };
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_

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.

Here’s an example of use: 

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

 struct person_heigths_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_heigths_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)),
 };
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_

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.

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

See
JSON_OBJ_DESCR_PRIM
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.

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.

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

See
JSON_OBJ_DESCR_OBJECT
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

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.

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

See
JSON_OBJ_DESCR_ARRAY
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

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.

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

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)),
 };
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_

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.

Return
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.
Parameters
  • bytes: Contents to write to the output
  • len: Number of bytes in
  • bytes: to append to output
  • data: User-provided pointer

Enums

enum json_tokens

Values:

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:

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

Return
< 0 if error, bitmap of decoded fields on success (bit 0 is set if first field in the descriptor has been properly decoded, etc).
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 31 due to implementation detail reasons (if more fields are necessary, use two descriptors)
  • val: Pointer to the struct to hold the decoded values

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.

Return
0 if string has been escaped properly, or -ENOMEM if there was not enough space to escape the buffer
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

size_t json_calc_escaped_len(const char *str, size_t len)

Calculates the JSON-escaped string length.

Return
The length str would have if it were escaped
Parameters
  • str: The string to analyze
  • len: String size

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.

Return
Number of bytes necessary to encode the values if >0, an error code is returned.
Parameters
  • descr: Pointer to the descriptor array
  • descr_len: Number of elements in the descriptor array
  • val: Struct holding the values

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.

Return
0 if object has been successfully encoded. A negative value indicates an error (as defined on errno.h).
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

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.

Return
0 if object has been successfully encoded. A negative value indicates an error.
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.