TinyCBOR 0.6.0 API
Data Structures | Functions
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)
 

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

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

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

◆ 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

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