Encoding to CBOR

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 cborencoder.c::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 cborencoder.c::cbor_encoder_create_array() and cborencoder.c::cbor_encoder_create_map(), later closed with cborencoder.c::cbor_encoder_close_container() or cborencoder_close_container_checked.c::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.

1
2
3
4
uint8_t buf[16];
CborEncoder encoder;
cbor_encoder_init(&encoder, &buf, sizeof(buf), 0);
cbor_encode_int(&encoder, some_value);

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.

1
2
3
4
5
6
7
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);

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, cborencoder.c::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.h::cbor_encoder_get_extra_bytes_needed().

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.

The flags field is currently unused and must be zero.

void put16(void * where, uint16_t v)
bool isOomError(cbor.h::CborError err)
void put32(void * where, uint32_t v)
void put64(void * where, uint64_t v)
bool would_overflow(CborEncoder * encoder, size_t len)
void advance_ptr(CborEncoder * encoder, size_t n)
cbor.h::CborError append_to_buffer(CborEncoder * encoder, const void * data, size_t len)
cbor.h::CborError append_byte_to_buffer(CborEncoder * encoder, uint8_t byte)
cbor.h::CborError encode_number_no_update(CborEncoder * encoder, uint64_t ui, uint8_t shiftedMajorType)
void saturated_decrement(CborEncoder * encoder)
cbor.h::CborError encode_number(CborEncoder * encoder, uint64_t ui, uint8_t shiftedMajorType)
CBOR_API cbor.h::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

cborencoder.c::cbor_encode_negative_int(), cborencoder.c::cbor_encode_int()

CBOR_API cbor.h::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

cborencoder.c::cbor_encode_uint(), cborencoder.c::cbor_encode_int()

CBOR_API cbor.h::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

cborencoder.c::cbor_encode_negative_int(), cborencoder.c::cbor_encode_uint()

CBOR_API cbor.h::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_API cbor.h::CborError cbor_encode_floating_point(CborEncoder * encoder, cbor.h::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.h::cbor_encode_half_float(), cbor.h::cbor_encode_float(), cbor.h::cbor_encode_double()

CBOR_API cbor.h::CborError cbor_encode_tag(CborEncoder * encoder, cbor.h::CborTag tag)

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

See also

cbor.h::CborTag

cbor.h::CborError encode_string(CborEncoder * encoder, size_t length, uint8_t shiftedMajorType, const void * string)
CBOR_API cbor.h::CborError cbor_encode_byte_string(CborEncoder * encoder, const uint8_t * 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

cbor.h::CborError cbor.h::cbor_encode_text_stringz(), cborencoder.c::cbor_encode_byte_string()

CBOR_API cbor.h::CborError cbor_encode_text_string(CborEncoder * encoder, const char * 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.h::cbor_encode_text_stringz(), cborencoder.c::cbor_encode_text_string()

cbor.h::CborError create_container(CborEncoder * encoder, CborEncoder * container, size_t length, uint8_t shiftedMajorType)
CBOR_API cbor.h::CborError cbor_encoder_create_array(CborEncoder * encoder, CborEncoder * arrayEncoder, size_t length)

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

The array must be terminated by calling either cborencoder.c::cbor_encoder_close_container() or cborencoder_close_container_checked.c::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 cbor.h::CborIndefiniteLength may be passed as length instead.

See also

cborencoder.c::cbor_encoder_create_map()

CBOR_API cbor.h::CborError cbor_encoder_create_map(CborEncoder * encoder, CborEncoder * mapEncoder, size_t length)

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

The map must be terminated by calling either cborencoder.c::cbor_encoder_close_container() or cborencoder_close_container_checked.c::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 cbor.h::CborIndefiniteLength may be passed as length instead.

{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 cbor.h::CborIndefiniteLength), this function returns error CborErrorDataTooLarge.

See also

cborencoder.c::cbor_encoder_create_array()

CBOR_API cbor.h::CborError cbor_encoder_close_container(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 cborencoder.c::cbor_encoder_create_array() or cborencoder.c::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 cborencoder_close_container_checked.c::cbor_encoder_close_container_checked() instead.

See also

cborencoder.c::cbor_encoder_create_array(), cborencoder.c::cbor_encoder_create_map()

CBOR_API cbor.h::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 cborencoder.c::cbor_encoder_create_array() or cborencoder.c::cbor_encoder_create_map().

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

See also

cborencoder.c::cbor_encoder_create_array(), cborencoder.c::cbor_encoder_create_map()

cbor.h::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

cborencoder.c::cbor_encode_text_string(), cborencoder.c::cbor_encode_byte_string()

cbor.h::CborError cbor_encode_boolean(CborEncoder * encoder, bool value)

Appends the boolean value value to the CBOR stream provided by encoder.

cbor.h::CborError cbor_encode_null(CborEncoder * encoder)

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

See also

cbor.h::cbor_encode_undefined()

cbor.h::CborError cbor_encode_undefined(CborEncoder * encoder)

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

See also

cbor.h::cbor_encode_null()

cbor.h::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

cborencoder.c::cbor_encode_floating_point(), cbor.h::cbor_encode_float(), cbor.h::cbor_encode_double()

cbor.h::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

cborencoder.c::cbor_encode_floating_point(), cbor.h::cbor_encode_half_float(), cbor.h::cbor_encode_double()

cbor.h::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

cborencoder.c::cbor_encode_floating_point(), cbor.h::cbor_encode_half_float(), cbor.h::cbor_encode_float()

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 cborencoder.c::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.h::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

cborencoder.c::cbor_encoder_init(), cbor.h::cbor_encoder_get_extra_bytes_needed(), Encoding to CBOR

size_t cbor_encoder_get_extra_bytes_needed(const CborEncoder * encoder)

Returns how many more bytes the original buffer supplied to cborencoder.c::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 cborencoder.c::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

cborencoder.c::cbor_encoder_init(), cbor.h::cbor_encoder_get_buffer_size(), Encoding to CBOR

struct CborEncoder

Structure used to encode to CBOR.

uint8_t * ptr
ptrdiff_t bytes_needed
union CborEncoder::@0 data
const uint8_t * end
size_t remaining
int flags