The latest development version of this page may be more current than this released 3.7.0 version.

Miscellaneous

Checksum APIs

CRC

group crc

Enums

enum crc_type

CRC algorithm enumeration.

These values should be used with the CRC dispatch function.

Values:

enumerator CRC4

Use crc4.

enumerator CRC4_TI

Use crc4_ti.

enumerator CRC7_BE

Use crc7_be.

enumerator CRC8

Use crc8.

enumerator CRC8_CCITT

Use crc8_ccitt.

enumerator CRC16

Use crc16.

enumerator CRC16_ANSI

Use crc16_ansi.

enumerator CRC16_CCITT

Use crc16_ccitt.

enumerator CRC16_ITU_T

Use crc16_itu_t.

enumerator CRC24_PGP

Use crc24_pgp.

enumerator CRC32_C

Use crc32_c.

enumerator CRC32_IEEE

Use crc32_ieee.

Functions

uint16_t crc16(uint16_t poly, uint16_t seed, const uint8_t *src, size_t len)

Generic function for computing a CRC-16 without input or output reflection.

Compute CRC-16 by passing in the address of the input, the input length and polynomial used in addition to the initial value. This is O(n*8) where n is the length of the buffer provided. No reflection is performed.

Note

If you are planning to use a CRC based on poly 0x1012 the functions crc16_itu_t() is faster and thus recommended over this one.

Parameters:

  • poly – The polynomial to use omitting the leading x^16 coefficient

  • seed – Initial value for the CRC computation

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns:

The computed CRC16 value (without any XOR applied to it)

uint16_t crc16_reflect(uint16_t poly, uint16_t seed, const uint8_t *src, size_t len)

Generic function for computing a CRC-16 with input and output reflection.

Compute CRC-16 by passing in the address of the input, the input length and polynomial used in addition to the initial value. This is O(n*8) where n is the length of the buffer provided. Both input and output are reflected.

The following checksums can, among others, be calculated by this function, depending on the value provided for the initial seed and the value the final calculated CRC is XORed with:

Note

If you are planning to use a CRC based on poly 0x1012 the function crc16_ccitt() is faster and thus recommended over this one.

Parameters:

  • poly – The polynomial to use omitting the leading x^16 coefficient. Important: please reflect the poly. For example, use 0xA001 instead of 0x8005 for CRC-16-MODBUS.

  • seed – Initial value for the CRC computation

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns:

The computed CRC16 value (without any XOR applied to it)

uint8_t crc8(const uint8_t *src, size_t len, uint8_t polynomial, uint8_t initial_value, bool reversed)

Generic function for computing CRC 8.

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

Parameters:

  • src – Input bytes for the computation

  • len – Length of the input in bytes

  • polynomial – The polynomial to use omitting the leading x^8 coefficient

  • initial_value – Initial value for the CRC computation

  • reversed – Should we use reflected/reversed values or not

Returns:

The computed CRC8 value

uint16_t crc16_ccitt(uint16_t seed, const uint8_t *src, size_t len)

Compute the checksum of a buffer with polynomial 0x1021, reflecting input and output.

This function is able to calculate any CRC that uses 0x1021 as it polynomial and requires reflecting both the input and the output. It is a fast variant that runs in O(n) time, where n is the length of the input buffer.

The following checksums can, among others, be calculated by this function, depending on the value provided for the initial seed and the value the final calculated CRC is XORed with:

See ITU-T Recommendation V.41 (November 1988).

Note

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

Parameters:

  • seed – Value to seed the CRC with

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns:

The computed CRC16 value (without any XOR applied to it)

uint16_t crc16_itu_t(uint16_t seed, const uint8_t *src, size_t len)

Compute the checksum of a buffer with polynomial 0x1021, no reflection of input or output.

This function is able to calculate any CRC that uses 0x1021 as it polynomial and requires no reflection on both the input and the output. It is a fast variant that runs in O(n) time, where n is the length of the input buffer.

The following checksums can, among others, be calculated by this function, depending on the value provided for the initial seed and the value the final calculated CRC is XORed with:

See ITU-T Recommendation V.41 (November 1988) (MSB first).

Note

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

Parameters:

  • seed – Value to seed the CRC with

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns:

The computed CRC16 value (without any XOR applied to it)

static inline uint16_t crc16_ansi(const uint8_t *src, size_t len)

Compute the ANSI (or Modbus) variant of CRC-16.

The ANSI variant of CRC-16 uses 0x8005 (0xA001 reflected) as its polynomial with the initial * value set to 0xffff.

Parameters:

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns:

The computed CRC16 value

uint32_t crc32_ieee(const uint8_t *data, size_t len)

Generate IEEE conform CRC32 checksum.

Parameters:

  • data – Pointer to data on which the CRC should be calculated.

  • len – Data length.

Returns:

CRC32 value.

uint32_t crc32_ieee_update(uint32_t crc, const uint8_t *data, size_t len)

Update an IEEE conforming CRC32 checksum.

Parameters:

  • crc – CRC32 checksum that needs to be updated.

  • data – Pointer to data on which the CRC should be calculated.

  • len – Data length.

Returns:

CRC32 value.

uint32_t crc32_c(uint32_t crc, const uint8_t *data, size_t len, bool first_pkt, bool last_pkt)

Calculate CRC32C (Castagnoli) checksum.

Parameters:

  • crc – CRC32C checksum that needs to be updated.

  • data – Pointer to data on which the CRC should be calculated.

  • len – Data length.

  • first_pkt – Whether this is the first packet in the stream.

  • last_pkt – Whether this is the last packet in the stream.

Returns:

CRC32 value.

uint8_t crc8_ccitt(uint8_t initial_value, const void *buf, size_t len)

Compute CCITT variant of CRC 8.

Normal CCITT variant of CRC 8 is using 0x07.

Parameters:

  • initial_value – Initial value for the CRC computation

  • buf – Input bytes for the computation

  • len – Length of the input in bytes

Returns:

The computed CRC8 value

uint8_t crc7_be(uint8_t seed, const uint8_t *src, size_t len)

Compute the CRC-7 checksum of a buffer.

See JESD84-A441. Used by the MMC protocol. Uses 0x09 as the polynomial with no reflection. The CRC is left justified, so bit 7 of the result is bit 6 of the CRC.

Parameters:

  • seed – Value to seed the CRC with

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns:

The computed CRC7 value

uint8_t crc4_ti(uint8_t seed, const uint8_t *src, size_t len)

Compute the CRC-4 checksum of a buffer.

Used by the TMAG5170 sensor. Uses 0x03 as the polynomial with no reflection. 4 most significant bits of the CRC result will be set to zero.

Parameters:

  • seed – Value to seed the CRC with

  • src – Input bytes for the computation

  • len – Length of the input in bytes

Returns:

The computed CRC4 value

uint8_t crc4(const uint8_t *src, size_t len, uint8_t polynomial, uint8_t initial_value, bool reversed)

Generic function for computing CRC 4.

Compute CRC 4 by passing in the address of the input, the input length and polynomial used in addition to the initial value. The input buffer must be aligned to a whole byte. It is guaranteed that 4 most significant bits of the result will be set to zero.

Parameters:

  • src – Input bytes for the computation

  • len – Length of the input in bytes

  • polynomial – The polynomial to use omitting the leading x^4 coefficient

  • initial_value – Initial value for the CRC computation

  • reversed – Should we use reflected/reversed values or not

Returns:

The computed CRC4 value

uint32_t crc24_pgp(const uint8_t *data, size_t len)

Generate an OpenPGP CRC-24 checksum as defined in RFC 4880 section 6.1.

Parameters:

  • data – A pointer to the data on which the CRC will be calculated.

  • len – Data length in bytes.

Returns:

The CRC-24 value.

uint32_t crc24_pgp_update(uint32_t crc, const uint8_t *data, size_t len)

Update an OpenPGP CRC-24 checksum.

Parameters:

  • crc – The CRC-24 checksum that needs to be updated. The full 32-bit value of the CRC needs to be used between calls, do not mask the value to keep only the last 24 bits.

  • data – A pointer to the data on which the CRC will be calculated.

  • len – Data length in bytes.

Returns:

The CRC-24 value. When the last buffer of data has been processed, mask the value with CRC24_FINAL_VALUE_MASK to keep only the meaningful 24 bits of the CRC result.

static inline uint32_t crc_by_type(enum crc_type type, const uint8_t *src, size_t len, uint32_t seed, uint32_t poly, bool reflect, bool first, bool last)

Compute a CRC checksum, in a generic way.

This is a dispatch function that calls the individual CRC routine determined by type.

For 7, 8, 16 and 24-bit CRCs, the relevant seed and poly values should be passed in via the least-significant byte(s).

Similarly, for 7, 8, 16 and 24-bit CRCs, the relevant result is stored in the least-significant byte(s) of the returned value.

Parameters:

  • type – CRC algorithm to use.

  • src – Input bytes for the computation

  • len – Length of the input in bytes

  • seed – Value to seed the CRC with

  • poly – The polynomial to use omitting the leading coefficient

  • reflect – Should we use reflected/reversed values or not

  • first – Whether this is the first packet in the stream.

  • last – Whether this is the last packet in the stream.

Returns:

uint32_t the computed CRC value

Structured Data APIs

JSON

Related code samples

AWS IoT Core MQTT

Connect to AWS IoT Core and publish messages using MQTT.

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

Parameters:

  • struct_ – Struct packing the values

  • field_name_ – Field name in the struct

  • sub_descr_ – Array of json_obj_descr describing the subobject

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 {
     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)
 };

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

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

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

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

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

See also

JSON_OBJ_DESCR_ARRAY_ARRAY

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_

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 also

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 also

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 also

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

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.

Param bytes:

Contents to write to the output

Param len:

Number of bytes to append to output

Param data:

User-provided pointer

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.

Enums

enum json_tokens

Values:

enumerator JSON_TOK_NONE = '_'
enumerator JSON_TOK_OBJECT_START = '{'
enumerator JSON_TOK_OBJECT_END = '}'
enumerator JSON_TOK_ARRAY_START = '['
enumerator JSON_TOK_ARRAY_END = ']'
enumerator JSON_TOK_STRING = '"'
enumerator JSON_TOK_COLON = ':'
enumerator JSON_TOK_COMMA = ','
enumerator JSON_TOK_NUMBER = '0'
enumerator JSON_TOK_FLOAT = '1'
enumerator JSON_TOK_OPAQUE = '2'
enumerator JSON_TOK_OBJ_ARRAY = '3'
enumerator JSON_TOK_ENCODED_OBJ = '4'
enumerator JSON_TOK_TRUE = 't'
enumerator JSON_TOK_FALSE = 'f'
enumerator JSON_TOK_NULL = 'n'
enumerator JSON_TOK_ERROR = '!'
enumerator 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.

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

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.

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

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

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.

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.

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

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.

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

size_t json_calc_escaped_len(const char *str, size_t len)

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

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.

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.

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.

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.

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.

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

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.

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

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.

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.

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.

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.

struct json_token
#include <json.h>
struct json_lexer
#include <json.h>
struct json_obj
#include <json.h>
struct json_obj_token
#include <json.h>
struct json_obj_descr
#include <json.h>

JWT

JSON Web Tokens (JWT) are an open, industry standard [RFC 7519](https://tools.ietf.org/html/rfc7519) method for representing claims securely between two parties. Although JWT is fairly flexible, this API is limited to creating the simplistic tokens needed to authenticate with the Google Core IoT infrastructure.

group jwt

JSON Web Token (JWT)

Functions

int jwt_init_builder(struct jwt_builder *builder, char *buffer, size_t buffer_size)

Initialize the JWT builder.

Initialize the given JWT builder for the creation of a fresh token. The buffer size should at least be as long as JWT_BUILDER_MAX_SIZE returns.

Parameters:

  • builder – The builder to initialize.

  • buffer – The buffer to write the token to.

  • buffer_size – The size of this buffer. The token will be NULL terminated, which needs to be allowed for in this size.

Return values:

  • 0 – Success

  • -ENOSPC – Buffer is insufficient to initialize

int jwt_add_payload(struct jwt_builder *builder, int32_t exp, int32_t iat, const char *aud)

add JWT primary payload.

int jwt_sign(struct jwt_builder *builder, const char *der_key, size_t der_key_len)

Sign the JWT token.

static inline size_t jwt_payload_len(struct jwt_builder *builder)
struct jwt_builder
#include <jwt.h>

JWT data tracking.

JSON Web Tokens contain several sections, each encoded in base-64. This structure tracks the token as it is being built, including limits on the amount of available space. It should be initialized with jwt_init().

Public Members

char *base

The base of the buffer we are writing to.

char *buf

The place in this buffer where we are currently writing.

size_t len

The length remaining to write.

bool overflowed

Flag that is set if we try to write past the end of the buffer.

If set, the token is not valid.