Parsing CBOR streams¶

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 cborparser.c::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 cborparser.c::cbor_value_enter_container(). Each call to cborparser.c::cbor_value_enter_container() must be matched by a call to cborparser.c::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 cborparser.c::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.h::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.

uintptr_t(* IterateFunction()¶

const struct KnownTagData knownTagData()¶

= {
    { 0, (uint32_t)CborTextStringType },
    { 1, (uint32_t)(CborIntegerType+1) },
    { 2, (uint32_t)CborByteStringType },
    { 3, (uint32_t)CborByteStringType },
    { 4, (uint32_t)CborArrayType },
    { 5, (uint32_t)CborArrayType },
    { 16, (uint32_t)CborArrayType },
    { 17, (uint32_t)CborArrayType },
    { 18, (uint32_t)CborArrayType },
    { 21, (uint32_t)CborByteStringType | ((uint32_t)CborArrayType << 8) | ((uint32_t)CborMapType << 16) },
    { 22, (uint32_t)CborByteStringType | ((uint32_t)CborArrayType << 8) | ((uint32_t)CborMapType << 16) },
    { 23, (uint32_t)CborByteStringType | ((uint32_t)CborArrayType << 8) | ((uint32_t)CborMapType << 16) },
    { 24, (uint32_t)CborByteStringType },
    { 32, (uint32_t)CborTextStringType },
    { 33, (uint32_t)CborTextStringType },
    { 34, (uint32_t)CborTextStringType },
    { 35, (uint32_t)CborTextStringType },
    { 36, (uint32_t)CborTextStringType },
    { 96, (uint32_t)CborArrayType },
    { 97, (uint32_t)CborArrayType },
    { 98, (uint32_t)CborArrayType },
    { 55799, 0U }
}

uint16_t get16(const uint8_t * ptr)¶

uint32_t get32(const uint8_t * ptr)¶

uint64_t get64(const uint8_t * ptr)¶

cbor.h::CborError CBOR_INTERNAL_API_CC _cbor_value_extract_number(const uint8_t ** ptr, const uint8_t * end, uint64_t * len)¶

cbor.h::CborError extract_length(const CborParser * parser, const uint8_t ** ptr, size_t * len)¶

bool is_fixed_type(uint8_t type)¶

cbor.h::CborError preparse_value(CborValue * it)¶

cbor.h::CborError preparse_next_value_nodecrement(CborValue * it)¶

cbor.h::CborError preparse_next_value(CborValue * it)¶

cbor.h::CborError advance_internal(CborValue * it)¶

uint64_t _cbor_value_decode_int64_internal(const CborValue * value)¶

CBOR_API cbor.h::CborError cbor_parser_init(const uint8_t * buffer, size_t size, uint32_t 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_API cbor.h::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 cborvalidation.c::cbor_value_validate().

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

CBOR_API cbor.h::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 cborparser.c::cbor_value_advance() function instead.

cbor.h::CborError advance_recursive(CborValue * it, int nestingLevel)¶

CBOR_API cbor.h::CborError cbor_value_advance(CborValue * it)¶

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

Unlike cborparser.c::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.

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

CBOR_API cbor.h::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 cborparser.c::cbor_value_leave_container() in order to continue iterating past this container.

The it CborValue iterator must point to a container.

CBOR_API cbor.h::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 cborparser.c::cbor_value_advance(), cborparser.c::cbor_value_advance_fixed(), a nested cborparser.c::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 cborparser.c::cbor_value_enter_container().

CBOR_API cbor.h::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.h::cbor_value_get_type() or with cbor.h::cbor_value_is_integer() is recommended.

Unlike cbor.h::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.h::cbor_value_get_uint64() (if the number is positive) or cbor.h::cbor_value_get_raw_integer().

CBOR_API cbor.h::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.h::cbor_value_get_type() or with cbor.h::cbor_value_is_integer() is recommended.

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

CBOR_API cbor.h::CborError cbor_value_calculate_string_length(const CborValue * value, size_t * length 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.h::cbor_value_get_type(), with cbor.h::cbor_value_is_text_string() or cbor.h::cbor_value_is_byte_string() is recommended.

This function is different from cbor.h::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.

void prepare_string_iteration(CborValue * it)¶

cbor.h::CborError CBOR_INTERNAL_API_CC _cbor_value_prepare_string_iteration(CborValue * it)¶

cbor.h::CborError get_string_chunk(CborValue * it, const void ** bufferptr, size_t * len)¶

cbor.h::CborError CBOR_INTERNAL_API_CC _cbor_value_get_string_chunk(const CborValue * value, const void ** bufferptr, size_t * len, CborValue * next)¶

uintptr_t iterate_noop(char * dest, const uint8_t * src, size_t len)¶

uintptr_t iterate_memcmp(char * s1, const uint8_t * s2, size_t len)¶

uintptr_t iterate_memcpy(char * dest, const uint8_t * src, size_t len)¶

cbor.h::CborError iterate_string_chunks(const CborValue * value, char * buffer, size_t * buflen, bool * result, CborValue * next, IterateFunction func)¶

cbor.h::CborError _cbor_value_copy_string(const CborValue * value, void * buffer, size_t * buflen, CborValue * next)¶

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

CBOR_API cbor.h::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.h::cbor_value_get_type() or cbor.h::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 cborparser.c::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.

CBOR_API cbor.h::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.h::cbor_value_get_type() or with cbor.h::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.

cbor.h::CborError validate_value(CborValue * it, uint32_t flags, int recursionLeft)¶

cbor.h::CborError validate_utf8_string(const void * ptr, size_t n)¶

cbor.h::CborError validate_simple_type(uint8_t simple_type, uint32_t flags)¶

cbor.h::CborError validate_number(const CborValue * it, cbor.h::CborType type, uint32_t flags)¶

cbor.h::CborError validate_tag(CborValue * it, cbor.h::CborTag tag, uint32_t flags, int recursionLeft)¶

cbor.h::CborError validate_floating_point(CborValue * it, cbor.h::CborType type, uint32_t flags)¶

cbor.h::CborError validate_container(CborValue * it, int containerType, uint32_t flags, int recursionLeft)¶

CBOR_API cbor.h::CborError cbor_value_validate(const CborValue * it, uint32_t 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 cborparser.c::cbor_value_validate_basic().

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

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.h::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.h::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.h::cbor_value_at_end()

bool cbor_value_is_valid(const CborValue * value it)¶

Returns true if the iterator it contains a valid value.

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

bool cbor_value_is_tag(const CborValue * value)¶

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

cbor.h::CborError cbor_value_get_tag(const CborValue * value, cbor.h::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.h::cbor_value_get_type() or with cbor.h::cbor_value_is_tag() is recommended.

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.

cbor.h::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.h::cbor_value_is_text_string() and cbor.h::cbor_value_is_null().

See also

cbor.h::cbor_value_is_valid()

bool cbor_value_is_null(const CborValue * value)¶

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

bool cbor_value_is_undefined(const CborValue * value)¶

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

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

cbor.h::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.h::cbor_value_get_type() or with cbor.h::cbor_value_is_boolean() is recommended.

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

cbor.h::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.h::cbor_value_get_type() or with cbor.h::cbor_value_is_simple_type() is recommended.

bool cbor_value_is_integer(const CborValue * value)¶

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

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

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.

cbor.h::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.h::cbor_value_get_type() or with cbor.h::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 cborparser.c::cbor_value_get_int_checked() if that is not acceptable.

cbor.h::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.h::cbor_value_get_type() or with cbor.h::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 cborparser.c::cbor_value_get_int64_checked() that is not acceptable.

cbor.h::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.h::cbor_value_get_type() or with cbor.h::cbor_value_is_unsigned_integer() is recommended.

cbor.h::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.h::cbor_value_get_type() or with cbor.h::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.h::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.

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.h::cbor_value_get_string_length(), cbor.h::cbor_value_get_array_length() or cbor.h::cbor_value_get_map_length() to obtain the length. If the length is not known but is necessary, code can use the cborparser.c::cbor_value_calculate_string_length() function (no equivalent function is provided for maps and arrays).

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.

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.

cbor.h::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.h::cbor_value_get_type(), with cbor.h::cbor_value_is_text_string() or cbor.h::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.h::cbor_value_is_length_known().

If the length of the string is required but the length was not encoded, use cborparser.c::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.

cbor.h::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.h::cbor_value_get_type() or cbor.h::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 cborparser.c::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.h::cbor_value_dup_text_string(), cbor.h::cbor_value_copy_byte_string(), cbor.h::cbor_value_get_string_length(), cborparser.c::cbor_value_calculate_string_length()

cbor.h::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.h::cbor_value_get_type() or cbor.h::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 cborparser.c::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.h::cbor_value_dup_text_string(), cbor.h::cbor_value_copy_text_string(), cbor.h::cbor_value_get_string_length(), cborparser.c::cbor_value_calculate_string_length()

bool cbor_value_is_array(const CborValue * value)¶

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

cbor.h::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.h::cbor_value_get_type() or cbor.h::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.h::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.

bool cbor_value_is_map(const CborValue * value)¶

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

cbor.h::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.h::cbor_value_get_type() or cbor.h::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.h::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.

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

cbor.h::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.h::cbor_value_get_type() or with cbor.h::cbor_value_is_float() is recommended.

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

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

enum CborValidationFlags¶

CborValidateShortestIntegrals = 0x0001
CborValidateShortestFloatingPoint = 0x0002
CborValidateShortestNumbers = CborValidateShortestIntegrals | CborValidateShortestFloatingPoint
CborValidateNoIndeterminateLength = 0x0100
CborValidateMapIsSorted = 0x0200 | CborValidateNoIndeterminateLength
CborValidateCanonicalFormat = 0x0fff
CborValidateMapKeysAreUnique = 0x1000 | CborValidateMapIsSorted
CborValidateTagUse = 0x2000
CborValidateUtf8 = 0x4000
CborValidateStrictMode = 0xfff00
CborValidateMapKeysAreString = 0x100000
CborValidateNoUndefined = 0x200000
CborValidateNoTags = 0x400000
CborValidateFiniteFloatingPoint = 0x800000
CborValidateNoUnknownSimpleTypesSA = 0x4000000
CborValidateNoUnknownSimpleTypes = 0x8000000 | CborValidateNoUnknownSimpleTypesSA
CborValidateNoUnknownTagsSA = 0x10000000
CborValidateNoUnknownTagsSR = 0x20000000 | CborValidateNoUnknownTagsSA
CborValidateNoUnknownTags = 0x40000000 | CborValidateNoUnknownTagsSR
CborValidateCompleteData = (int)0x80000000
CborValidateStrictest = (int)~0U
CborValidateBasic = 0

struct KnownTagData¶

uint32_t tag¶

uint32_t types¶

struct CborValue¶

This type contains one value parsed from the CBOR stream.

Each CborValue behaves as an iterator in a StAX-style parser.

const CborParser * parser¶

const uint8_t * ptr¶

uint32_t remaining¶

uint16_t extra¶

uint8_t type¶

uint8_t flags¶

Parsing CBOR streams¶

Group of functions used to parse CBOR streams.

Memory and parsing constraints¶

Error handling and preconditions¶

tiny-cbor

Navigation

Related Topics