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

CborError	cbor_encode_uint (CborEncoder *encoder, uint64_t value)
	Appends the unsigned 64-bit integer value to the CBOR stream provided by encoder. More...

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

CborError	cbor_encode_int (CborEncoder *encoder, int64_t value)
	Appends the signed 64-bit integer value to the CBOR stream provided by encoder. More...

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

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

CborError	cbor_encode_tag (CborEncoder *encoder, CborTag tag)
	Appends the CBOR tag tag to the CBOR stream provided by encoder. More...

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

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

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

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

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

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

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

CborError	cbor_encode_undefined (CborEncoder *encoder)
	Appends the CBOR type representing an undefined value to the CBOR stream provided by encoder. More...

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

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

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

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

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

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

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

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

Function Documentation

◆ cbor_encode_byte_string()

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: CborError cbor_encode_text_stringz, cbor_encode_byte_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()

◆ 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_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, cbor_encode_double

Referenced by cbor_encode_double(), cbor_encode_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 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

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

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

See also: cbor_encoder_create_map

◆ cbor_encoder_create_map()

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

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