Parsing CBOR streams

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

## Data Structures

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

## Functions

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.
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.
CborError | cbor_value_advance_fixed (CborValue *it)
| Advances the CBOR value it by one fixed-size position.
CborError | cbor_value_advance (CborValue *it)
| Advances the CBOR value it by one element, skipping over containers.
CborError | cbor_value_skip_tag (CborValue *it)
| Advances the CBOR value it until it no longer points to a tag.
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.
CborError | cbor_value_leave_container (CborValue *it, const CborValue *recursed)
| Updates it to point to the next element after the container.
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.
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.
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.
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.
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.
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.
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.
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.
bool | cbor_value_is_valid (const CborValue *value)
| Returns true if the iterator it contains a valid value.
bool | cbor_value_is_tag (const CborValue *value)
| Returns true if the iterator value is valid and points to a CBOR 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.
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.
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).
CborError | cbor_value_get_boolean (const CborValue *value, bool *result)
| Retrieves the boolean value that value points to and stores it in result.
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).
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.
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.
CborError | cbor_value_get_int (const CborValue *value, int *result)
| Retrieves the CBOR integer value that value points to and stores it in result.
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.
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.
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.
bool | cbor_value_is_length_known (const CborValue *value)
| Returns true if the length of this type is known without calculation.
bool | cbor_value_is_text_string (const CborValue *value)
| Returns true if the iterator value is valid and points to a CBOR text string.
bool | cbor_value_is_byte_string (const CborValue *value)
| Returns true if the iterator value is valid and points to a CBOR byte string.
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.
CborError | cbor_value_get_text_string_chunk (const CborValue *value, const char **bufferptr, size_t *len, CborValue *next)
| Extracts one text string chunk pointed to by value and stores a pointer to the data in buffer and the size in len, which must not be null.
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.
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.
bool | cbor_value_is_array (const CborValue *value)
| Returns true if the iterator value is valid and points to a CBOR array.
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.
bool | cbor_value_is_map (const CborValue *value)
| Returns true if the iterator value is valid and points to a CBOR map.
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.
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).
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.
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).
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.

## 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;
}
cbor_parser_init
CBOR_API 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.
Definition cborparser.c:345
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.
Definition cbor.h:441
CborValue
This type contains one value parsed from the CBOR stream.
Definition cbor.h:341

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;
}
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.
Definition cbor.h:411

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.

## Function Documentation

## cbor_parser_init()

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_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_map_find_value(), and 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_half_float_as_float(), cbor_value_get_float()

Referenced by cbor_value_get_half_float_as_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.

This function makes sense only when using a linear buffer (that is, when the parser is initialize by cbor_parser_init()). If using an external source, this function may return garbage; instead, consult the external source itself to find out more details about the presence of more 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_text_string_chunk()

CborError cbor_value_get_text_string_chunk | ( | const CborValue * | value,
|  | const char ** | bufferptr,
|  | size_t * | len,
|  | CborValue * | next )

Extracts one text string chunk pointed to by value and stores a pointer to the data in buffer and the size in len, which must not be null.

If no more chunks are available, then bufferptr will be set to null. This function may be used to iterate over any string without causing its contents to be copied to a separate buffer, like the convenience function cbor_value_copy_text_string() does.

It is designed to be used in code like:

if (cbor_value_is_text_string(value)) {
char *ptr;
size_t len;
while (1) {
err = cbor_value_get_text_string_chunk(value, &ptr, &len, &value));
if (err) return err;
if (ptr == NULL) return CborNoError;
consume(ptr, len);
}
}
cbor_value_get_text_string_chunk
CborError cbor_value_get_text_string_chunk(const CborValue *value, const char **bufferptr, size_t *len, CborValue *next)
Extracts one text string chunk pointed to by value and stores a pointer to the data in buffer and the...
Definition cbor.h:549
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.
Definition cbor.h:470

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.

The next pointer, if not null, will be updated to point to the next item after this string. During iteration, the pointer must only be passed back again to this function; passing it to any other function in this library results in undefined behavior. If there are no more chunks to be read from value, then next will be set to the next item after this string; if value points to the last item, then next will be invalid.

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

See also
  cbor_value_dup_text_string(), cbor_value_copy_text_string(), cbor_value_caculate_string_length(), cbor_value_get_byte_string_chunk()

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

Referenced by cbor_value_to_json_advance().

## 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 byte 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_get_text_string_chunk(), 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,
|  | 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 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()