Group of functions used to parse CBOR streams. More...

Data Structures
struct	CborValue
	This type contains one value parsed from the CBOR stream. More...

Enumerations
enum	CborValidationFlags
	The CborValidationFlags enum contains flags that control the validation of a CBOR stream. More...

Functions
CborError	cbor_parser_init (const uint8_t buffer, size_t size, int flags, CborParser parser, CborValue *it)
	Initializes the CBOR parser for parsing size bytes beginning at buffer. More...

CborError	cbor_value_validate_basic (const CborValue *it)
	Performs a basic validation of the CBOR stream pointed by it and returns the error it found. More...

CborError	cbor_value_advance_fixed (CborValue *it)
	Advances the CBOR value it by one fixed-size position. More...

CborError	cbor_value_advance (CborValue *it)
	Advances the CBOR value it by one element, skipping over containers. More...

CborError	cbor_value_skip_tag (CborValue *it)
	Advances the CBOR value it until it no longer points to a tag. More...

CborError	cbor_value_enter_container (const CborValue it, CborValue recursed)
	Creates a CborValue iterator pointing to the first element of the container represented by it and saves it in recursed. More...

CborError	cbor_value_leave_container (CborValue it, const CborValue recursed)
	Updates it to point to the next element after the container. More...

CborError	cbor_value_get_int64_checked (const CborValue value, int64_t result)
	Retrieves the CBOR integer value that value points to and stores it in result. More...

CborError	cbor_value_get_int_checked (const CborValue value, int result)
	Retrieves the CBOR integer value that value points to and stores it in result. More...

CborError	cbor_value_calculate_string_length (const CborValue value, size_t len)
	Calculates the length of the byte or text string that value points to and stores it in len. More...

CborError	cbor_value_text_string_equals (const CborValue value, const char string, bool *result)
	Compares the entry value with the string string and stores the result in result. More...

CborError	cbor_value_map_find_value (const CborValue map, const char string, CborValue *element)
	Attempts to find the value in map map that corresponds to the text string entry string. More...

CborError	cbor_value_get_half_float (const CborValue value, void result)
	Retrieves the CBOR half-precision floating point (16-bit) value that value points to and stores it in result. More...

CborError	cbor_value_validate (const CborValue *it, int flags)
	Performs a full validation, controlled by the flags options, of the CBOR stream pointed by it and returns the error it found. More...

bool	cbor_value_at_end (const CborValue *it)
	Returns true if it has reached the end of the iteration, usually when advancing after the last item in an array or map. More...

const uint8_t *	cbor_value_get_next_byte (const CborValue *it)
	Returns a pointer to the next byte that would be decoded if this CborValue object were advanced. More...

bool	cbor_value_is_valid (const CborValue *value)
	Returns true if the iterator it contains a valid value. More...

bool	cbor_value_is_tag (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR tag. More...

CborError	cbor_value_get_tag (const CborValue value, CborTag result)
	Retrieves the CBOR tag value that value points to and stores it in result. More...

bool	cbor_value_is_container (const CborValue *it)
	Returns true if the it value is a container and requires recursion in order to decode (maps and arrays), false otherwise.

CborType	cbor_value_get_type (const CborValue *value)
	Returns the type of the CBOR value that the iterator value points to. More...

bool	cbor_value_is_null (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR null type. More...

bool	cbor_value_is_undefined (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR undefined type. More...

bool	cbor_value_is_boolean (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR boolean type (true or false). More...

CborError	cbor_value_get_boolean (const CborValue value, bool result)
	Retrieves the boolean value that value points to and stores it in result. More...

bool	cbor_value_is_simple_type (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR Simple Type type (other than true, false, null and undefined). More...

CborError	cbor_value_get_simple_type (const CborValue value, uint8_t result)
	Retrieves the CBOR Simple Type value that value points to and stores it in result. More...

bool	cbor_value_is_integer (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR integer type. More...

bool	cbor_value_is_unsigned_integer (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR unsigned integer type (positive values or zero). More...

bool	cbor_value_is_negative_integer (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR negative integer type. More...

CborError	cbor_value_get_int (const CborValue value, int result)
	Retrieves the CBOR integer value that value points to and stores it in result. More...

CborError	cbor_value_get_int64 (const CborValue value, int64_t result)
	Retrieves the CBOR integer value that value points to and stores it in result. More...

CborError	cbor_value_get_uint64 (const CborValue value, uint64_t result)
	Retrieves the CBOR integer value that value points to and stores it in result. More...

CborError	cbor_value_get_raw_integer (const CborValue value, uint64_t result)
	Retrieves the CBOR integer value that value points to and stores it in result. More...

bool	cbor_value_is_length_known (const CborValue *value)
	Returns true if the length of this type is known without calculation. More...

bool	cbor_value_is_text_string (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR text string. More...

bool	cbor_value_is_byte_string (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR text string. More...

CborError	cbor_value_get_string_length (const CborValue value, size_t length)
	Extracts the length of the byte or text string that value points to and stores it in result. More...

CborError	cbor_value_copy_text_string (const CborValue value, char buffer, size_t buflen, CborValue next)
	Copies the string pointed to by value into the buffer provided at buffer of buflen bytes. More...

CborError	cbor_value_copy_byte_string (const CborValue value, uint8_t buffer, size_t buflen, CborValue next)
	Copies the string pointed by value into the buffer provided at buffer of buflen bytes. More...

bool	cbor_value_is_array (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR array. More...

CborError	cbor_value_get_array_length (const CborValue value, size_t length)
	Extracts the length of the CBOR array that value points to and stores it in result. More...

bool	cbor_value_is_map (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR map. More...

CborError	cbor_value_get_map_length (const CborValue value, size_t length)
	Extracts the length of the CBOR map that value points to and stores it in result. More...

bool	cbor_value_is_float (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR single-precision floating point (32-bit). More...

CborError	cbor_value_get_float (const CborValue value, float result)
	Retrieves the CBOR single-precision floating point (32-bit) value that value points to and stores it in result. More...

bool	cbor_value_is_double (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR double-precision floating point (64-bit). More...

bool	cbor_value_is_half_float (const CborValue *value)
	Returns true if the iterator value is valid and points to a CBOR single-precision floating point (16-bit). More...

Detailed Description

Group of functions used to parse CBOR streams.

TinyCBOR provides functions for pull-based stream parsing of a CBOR-encoded payload. The main data type for the parsing is a CborValue, which behaves like an iterator and can be used to extract the encoded data. It is first initialized with a call to cbor_parser_init() and is usually used to extract exactly one item, most often an array or map.

Nested CborValue objects can be parsed using cbor_value_enter_container(). Each call to cbor_value_enter_container() must be matched by a call to cbor_value_leave_container(), with the exact same parameters.

The example below initializes a CborParser object, begins the parsing with a CborValue and decodes a single integer:

int extract_int(const uint8_t *buffer, size_t len)
{
    CborParser parser;
    CborValue value;
    int result;
    cbor_parser_init(buffer, len, 0, &parser, &value);
    cbor_value_get_int(&value, &result);
    return result;
}

The code above does no error checking, which means it assumes the data comes from a source trusted to send one properly-encoded integer. The following example does the exact same operation, but includes error checking and returns 0 on parsing failure:

int extract_int(const uint8_t *buffer, size_t len)
{
    CborParser parser;
    CborValue value;
    int result;
    if (cbor_parser_init(buffer, len, 0, &parser, &value) != CborNoError)
        return 0;
    if (!cbor_value_is_integer(&value) ||
            cbor_value_get_int(&value, &result) != CborNoError)
        return 0;
    return result;
}

Note, in the example above, that one can't distinguish a parsing failure from an encoded value of zero. Reporting a parsing error is left as an exercise to the reader.

The code above does not execute a range-check either: it is possible that the value decoded from the CBOR stream encodes a number larger than what can be represented in a variable of type {int}. If detecting that case is important, the code should call cbor_value_get_int_checked() instead.

Memory and parsing constraints

TinyCBOR is designed to run with little memory and with minimal overhead. Except where otherwise noted, the parser functions always run on constant time (O(1)), do not recurse and never allocate memory (thus, stack usage is bounded and is O(1)).

Error handling and preconditions

All functions operating on a CborValue return a CborError condition, with CborNoError standing for the normal situation in which no parsing error occurred. All functions may return parsing errors in case the stream cannot be decoded properly, be it due to corrupted data or due to reaching the end of the input buffer.

Error conditions must not be ignored. All decoder functions have undefined behavior if called after an error has been reported, and may crash.

Some functions are also documented to have preconditions, like cbor_value_get_int() requiring that the input be an integral value. Violation of preconditions also results in undefined behavior and the program may crash.

Enumeration Type Documentation

◆ CborValidationFlags

enum CborValidationFlags

The CborValidationFlags enum contains flags that control the validation of a CBOR stream.

CborValidateBasic Validates only the syntactic correctedness of the stream.
CborValidateCanonical Validates that the stream is in canonical format, according to RFC 7049 section 3.9.
CborValidateStrictMode Performs strict validation, according to RFC 7049 section 3.10.
CborValidateStrictest Attempt to perform the strictest validation we know of.

CborValidateShortestIntegrals (Canonical) Validate that integral numbers and lengths are enconded in their shortest form possible.
CborValidateShortestFloatingPoint (Canonical) Validate that floating-point numbers are encoded in their shortest form possible.
CborValidateShortestNumbers (Canonical) Validate both integral and floating-point numbers are in their shortest form possible.
CborValidateNoIndeterminateLength (Canonical) Validate that no string, array or map uses indeterminate length encoding.
CborValidateMapIsSorted (Canonical & Strict mode) Validate that map keys appear in sorted order.
CborValidateMapKeysAreUnique (Strict mode) Validate that map keys are unique.
CborValidateTagUse (Strict mode) Validate that known tags are used with the correct types. This does not validate that the content of those types is syntactically correct. For example, this option validates that tag 1 (DateTimeString) is used with a Text String, but it does not validate that the string is a valid date/time representation.
CborValidateUtf8 (Strict mode) Validate that text strings are appropriately encoded in UTF-8.
CborValidateMapKeysAreString Validate that all map keys are text strings.
CborValidateNoUndefined Validate that no elements of type "undefined" are present.
CborValidateNoTags Validate that no tags are used.
CborValidateFiniteFloatingPoint Validate that all floating point numbers are finite (no NaN or infinities are allowed).
CborValidateCompleteData Validate that the stream is complete and there is no more data in the buffer.
CborValidateNoUnknownSimpleTypesSA Validate that all Standards Action simple types are registered with IANA.
CborValidateNoUnknownSimpleTypes Validate that all simple types used are registered with IANA.
CborValidateNoUnknownTagsSA Validate that all Standard Actions tags are registered with IANA.
CborValidateNoUnknownTagsSR Validate that all Standard Actions and Specification Required tags are registered with IANA (see below for limitations).
CborValidateNoUnkonwnTags Validate that all tags are registered with IANA (see below for limitations).

Simple type registry: The CBOR specification requires that registration for use of the first 19 simple types must be done by way of Standards Action. The rest of the simple types only require a specification. The official list can be obtained from https://www.iana.org/assignments/cbor-simple-values/cbor-simple-values.xhtml.

: There are no registered simple types recognized by this release of TinyCBOR (beyond those defined by RFC 7049).

Tag registry: The CBOR specification requires that registration for use of the first 23 tags must be done by way of Standards Action. The next up to tag 255 only require a specification. Finally, all other tags can be registered on a first-come-first-serve basis. The official list can be ontained from https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml.

: Given the variability of this list, TinyCBOR cannot recognize all tags registered with IANA. Instead, the implementation only recognizes tags that are backed by an RFC.

These are the tags known to the current TinyCBOR release:

Tag	Data Item	Semantics
0	UTF-8 text string	Standard date/time string
1	integer	Epoch-based date/time
2	byte string	Positive bignum
3	byte string	Negative bignum
4	array	Decimal fraction
5	array	Bigfloat
16	array	COSE Single Recipient Encrypted Data Object (RFC 8152)
17	array	COSE Mac w/o Recipients Object (RFC 8152)
18	array	COSE Single Signer Data Object (RFC 8162)
21	byte string, array, map	Expected conversion to base64url encoding
22	byte string, array, map	Expected conversion to base64 encoding
23	byte string, array, map	Expected conversion to base16 encoding
24	byte string	Encoded CBOR data item
32	UTF-8 text string	URI
33	UTF-8 text string	base64url
34	UTF-8 text string	base64
35	UTF-8 text string	Regular expression
36	UTF-8 text string	MIME message
96	array	COSE Encrypted Data Object (RFC 8152)
97	array	COSE MACed Data Object (RFC 8152)
98	array	COSE Signed Data Object (RFC 8152)
55799	any	Self-describe CBOR

Function Documentation

◆ cbor_parser_init()

CborError cbor_parser_init	(	const uint8_t *	buffer,
		size_t	size,
		int	flags,
		CborParser *	parser,
		CborValue *	it
	)

Initializes the CBOR parser for parsing size bytes beginning at buffer.

Parsing will use flags set in flags. The iterator to the first element is returned in it.

The parser structure needs to remain valid throughout the decoding process. It is not thread-safe to share one CborParser among multiple threads iterating at the same time, but the object can be copied so multiple threads can iterate.

◆ cbor_value_advance()

CborError cbor_value_advance ( CborValue * it )

Advances the CBOR value it by one element, skipping over containers.

Unlike cbor_value_advance_fixed(), this function can be called on a CBOR value of any type. However, if the type is a container (map or array) or a string with a chunked payload, this function will not run in constant time and will recurse into itself (it will run on O(n) time for the number of elements or chunks and will use O(n) memory for the number of nested containers).

The number of recursions can be limited at compile time to avoid stack exhaustion in constrained systems.

See also: cbor_value_at_end(), cbor_value_advance_fixed(), cbor_value_enter_container(), cbor_value_leave_container()

Referenced by cbor_value_validate_basic().

◆ cbor_value_advance_fixed()

CborError cbor_value_advance_fixed ( CborValue * it )

Advances the CBOR value it by one fixed-size position.

Fixed-size types are: integers, tags, simple types (including boolean, null and undefined values) and floating point types.

If the type is not of fixed size, this function has undefined behavior. Code must be sure that the current type is one of the fixed-size types before calling this function. This function is provided because it can guarantee that it runs in constant time (O(1)).

If the caller is not able to determine whether the type is fixed or not, code can use the cbor_value_advance() function instead.

See also: cbor_value_at_end(), cbor_value_advance(), cbor_value_enter_container(), cbor_value_leave_container()

Referenced by cbor_value_skip_tag().

◆ cbor_value_at_end()

bool cbor_value_at_end ( const CborValue * it )

Returns true if it has reached the end of the iteration, usually when advancing after the last item in an array or map.

In the case of the outermost CborValue object, this function returns true after decoding a single element. A pointer to the first byte of the remaining data (if any) can be obtained with cbor_value_get_next_byte().

See also: cbor_value_advance(), cbor_value_is_valid(), cbor_value_get_next_byte()

Referenced by cbor_value_map_find_value().

◆ cbor_value_calculate_string_length()

CborError cbor_value_calculate_string_length	(	const CborValue *	value,
		size_t *	len
	)

Calculates the length of the byte or text string that value points to and stores it in len.

If the iterator value does not point to a text string or a byte string, the behaviour is undefined, so checking with cbor_value_get_type, with cbor_value_is_text_string or cbor_value_is_byte_string is recommended.

This function is different from cbor_value_get_string_length() in that it calculates the length even for strings sent in chunks. For that reason, this function may not run in constant time (it will run in O(n) time on the number of chunks). It does use constant memory (O(1)).

Note: On 32-bit platforms, this function will return error condition of CborErrorDataTooLarge if the stream indicates a length that is too big to fit in 32-bit.

See also: cbor_value_get_string_length(), cbor_value_copy_text_string(), cbor_value_copy_byte_string(), cbor_value_is_length_known()

◆ cbor_value_copy_byte_string()

CborError cbor_value_copy_byte_string	(	const CborValue *	value,
		uint8_t *	buffer,
		size_t *	buflen,
		CborValue *	next
	)

Copies the string pointed by value into the buffer provided at buffer of buflen bytes.

If buffer is a NULL pointer, this function will not copy anything and will only update the next value.

If the iterator value does not point to a byte string, the behaviour is undefined, so checking with cbor_value_get_type or cbor_value_is_byte_string is recommended.

If the provided buffer length was too small, this function returns an error condition of CborErrorOutOfMemory. If you need to calculate the length of the string in order to preallocate a buffer, use cbor_value_calculate_string_length().

On success, this function sets the number of bytes copied to {*buflen}. If the buffer is large enough, this function will insert a null byte after the last copied byte, to facilitate manipulation of null-terminated strings. That byte is not included in the returned value of {*buflen}.

The next pointer, if not null, will be updated to point to the next item after this string. If value points to the last item, then next will be invalid.

This function may not run in constant time (it will run in O(n) time on the number of chunks). It requires constant memory (O(1)).

See also: cbor_value_get_byte_string_chunk(), cbor_value_dup_text_string(), cbor_value_copy_text_string(), cbor_value_get_string_length(), cbor_value_calculate_string_length()

◆ cbor_value_copy_text_string()

CborError cbor_value_copy_text_string	(	const CborValue *	value,
		char *	buffer,
		size_t *	buflen,
		CborValue *	next
	)

Copies the string pointed to by value into the buffer provided at buffer of buflen bytes.

If buffer is a NULL pointer, this function will not copy anything and will only update the next value.

If the iterator value does not point to a text string, the behaviour is undefined, so checking with cbor_value_get_type or cbor_value_is_text_string is recommended.

If the provided buffer length was too small, this function returns an error condition of CborErrorOutOfMemory. If you need to calculate the length of the string in order to preallocate a buffer, use cbor_value_calculate_string_length().

On success, this function sets the number of bytes copied to {*buflen}. If the buffer is large enough, this function will insert a null byte after the last copied byte, to facilitate manipulation of text strings. That byte is not included in the returned value of {*buflen}. If there was no space for the terminating null, no error is returned, so callers must check the value of *buflen after the call, before relying on the '\0'; if it has not been changed by the call, there is no '\0'-termination on the buffer's contents.

The next pointer, if not null, will be updated to point to the next item after this string. If value points to the last item, then next will be invalid.

This function may not run in constant time (it will run in O(n) time on the number of chunks). It requires constant memory (O(1)).

Note: This function does not perform UTF-8 validation on the incoming text string.

See also: cbor_value_get_text_string_chunk() cbor_value_dup_text_string(), cbor_value_copy_byte_string(), cbor_value_get_string_length(), cbor_value_calculate_string_length()

◆ cbor_value_enter_container()

CborError cbor_value_enter_container	(	const CborValue *	it,
		CborValue *	recursed
	)

Creates a CborValue iterator pointing to the first element of the container represented by it and saves it in recursed.

The it container object needs to be kept and passed again to cbor_value_leave_container() in order to continue iterating past this container.

The it CborValue iterator must point to a container.

See also: cbor_value_is_container(), cbor_value_leave_container(), cbor_value_advance()

Referenced by cbor_value_map_find_value().

◆ cbor_value_get_array_length()

CborError cbor_value_get_array_length	(	const CborValue *	value,
		size_t *	length
	)

Extracts the length of the CBOR array that value points to and stores it in result.

If the iterator value does not point to a CBOR array, the behaviour is undefined, so checking with cbor_value_get_type or cbor_value_is_array is recommended.

If the length of this array is not encoded in the CBOR data stream, this function will return the recoverable error CborErrorUnknownLength. You may also check whether that is the case by using cbor_value_is_length_known().

Note: On 32-bit platforms, this function will return error condition of CborErrorDataTooLarge if the stream indicates a length that is too big to fit in 32-bit.

See also: cbor_value_is_valid(), cbor_value_is_length_known()

◆ cbor_value_get_boolean()

CborError cbor_value_get_boolean	(	const CborValue *	value,
		bool *	result
	)

Retrieves the boolean value that value points to and stores it in result.

If the iterator value does not point to a boolean value, the behavior is undefined, so checking with cbor_value_get_type or with cbor_value_is_boolean is recommended.

See also: cbor_value_get_type(), cbor_value_is_valid(), cbor_value_is_boolean()

◆ cbor_value_get_float()

CborError cbor_value_get_float	(	const CborValue *	value,
		float *	result
	)

Retrieves the CBOR single-precision floating point (32-bit) value that value points to and stores it in result.

If the iterator value does not point to a single-precision floating point value, the behavior is undefined, so checking with cbor_value_get_type or with cbor_value_is_float is recommended.

See also: cbor_value_get_type(), cbor_value_is_valid(), cbor_value_is_float(), cbor_value_get_double()

◆ cbor_value_get_half_float()

CborError cbor_value_get_half_float	(	const CborValue *	value,
		void *	result
	)

Retrieves the CBOR half-precision floating point (16-bit) value that value points to and stores it in result.

If the iterator value does not point to a half-precision floating point value, the behavior is undefined, so checking with cbor_value_get_type or with cbor_value_is_half_float is recommended.

Note: since the C language does not have a standard type for half-precision floating point, this function takes a {void *} as a parameter for the storage area, which must be at least 16 bits wide.

See also: cbor_value_get_type(), cbor_value_is_valid(), cbor_value_is_half_float(), cbor_value_get_float()

◆ cbor_value_get_int()

CborError cbor_value_get_int	(	const CborValue *	value,
		int *	result
	)

Retrieves the CBOR integer value that value points to and stores it in result.

If the iterator value does not point to an integer value, the behavior is undefined, so checking with cbor_value_get_type or with cbor_value_is_integer is recommended.

Note that this function does not do range-checking: integral values that do not fit in a variable of type {int} are silently truncated to fit. Use cbor_value_get_int_checked() if that is not acceptable.

See also: cbor_value_get_type(), cbor_value_is_valid(), cbor_value_is_integer()

◆ cbor_value_get_int64()

CborError cbor_value_get_int64	(	const CborValue *	value,
		int64_t *	result
	)

Retrieves the CBOR integer value that value points to and stores it in result.

If the iterator value does not point to an integer value, the behavior is undefined, so checking with cbor_value_get_type or with cbor_value_is_integer is recommended.

Note that this function does not do range-checking: integral values that do not fit in a variable of type {int64_t} are silently truncated to fit. Use cbor_value_get_int64_checked() that is not acceptable.

See also: cbor_value_get_type(), cbor_value_is_valid(), cbor_value_is_integer()

◆ cbor_value_get_int64_checked()

CborError cbor_value_get_int64_checked	(	const CborValue *	value,
		int64_t *	result
	)

Retrieves the CBOR integer value that value points to and stores it in result.

If the iterator value does not point to an integer value, the behavior is undefined, so checking with cbor_value_get_type or with cbor_value_is_integer is recommended.

Unlike cbor_value_get_int64(), this function performs a check to see if the stored integer fits in result without data loss. If the number is outside the valid range for the data type, this function returns the recoverable error CborErrorDataTooLarge. In that case, use either cbor_value_get_uint64() (if the number is positive) or cbor_value_get_raw_integer().

See also: cbor_value_get_type(), cbor_value_is_valid(), cbor_value_is_integer(), cbor_value_get_int64()

◆ cbor_value_get_int_checked()

CborError cbor_value_get_int_checked	(	const CborValue *	value,
		int *	result
	)

Retrieves the CBOR integer value that value points to and stores it in result.

If the iterator value does not point to an integer value, the behavior is undefined, so checking with cbor_value_get_type or with cbor_value_is_integer is recommended.

Unlike cbor_value_get_int(), this function performs a check to see if the stored integer fits in result without data loss. If the number is outside the valid range for the data type, this function returns the recoverable error CborErrorDataTooLarge. In that case, use one of the other integer functions to obtain the value.

See also: cbor_value_get_type(), cbor_value_is_valid(), cbor_value_is_integer(), cbor_value_get_int64(), cbor_value_get_uint64(), cbor_value_get_int64_checked(), cbor_value_get_raw_integer()

◆ cbor_value_get_map_length()

CborError cbor_value_get_map_length	(	const CborValue *	value,
		size_t *	length
	)

Extracts the length of the CBOR map that value points to and stores it in result.

If the iterator value does not point to a CBOR map, the behaviour is undefined, so checking with cbor_value_get_type or cbor_value_is_map is recommended.

If the length of this map is not encoded in the CBOR data stream, this function will return the recoverable error CborErrorUnknownLength. You may also check whether that is the case by using cbor_value_is_length_known().

Note: On 32-bit platforms, this function will return error condition of CborErrorDataTooLarge if the stream indicates a length that is too big to fit in 32-bit.

See also: cbor_value_is_valid(), cbor_value_is_length_known()

◆ cbor_value_get_next_byte()

const uint8_t * cbor_value_get_next_byte ( const CborValue * it )

Returns a pointer to the next byte that would be decoded if this CborValue object were advanced.

This function is useful if cbor_value_at_end() returns true for the outermost CborValue: the pointer returned is the first byte of the data remaining in the buffer, if any. Code can decide whether to begin decoding a new CBOR data stream from this point, or parse some other data appended to the same buffer.

This function may be used even after a parsing error. If that occurred, then this function returns a pointer to where the parsing error occurred. Note that the error recovery is not precise and the pointer may not indicate the exact byte containing bad data.

See also: cbor_value_at_end()

◆ cbor_value_get_raw_integer()

CborError cbor_value_get_raw_integer	(	const CborValue *	value,
		uint64_t *	result
	)

Retrieves the CBOR integer value that value points to and stores it in result.

If the iterator value does not point to an integer value, the behavior is undefined, so checking with cbor_value_get_type or with cbor_value_is_integer is recommended.

This function is provided because CBOR negative integers can assume values that cannot be represented with normal 64-bit integer variables.

If the integer is unsigned (that is, if cbor_value_is_unsigned_integer() returns true), then result will contain the actual value. If the integer is negative, then result will contain the absolute value of that integer, minus one. That is, {actual = -result - 1}. On architectures using two's complement for representation of negative integers, it is equivalent to say that result will contain the bitwise negation of the actual value.

See also: cbor_value_get_type(), cbor_value_is_valid(), cbor_value_is_integer()

◆ cbor_value_get_simple_type()

CborError cbor_value_get_simple_type	(	const CborValue *	value,
		uint8_t *	result
	)

Retrieves the CBOR Simple Type value that value points to and stores it in result.

If the iterator value does not point to a simple_type value, the behavior is undefined, so checking with cbor_value_get_type or with cbor_value_is_simple_type is recommended.

See also: cbor_value_get_type(), cbor_value_is_valid(), cbor_value_is_simple_type()

◆ cbor_value_get_string_length()

CborError cbor_value_get_string_length	(	const CborValue *	value,
		size_t *	length
	)

Extracts the length of the byte or text string that value points to and stores it in result.

If the iterator value does not point to a text string or a byte string, the behaviour is undefined, so checking with cbor_value_get_type, with cbor_value_is_text_string or cbor_value_is_byte_string is recommended.

If the length of this string is not encoded in the CBOR data stream, this function will return the recoverable error CborErrorUnknownLength. You may also check whether that is the case by using cbor_value_is_length_known().

If the length of the string is required but the length was not encoded, use cbor_value_calculate_string_length(), but note that that function does not run in constant time.

Note: On 32-bit platforms, this function will return error condition of CborErrorDataTooLarge if the stream indicates a length that is too big to fit in 32-bit.

See also: cbor_value_is_valid(), cbor_value_is_length_known(), cbor_value_calculate_string_length()

◆ cbor_value_get_tag()

CborError cbor_value_get_tag	(	const CborValue *	value,
		CborTag *	result
	)

Retrieves the CBOR tag value that value points to and stores it in result.

If the iterator value does not point to a CBOR tag value, the behavior is undefined, so checking with cbor_value_get_type or with cbor_value_is_tag is recommended.

See also: cbor_value_get_type(), cbor_value_is_valid(), cbor_value_is_tag()

◆ cbor_value_get_type()

CborType cbor_value_get_type ( const CborValue * value )

Returns the type of the CBOR value that the iterator value points to.

If value does not point to a valid value, this function returns CborInvalidType.

TinyCBOR also provides functions to test directly if a given CborValue object is of a given type, like cbor_value_is_text_string() and cbor_value_is_null().

See also: cbor_value_is_valid()

◆ cbor_value_get_uint64()

CborError cbor_value_get_uint64	(	const CborValue *	value,
		uint64_t *	result
	)

Retrieves the CBOR integer value that value points to and stores it in result.

If the iterator value does not point to an unsigned integer value, the behavior is undefined, so checking with cbor_value_get_type or with cbor_value_is_unsigned_integer is recommended.

See also: cbor_value_get_type(), cbor_value_is_valid(), cbor_value_is_unsigned_integer()

◆ cbor_value_is_array()

bool cbor_value_is_array ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR array.

See also: cbor_value_is_valid(), cbor_value_is_map()

Referenced by cbor_value_get_array_length().

◆ cbor_value_is_boolean()

bool cbor_value_is_boolean ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR boolean type (true or false).

See also: cbor_value_is_valid(), cbor_value_get_boolean()

Referenced by cbor_value_get_boolean().

◆ cbor_value_is_byte_string()

bool cbor_value_is_byte_string ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR text string.

CBOR byte strings are binary data with no specified encoding or format.

See also: cbor_value_is_valid(), cbor_value_get_string_length(), cbor_value_calculate_string_length(), cbor_value_copy_byte_string(), cbor_value_dup_byte_string()

Referenced by cbor_value_copy_byte_string(), cbor_value_dup_byte_string(), and cbor_value_get_string_length().

◆ cbor_value_is_double()

bool cbor_value_is_double ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR double-precision floating point (64-bit).

See also: cbor_value_is_valid(), cbor_value_is_float(), cbor_value_is_half_float()

◆ cbor_value_is_float()

bool cbor_value_is_float ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR single-precision floating point (32-bit).

See also: cbor_value_is_valid(), cbor_value_is_double(), cbor_value_is_half_float()

Referenced by cbor_value_get_float().

◆ cbor_value_is_half_float()

bool cbor_value_is_half_float ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR single-precision floating point (16-bit).

See also: cbor_value_is_valid(), cbor_value_is_double(), cbor_value_is_float()

Referenced by cbor_value_get_half_float().

◆ cbor_value_is_integer()

bool cbor_value_is_integer ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR integer type.

See also: cbor_value_is_valid(), cbor_value_get_int, cbor_value_get_int64, cbor_value_get_uint64, cbor_value_get_raw_integer

Referenced by cbor_value_get_int(), cbor_value_get_int64(), cbor_value_get_int64_checked(), cbor_value_get_int_checked(), cbor_value_get_raw_integer(), cbor_value_is_negative_integer(), and cbor_value_is_unsigned_integer().

◆ cbor_value_is_length_known()

bool cbor_value_is_length_known ( const CborValue * value )

Returns true if the length of this type is known without calculation.

That is, if the length of this CBOR string, map or array is encoded in the data stream, this function returns true. If the length is not encoded, it returns false.

If the length is known, code can call cbor_value_get_string_length(), cbor_value_get_array_length() or cbor_value_get_map_length() to obtain the length. If the length is not known but is necessary, code can use the cbor_value_calculate_string_length() function (no equivalent function is provided for maps and arrays).

Referenced by cbor_value_get_array_length(), cbor_value_get_map_length(), and cbor_value_get_string_length().

◆ cbor_value_is_map()

bool cbor_value_is_map ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR map.

See also: cbor_value_is_valid(), cbor_value_is_array()

Referenced by cbor_value_get_map_length(), and cbor_value_map_find_value().

◆ cbor_value_is_negative_integer()

bool cbor_value_is_negative_integer ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR negative integer type.

See also: cbor_value_is_valid(), cbor_value_get_int, cbor_value_get_int64, cbor_value_get_raw_integer

◆ cbor_value_is_null()

bool cbor_value_is_null ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR null type.

See also: cbor_value_is_valid(), cbor_value_is_undefined()

◆ cbor_value_is_simple_type()

bool cbor_value_is_simple_type ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR Simple Type type (other than true, false, null and undefined).

See also: cbor_value_is_valid(), cbor_value_get_simple_type()

Referenced by cbor_value_get_simple_type().

◆ cbor_value_is_tag()

bool cbor_value_is_tag ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR tag.

See also: cbor_value_get_tag(), cbor_value_skip_tag()

Referenced by cbor_value_get_tag(), and cbor_value_skip_tag().

◆ cbor_value_is_text_string()

bool cbor_value_is_text_string ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR text string.

CBOR text strings are UTF-8 encoded and usually contain human-readable text.

See also: cbor_value_is_valid(), cbor_value_get_string_length(), cbor_value_calculate_string_length(), cbor_value_copy_text_string(), cbor_value_dup_text_string()

Referenced by cbor_value_copy_text_string(), cbor_value_dup_text_string(), cbor_value_get_string_length(), cbor_value_map_find_value(), and cbor_value_text_string_equals().

◆ cbor_value_is_undefined()

bool cbor_value_is_undefined ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR undefined type.

See also: cbor_value_is_valid(), cbor_value_is_null()

◆ cbor_value_is_unsigned_integer()

bool cbor_value_is_unsigned_integer ( const CborValue * value )

Returns true if the iterator value is valid and points to a CBOR unsigned integer type (positive values or zero).

See also: cbor_value_is_valid(), cbor_value_get_uint64()

Referenced by cbor_value_get_uint64().

◆ cbor_value_is_valid()

bool cbor_value_is_valid ( const CborValue * it )

Returns true if the iterator it contains a valid value.

Invalid iterators happen when iteration reaches the end of a container (see cbor_value_at_end()) or when a search function resulted in no matches.

See also: cbor_value_advance(), cbor_value_at_end(), cbor_value_get_type()

◆ cbor_value_leave_container()

CborError cbor_value_leave_container	(	CborValue *	it,
		const CborValue *	recursed
	)

Updates it to point to the next element after the container.

The recursed object needs to point to the element obtained either by advancing the last element of the container (via cbor_value_advance(), cbor_value_advance_fixed(), a nested cbor_value_leave_container(), or the next pointer from cbor_value_copy_string() or cbor_value_dup_string()).

The it and recursed parameters must be the exact same as passed to cbor_value_enter_container().

See also: cbor_value_enter_container(), cbor_value_at_end()

◆ cbor_value_map_find_value()

CborError cbor_value_map_find_value	(	const CborValue *	map,
		const char *	string,
		CborValue *	element
	)

Attempts to find the value in map map that corresponds to the text string entry string.

If the iterator value does not point to a CBOR map, the behaviour is undefined, so checking with cbor_value_get_type or cbor_value_is_map is recommended.

If the item is found, it is stored in result. If no item is found matching the key, then result will contain an element of type CborInvalidType. Matching is performed using cbor_value_text_string_equals(), so tagged strings will also match.

This function has a time complexity of O(n) where n is the number of elements in the map to be searched. In addition, this function is has O(n) memory requirement based on the number of nested containers (maps or arrays) found as elements of this map.

See also: cbor_value_is_valid(), cbor_value_text_string_equals(), cbor_value_advance()

◆ cbor_value_skip_tag()

CborError cbor_value_skip_tag ( CborValue * it )

Advances the CBOR value it until it no longer points to a tag.

If it is already not pointing to a tag, then this function returns it unchanged.

This function does not run in constant time: it will run on O(n) for n being the number of tags. It does use constant memory (O(1) memory requirements).

See also: cbor_value_advance_fixed(), cbor_value_advance()

Referenced by cbor_value_map_find_value(), and cbor_value_text_string_equals().

◆ cbor_value_text_string_equals()

CborError cbor_value_text_string_equals	(	const CborValue *	value,
		const char *	string,
		bool *	result
	)

Compares the entry value with the string string and stores the result in result.

If the value is different from string result will contain false.

The entry at value may be a tagged string. If value is not a string or a tagged string, the comparison result will be false.

CBOR requires text strings to be encoded in UTF-8, but this function does not validate either the strings in the stream or the string string to be matched. Moreover, comparison is done on strict codepoint comparison, without any Unicode normalization.

This function may not run in constant time (it will run in O(n) time on the number of chunks). It requires constant memory (O(1)).

See also: cbor_value_skip_tag(), cbor_value_copy_text_string()

◆ cbor_value_validate()

CborError cbor_value_validate	(	const CborValue *	it,
		int	flags
	)

Performs a full validation, controlled by the flags options, of the CBOR stream pointed by it and returns the error it found.

If no error was found, it returns CborNoError and the application can iterate over the items with certainty that no errors will appear during parsing.

If flags is CborValidateBasic, the result should be the same as cbor_value_validate_basic().

This function has the same timing and memory requirements as cbor_value_advance() and cbor_value_validate_basic().

See also: CborValidationFlags, cbor_value_validate_basic(), cbor_value_advance()

◆ cbor_value_validate_basic()

CborError cbor_value_validate_basic ( const CborValue * it )

Performs a basic validation of the CBOR stream pointed by it and returns the error it found.

If no error was found, it returns CborNoError and the application can iterate over the items with certainty that no other errors will appear during parsing.

A basic validation checks for:

absence of undefined additional information bytes;
well-formedness of all numbers, lengths, and simple values;
string contents match reported sizes;
arrays and maps contain the number of elements they are reported to have;

For further checks, see cbor_value_validate().

This function has the same timing and memory requirements as cbor_value_advance().

See also: cbor_value_validate(), cbor_value_advance()

Data Structures

Enumerations

Functions

Detailed Description

Memory and parsing constraints

Error handling and preconditions

Enumeration Type Documentation

◆ CborValidationFlags

Function Documentation

◆ cbor_parser_init()

◆ cbor_value_advance()

◆ cbor_value_advance_fixed()

◆ cbor_value_at_end()

◆ cbor_value_calculate_string_length()

◆ cbor_value_copy_byte_string()

◆ cbor_value_copy_text_string()

◆ cbor_value_enter_container()

◆ cbor_value_get_array_length()

◆ cbor_value_get_boolean()

◆ cbor_value_get_float()

◆ cbor_value_get_half_float()

◆ cbor_value_get_int()

◆ cbor_value_get_int64()

◆ cbor_value_get_int64_checked()

◆ cbor_value_get_int_checked()

◆ cbor_value_get_map_length()

◆ cbor_value_get_next_byte()

◆ cbor_value_get_raw_integer()

◆ cbor_value_get_simple_type()

◆ cbor_value_get_string_length()

◆ cbor_value_get_tag()

◆ cbor_value_get_type()

◆ cbor_value_get_uint64()

◆ cbor_value_is_array()

◆ cbor_value_is_boolean()

◆ cbor_value_is_byte_string()

◆ cbor_value_is_double()

◆ cbor_value_is_float()

◆ cbor_value_is_half_float()

◆ cbor_value_is_integer()

◆ cbor_value_is_length_known()

◆ cbor_value_is_map()

◆ cbor_value_is_negative_integer()

◆ cbor_value_is_null()

◆ cbor_value_is_simple_type()

◆ cbor_value_is_tag()

◆ cbor_value_is_text_string()

◆ cbor_value_is_undefined()

◆ cbor_value_is_unsigned_integer()

◆ cbor_value_is_valid()

◆ cbor_value_leave_container()

◆ cbor_value_map_find_value()

◆ cbor_value_skip_tag()

◆ cbor_value_text_string_equals()

◆ cbor_value_validate()

◆ cbor_value_validate_basic()