Encoding to CBOR

Group of functions used to encode data to CBOR. More...

## Data Structures

struct | CborEncoder
| Structure used to encode to CBOR. More...

## Functions

void | cbor_encoder_init (CborEncoder *encoder, uint8_t *buffer, size_t size, int flags)
| Initializes a CborEncoder structure encoder by pointing it to buffer buffer of size size.
CborError | cbor_encode_uint (CborEncoder *encoder, uint64_t value)
| Appends the unsigned 64-bit integer value to the CBOR stream provided by encoder.
CborError | cbor_encode_negative_int (CborEncoder *encoder, uint64_t absolute_value)
| Appends the negative 64-bit integer whose absolute value is absolute_value to the CBOR stream provided by encoder.
CborError | cbor_encode_int (CborEncoder *encoder, int64_t value)
| Appends the signed 64-bit integer value to the CBOR stream provided by encoder.
CborError | cbor_encode_simple_value (CborEncoder *encoder, uint8_t value)
| Appends the CBOR Simple Type of value value to the CBOR stream provided by encoder.
CborError | cbor_encode_floating_point (CborEncoder *encoder, CborType fpType, const void *value)
| Appends the floating-point value of type fpType and pointed to by value to the CBOR stream provided by encoder.
CborError | cbor_encode_tag (CborEncoder *encoder, CborTag tag)
| Appends the CBOR tag tag to the CBOR stream provided by encoder.
CborError | cbor_encode_byte_string (CborEncoder *encoder, const uint8_t *string, size_t length)
| Appends the byte string string of length length to the CBOR stream provided by encoder.
CborError | cbor_encode_text_string (CborEncoder *encoder, const char *string, size_t length)
| Appends the text string string of length length to the CBOR stream provided by encoder.
CborError | cbor_encoder_create_array (CborEncoder *parentEncoder, CborEncoder *arrayEncoder, size_t length)
| Creates a CBOR array in the CBOR stream provided by parentEncoder and initializes arrayEncoder so that items can be added to the array using the CborEncoder functions.
CborError | cbor_encoder_create_map (CborEncoder *parentEncoder, CborEncoder *mapEncoder, size_t length)
| Creates a CBOR map in the CBOR stream provided by parentEncoder and initializes mapEncoder so that items can be added to the map using the CborEncoder functions.
CborError | cbor_encoder_close_container (CborEncoder *parentEncoder, const CborEncoder *containerEncoder)
| Closes the CBOR container (array or map) provided by containerEncoder and updates the CBOR stream provided by encoder.
CborError | cbor_encoder_close_container_checked (CborEncoder *encoder, const CborEncoder *containerEncoder)
CborError | cbor_encode_text_stringz (CborEncoder *encoder, const char *string)
| Appends the null-terminated text string string to the CBOR stream provided by encoder.
CborError | cbor_encode_boolean (CborEncoder *encoder, bool value)
| Appends the boolean value value to the CBOR stream provided by encoder.
CborError | cbor_encode_null (CborEncoder *encoder)
| Appends the CBOR type representing a null value to the CBOR stream provided by encoder.
CborError | cbor_encode_undefined (CborEncoder *encoder)
| Appends the CBOR type representing an undefined value to the CBOR stream provided by encoder.
CborError | cbor_encode_half_float (CborEncoder *encoder, const void *value)
| Appends the IEEE 754 half-precision (16-bit) floating point value pointed to by value to the CBOR stream provided by encoder.
CBOR_API CborError | cbor_encode_float_as_half_float (CborEncoder *encoder, float value)
| Convert the IEEE 754 single-precision (32-bit) floating point value value to the IEEE 754 half-precision (16-bit) floating point value and append it to the CBOR stream provided by encoder.
CborError | cbor_encode_float (CborEncoder *encoder, float value)
| Appends the IEEE 754 single-precision (32-bit) floating point value value to the CBOR stream provided by encoder.
CborError | cbor_encode_double (CborEncoder *encoder, double value)
| Appends the IEEE 754 double-precision (64-bit) floating point value value to the CBOR stream provided by encoder.
size_t | cbor_encoder_get_buffer_size (const CborEncoder *encoder, const uint8_t *buffer)
| Returns the total size of the buffer starting at buffer after the encoding finished without errors.
size_t | cbor_encoder_get_extra_bytes_needed (const CborEncoder *encoder)
| Returns how many more bytes the original buffer supplied to cbor_encoder_init() needs to be extended by so that no CborErrorOutOfMemory condition will happen for the encoding.

## Detailed Description

Group of functions used to encode data to CBOR.

CborEncoder is used to encode data into a CBOR stream. The outermost CborEncoder is initialized by calling cbor_encoder_init(), with the buffer where the CBOR stream will be stored. The outermost CborEncoder is usually used to encode exactly one item, most often an array or map. It is possible to encode more than one item, but care must then be taken on the decoder side to ensure the state is reset after each item was decoded.

Nested CborEncoder objects are created using cbor_encoder_create_array() and cbor_encoder_create_map(), later closed with cbor_encoder_close_container() or cbor_encoder_close_container_checked(). The pairs of creation and closing must be exactly matched and their parameters are always the same.

CborEncoder writes directly to the user-supplied buffer, without extra buffering. CborEncoder does not allocate memory and CborEncoder objects are usually created on the stack of the encoding functions.

The example below initializes a CborEncoder object with a buffer and encodes a single integer.

uint8_t buf[16];
CborEncoder encoder;
cbor_encoder_init(&encoder, buf, sizeof(buf), 0);
cbor_encode_int(&encoder, some_value);
cbor_encoder_init
CBOR_API void cbor_encoder_init(CborEncoder *encoder, uint8_t *buffer, size_t size, int flags)
Initializes a CborEncoder structure encoder by pointing it to buffer buffer of size size.
Definition cborencoder.c:204
cbor_encode_int
CBOR_API CborError cbor_encode_int(CborEncoder *encoder, int64_t value)
Appends the signed 64-bit integer value to the CBOR stream provided by encoder.
Definition cborencoder.c:381
CborEncoder
Structure used to encode to CBOR.
Definition cbor.h:227

As explained before, usually the outermost CborEncoder object is used to add one array or map, which in turn contains multiple elements. The example below creates a CBOR map with one element: a key "foo" and a boolean value.

uint8_t buf[16];
CborEncoder encoder, mapEncoder;
cbor_encoder_init(&encoder, buf, sizeof(buf), 0);
cbor_encoder_create_map(&encoder, &mapEncoder, 1);
cbor_encode_text_stringz(&mapEncoder, "foo");
cbor_encode_boolean(&mapEncoder, some_value);
cbor_encoder_close_container(&encoder, &mapEncoder);
cbor_encode_text_stringz
CborError cbor_encode_text_stringz(CborEncoder *encoder, const char *string)
Appends the null-terminated text string string to the CBOR stream provided by encoder.
Definition cbor.h:250
cbor_encoder_close_container
CBOR_API CborError cbor_encoder_close_container(CborEncoder *parentEncoder, const CborEncoder *containerEncoder)
Closes the CBOR container (array or map) provided by containerEncoder and updates the CBOR stream pro...
Definition cborencoder.c:575
cbor_encode_boolean
CborError cbor_encode_boolean(CborEncoder *encoder, bool value)
Appends the boolean value value to the CBOR stream provided by encoder.
Definition cbor.h:255
cbor_encoder_create_map
CBOR_API CborError cbor_encoder_create_map(CborEncoder *parentEncoder, CborEncoder *mapEncoder, size_t length)
Creates a CBOR map in the CBOR stream provided by parentEncoder and initializes mapEncoder so that it...
Definition cborencoder.c:556

### Error checking and buffer size

All functions operating on CborEncoder return a condition of type CborError. If the encoding was successful, they return CborNoError. Some functions do extra checking on the input provided and may return some other error conditions (for example, cbor_encode_simple_value() checks that the type is of the correct type).

In addition, all functions check whether the buffer has enough bytes to encode the item being appended. If that is not possible, they return CborErrorOutOfMemory.

It is possible to continue with the encoding of data past the first function that returns CborErrorOutOfMemory. CborEncoder functions will not overrun the buffer, but will instead count how many more bytes are needed to complete the encoding. At the end, you can obtain that count by calling cbor_encoder_get_extra_bytes_needed().

# the encoding

Once all items have been appended and the containers have all been properly closed, the user-supplied buffer will contain the CBOR stream and may be immediately used. To obtain the size of the buffer, call cbor_encoder_get_buffer_size() with the original buffer pointer.

The example below illustrates how one can encode an item with error checking and then pass on the buffer for network sending.

uint8_t buf[16];
CborError err;
CborEncoder encoder, mapEncoder;
cbor_encoder_init(&encoder, buf, sizeof(buf), 0);
err = cbor_encoder_create_map(&encoder, &mapEncoder, 1);
if (err)
return err;
err = cbor_encode_text_stringz(&mapEncoder, "foo");
if (err)
return err;
err = cbor_encode_boolean(&mapEncoder, some_value);
if (err)
return err;
err = cbor_encoder_close_container_checked(&encoder, &mapEncoder);
if (err)
return err;
size_t len = cbor_encoder_get_buffer_size(&encoder, buf);
send_payload(buf, len);
return CborNoError;
cbor_encoder_get_buffer_size
size_t cbor_encoder_get_buffer_size(const CborEncoder *encoder, const uint8_t *buffer)
Returns the total size of the buffer starting at buffer after the encoding finished without errors.
Definition cbor.h:280
cbor_encoder_close_container_checked
CBOR_API CborError cbor_encoder_close_container_checked(CborEncoder *parentEncoder, const CborEncoder *containerEncoder)
Definition cborencoder_close_container_checked.c:53

Finally, the example below expands on the one above and also deals with dynamically growing the buffer if the initial allocation wasn't big enough. Note the two places where the error checking was replaced with an cbor_assertion, showing where the author assumes no error can occur.

uint8_t *encode_string_array(const char **strings, int n, size_t *bufsize)
{
CborError err;
CborEncoder encoder, arrayEncoder;
size_t size = 256;
uint8_t *buf = NULL;
while (1) {
int i;
size_t more_bytes;
uint8_t *nbuf = realloc(buf, size);
if (nbuf == NULL)
goto error;
buf = nbuf;
cbor_encoder_init(&encoder, buf, size, 0);
err = cbor_encoder_create_array(&encoder, &arrayEncoder, n);
cbor_assert(!err); // can't fail, the buffer is always big enough
for (i = 0; i < n; ++i) {
err = cbor_encode_text_stringz(&arrayEncoder, strings[i]);
if (err && err != CborErrorOutOfMemory)
goto error;
}
err = cbor_encoder_close_container_checked(&encoder, &arrayEncoder);
cbor_assert(!err); // shouldn't fail!
more_bytes = cbor_encoder_get_extra_bytes_needed(encoder);
if (more_size) {
// buffer wasn't big enough, try again
size += more_bytes;
continue;
}
*bufsize = cbor_encoder_get_buffer_size(encoder, buf);
return buf;
}
error:
free(buf);
return NULL;
}
cbor_encoder_create_array
CBOR_API CborError cbor_encoder_create_array(CborEncoder *parentEncoder, CborEncoder *arrayEncoder, size_t length)
Creates a CBOR array in the CBOR stream provided by parentEncoder and initializes arrayEncoder so tha...
Definition cborencoder.c:532
cbor_encoder_get_extra_bytes_needed
size_t cbor_encoder_get_extra_bytes_needed(const CborEncoder *encoder)
Returns how many more bytes the original buffer supplied to cbor_encoder_init() needs to be extended ...
Definition cbor.h:285

## Function Documentation

## cbor_encode_byte_string()

CborError cbor_encode_byte_string | ( | CborEncoder * | encoder,
|  | const uint8_t * | string,
|  | size_t | length )

Appends the byte string string of length length to the CBOR stream provided by encoder.

CBOR byte strings are arbitrary raw data.

See also
  cbor_encode_text_stringz, cbor_encode_text_string

## cbor_encode_double()

CborError cbor_encode_double | ( | CborEncoder * | encoder,
|  | double | value )

Appends the IEEE 754 double-precision (64-bit) floating point value value to the CBOR stream provided by encoder.

See also
  cbor_encode_floating_point(), cbor_encode_half_float(), cbor_encode_float_as_half_float(), cbor_encode_float()

## cbor_encode_float()

CborError cbor_encode_float | ( | CborEncoder * | encoder,
|  | float | value )

Appends the IEEE 754 single-precision (32-bit) floating point value value to the CBOR stream provided by encoder.

See also
  cbor_encode_floating_point(), cbor_encode_half_float(), cbor_encode_float_as_half_float(), cbor_encode_double()

## cbor_encode_float_as_half_float()

CBOR_API CborError cbor_encode_float_as_half_float | ( | CborEncoder * | encoder,
|  | float | value )

Convert the IEEE 754 single-precision (32-bit) floating point value value to the IEEE 754 half-precision (16-bit) floating point value and append it to the CBOR stream provided by encoder.

The value should be in the range of the IEEE 754 half-precision floating point type, INFINITY, -INFINITY, or NAN, otherwise the behavior of this function is undefined.

See also
  cbor_encode_floating_point(), cbor_encode_float(), cbor_encode_double()

## cbor_encode_floating_point()

CborError cbor_encode_floating_point | ( | CborEncoder * | encoder,
|  | CborType | fpType,
|  | const void * | value )

Appends the floating-point value of type fpType and pointed to by value to the CBOR stream provided by encoder.

The value of fpType must be one of CborHalfFloatType, CborFloatType or CborDoubleType, otherwise the behavior of this function is undefined.

This function is useful for code that needs to pass through floating point values but does not wish to have the actual floating-point code.

See also
  cbor_encode_half_float, cbor_encode_float_as_half_float, cbor_encode_float, cbor_encode_double

Referenced by cbor_encode_double(), cbor_encode_float(), cbor_encode_float_as_half_float(), and cbor_encode_half_float().

## cbor_encode_half_float()

CborError cbor_encode_half_float | ( | CborEncoder * | encoder,
|  | const void * | value )

Appends the IEEE 754 half-precision (16-bit) floating point value pointed to by value to the CBOR stream provided by encoder.

See also
  cbor_encode_floating_point(), cbor_encode_float(), cbor_encode_double()

## cbor_encode_int()

CborError cbor_encode_int | ( | CborEncoder * | encoder,
|  | int64_t | value )

Appends the signed 64-bit integer value to the CBOR stream provided by encoder.

See also
  cbor_encode_negative_int, cbor_encode_uint

## cbor_encode_negative_int()

CborError cbor_encode_negative_int | ( | CborEncoder * | encoder,
|  | uint64_t | absolute_value )

Appends the negative 64-bit integer whose absolute value is absolute_value to the CBOR stream provided by encoder.

If the value absolute_value is zero, this function encodes -2^64.

See also
  cbor_encode_uint, cbor_encode_int

## cbor_encode_null()

CborError cbor_encode_null | ( | CborEncoder * | encoder | ) |

Appends the CBOR type representing a null value to the CBOR stream provided by encoder.

See also
  cbor_encode_undefined()

## cbor_encode_simple_value()

CborError cbor_encode_simple_value | ( | CborEncoder * | encoder,
|  | uint8_t | value )

Appends the CBOR Simple Type of value value to the CBOR stream provided by encoder.

This function may return error CborErrorIllegalSimpleType if the value variable contains a number that is not a valid simple type.

Referenced by cbor_encode_boolean(), cbor_encode_null(), and cbor_encode_undefined().

## cbor_encode_tag()

CborError cbor_encode_tag | ( | CborEncoder * | encoder,
|  | CborTag | tag )

Appends the CBOR tag tag to the CBOR stream provided by encoder.

See also
  CborTag

## cbor_encode_text_string()

CborError cbor_encode_text_string | ( | CborEncoder * | encoder,
|  | const char * | string,
|  | size_t | length )

Appends the text string string of length length to the CBOR stream provided by encoder.

CBOR requires that string be valid UTF-8, but TinyCBOR makes no verification of correctness.

See also
  CborError cbor_encode_text_stringz, cbor_encode_byte_string

Referenced by cbor_encode_text_stringz().

## cbor_encode_text_stringz()

CborError cbor_encode_text_stringz | ( | CborEncoder * | encoder,
|  | const char * | string )

Appends the null-terminated text string string to the CBOR stream provided by encoder.

CBOR requires that string be valid UTF-8, but TinyCBOR makes no verification of correctness. The terminating null is not included in the stream.

See also
  cbor_encode_text_string, cbor_encode_byte_string

## cbor_encode_uint()

CborError cbor_encode_uint | ( | CborEncoder * | encoder,
|  | uint64_t | value )

Appends the unsigned 64-bit integer value to the CBOR stream provided by encoder.

See also
  cbor_encode_negative_int, cbor_encode_int

## cbor_encode_undefined()

CborError cbor_encode_undefined | ( | CborEncoder * | encoder | ) |

Appends the CBOR type representing an undefined value to the CBOR stream provided by encoder.

See also
  cbor_encode_null()

## cbor_encoder_close_container()

CborError cbor_encoder_close_container | ( | CborEncoder * | parentEncoder,
|  | const CborEncoder * | containerEncoder )

Closes the CBOR container (array or map) provided by containerEncoder and updates the CBOR stream provided by encoder.

Both parameters must be the same as were passed to cbor_encoder_create_array() or cbor_encoder_create_map().

Since version 0.5, this function verifies that the number of items (or pairs of items, in the case of a map) was correct. It is no longer necessary to call cbor_encoder_close_container_checked() instead.

See also
  cbor_encoder_create_array(), cbor_encoder_create_map()

Referenced by cbor_encoder_close_container_checked().

## cbor_encoder_close_container_checked()

CborError cbor_encoder_close_container_checked | ( | CborEncoder * | encoder,
|  | const CborEncoder * | containerEncoder )

Closes the CBOR container (array or map) provided by containerEncoder and updates the CBOR stream provided by encoder. Both parameters must be the same as were passed to cbor_encoder_create_array() or cbor_encoder_create_map().

Prior to version 0.5, cbor_encoder_close_container() did not check the number of items added. Since that version, it does and now cbor_encoder_close_container_checked() is no longer needed.

See also
  cbor_encoder_create_array(), cbor_encoder_create_map()

## cbor_encoder_create_array()

CborError cbor_encoder_create_array | ( | CborEncoder * | parentEncoder,
|  | CborEncoder * | arrayEncoder,
|  | size_t | length )

Creates a CBOR array in the CBOR stream provided by parentEncoder and initializes arrayEncoder so that items can be added to the array using the CborEncoder functions.

The array must be terminated by calling either cbor_encoder_close_container() or cbor_encoder_close_container_checked() with the same encoder and arrayEncoder parameters.

The number of items inserted into the array must be exactly length items, otherwise the stream is invalid. If the number of items is not known when creating the array, the constant CborIndefiniteLength may be passed as length instead, and an indefinite length array is created.

See also
  cbor_encoder_create_map

## cbor_encoder_create_map()

CborError cbor_encoder_create_map | ( | CborEncoder * | parentEncoder,
|  | CborEncoder * | mapEncoder,
|  | size_t | length )

Creates a CBOR map in the CBOR stream provided by parentEncoder and initializes mapEncoder so that items can be added to the map using the CborEncoder functions.

The map must be terminated by calling either cbor_encoder_close_container() or cbor_encoder_close_container_checked() with the same encoder and mapEncoder parameters.

The number of pair of items inserted into the map must be exactly length items, otherwise the stream is invalid. If the number is not known when creating the map, the constant CborIndefiniteLength may be passed as length instead, and an indefinite length map is created.

Implementation limitation: TinyCBOR cannot encode more than SIZE_MAX/2 key-value pairs in the stream. If the length length is larger than this value (and is not CborIndefiniteLength), this function returns error CborErrorDataTooLarge.

See also
  cbor_encoder_create_array

## cbor_encoder_get_buffer_size()

size_t cbor_encoder_get_buffer_size | ( | const CborEncoder * | encoder,
|  | const uint8_t * | buffer )

Returns the total size of the buffer starting at buffer after the encoding finished without errors.

The encoder and buffer arguments must be the same as supplied to cbor_encoder_init().

If the encoding process had errors, the return value of this function is meaningless. If the only errors were CborErrorOutOfMemory, instead use cbor_encoder_get_extra_bytes_needed() to find out by how much to grow the buffer before encoding again.

See Encoding to CBOR for an example of using this function.

See also
  cbor_encoder_init(), cbor_encoder_get_extra_bytes_needed(), Encoding to CBOR

## cbor_encoder_get_extra_bytes_needed()

size_t cbor_encoder_get_extra_bytes_needed | ( | const CborEncoder * | encoder | ) |

Returns how many more bytes the original buffer supplied to cbor_encoder_init() needs to be extended by so that no CborErrorOutOfMemory condition will happen for the encoding.

If the buffer was big enough, this function returns 0. The encoder must be the original argument as passed to cbor_encoder_init().

This function is usually called after an encoding sequence ended with one or more CborErrorOutOfMemory errors, but no other error. If any other error happened, the return value of this function is meaningless.

See Encoding to CBOR for an example of using this function.

See also
  cbor_encoder_init(), cbor_encoder_get_buffer_size(), Encoding to CBOR

## cbor_encoder_init()

void cbor_encoder_init | ( | CborEncoder * | encoder,
|  | uint8_t * | buffer,
|  | size_t | size,
|  | int | flags )

Initializes a CborEncoder structure encoder by pointing it to buffer buffer of size size.

The flags field is currently unused and must be zero.