cbor.h File Reference

> The <cbor.h> is the main header in TinyCBOR and defines the constants used by most functions as well as the structures for encoding (CborEncoder) and decoding (CborValue). More...

`#include <assert.h>`
`#include <limits.h>`
`#include <stddef.h>`
`#include <stdint.h>`
`#include <string.h>`
`#include <stdio.h>`
`#include "tinycbor-version.h"`
`#include <stdbool.h>`

Go to the source code of this file.

## Data Structures

struct | CborEncoder
| Structure used to encode to CBOR. More...
struct | CborValue
| This type contains one value parsed from the CBOR stream. More...

## Functions

CBOR_API const char * | cbor_error_string (CborError error)
| Returns the error string corresponding to the CBOR error condition error.
CBOR_API void | cbor_encoder_init (CborEncoder *encoder, uint8_t *buffer, size_t size, int flags)
| Initializes a CborEncoder structure encoder by pointing it to buffer buffer of size size.
CBOR_API CborError | cbor_encode_uint (CborEncoder *encoder, uint64_t value)
| Appends the unsigned 64-bit integer value to the CBOR stream provided by encoder.
CBOR_API CborError | cbor_encode_int (CborEncoder *encoder, int64_t value)
| Appends the signed 64-bit integer value to the CBOR stream provided by encoder.
CBOR_API CborError | cbor_encode_negative_int (CborEncoder *encoder, uint64_t absolute_value)
| Appends the negative 64-bit integer whose absolute value is absolute_value to the CBOR stream provided by encoder.
CBOR_API CborError | cbor_encode_simple_value (CborEncoder *encoder, uint8_t value)
| Appends the CBOR Simple Type of value value to the CBOR stream provided by encoder.
CBOR_API CborError | cbor_encode_tag (CborEncoder *encoder, CborTag tag)
| Appends the CBOR tag tag to the CBOR stream provided by encoder.
CBOR_API CborError | cbor_encode_text_string (CborEncoder *encoder, const char *string, size_t length)
| Appends the text string string of length length to the CBOR stream provided by encoder.
CBOR_API CborError | cbor_encode_byte_string (CborEncoder *encoder, const uint8_t *string, size_t length)
| Appends the byte string string of length length to the CBOR stream provided by encoder.
CBOR_API CborError | cbor_encode_floating_point (CborEncoder *encoder, CborType fpType, const void *value)
| Appends the floating-point value of type fpType and pointed to by value to the CBOR stream provided by encoder.
CBOR_API CborError | cbor_encoder_create_array (CborEncoder *parentEncoder, CborEncoder *arrayEncoder, size_t length)
| Creates a CBOR array in the CBOR stream provided by parentEncoder and initializes arrayEncoder so that items can be added to the array using the CborEncoder functions.
CBOR_API CborError | cbor_encoder_create_map (CborEncoder *parentEncoder, CborEncoder *mapEncoder, size_t length)
| Creates a CBOR map in the CBOR stream provided by parentEncoder and initializes mapEncoder so that items can be added to the map using the CborEncoder functions.
CBOR_API CborError | cbor_encoder_close_container (CborEncoder *parentEncoder, const CborEncoder *containerEncoder)
| Closes the CBOR container (array or map) provided by containerEncoder and updates the CBOR stream provided by encoder.
CBOR_API CborError | cbor_encoder_close_container_checked (CborEncoder *parentEncoder, const CborEncoder *containerEncoder)
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.
CBOR_API 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.
CBOR_API CborError | cbor_value_advance_fixed (CborValue *it)
| Advances the CBOR value it by one fixed-size position.
CBOR_API CborError | cbor_value_advance (CborValue *it)
| Advances the CBOR value it by one element, skipping over containers.
CBOR_API 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.
CBOR_API CborError | cbor_value_leave_container (CborValue *it, const CborValue *recursed)
| Updates it to point to the next element after the container.
CBOR_API 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.
CBOR_API 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.
CBOR_API CborError | cbor_value_skip_tag (CborValue *it)
| Advances the CBOR value it until it no longer points to a tag.
CBOR_API CborError | cbor_value_calculate_string_length (const CborValue *value, size_t *length)
| Calculates the length of the byte or text string that value points to and stores it in len.
CborError | cbor_value_dup_text_string (const CborValue *value, char **buffer, size_t *buflen, CborValue *next)
| Allocates memory for the string pointed by value and copies it into this buffer.
CborError | cbor_value_dup_byte_string (const CborValue *value, uint8_t **buffer, size_t *buflen, CborValue *next)
| Allocates memory for the string pointed by value and copies it into this buffer.
CBOR_API 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.
CBOR_API 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.
CBOR_API CborError | cbor_value_get_half_float_as_float (const CborValue *value, float *result)
| Retrieves the CBOR half-precision floating point (16-bit) value that value points to, converts it to the float and store it in result.
CBOR_API 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.
CBOR_API CborError | cbor_value_to_pretty_stream (CborStreamFunction streamFunction, void *token, CborValue *value, int flags)
| Converts the current CBOR type pointed by value to its textual representation and writes it to the stream by calling the streamFunction.
CBOR_API CborError | cbor_value_to_pretty_advance_flags (FILE *out, CborValue *value, int flags)
| Converts the current CBOR type pointed to by value to its textual representation and writes it to the out stream.
CBOR_API CborError | cbor_value_to_pretty_advance (FILE *out, CborValue *value)
| Converts the current CBOR type pointed to by value to its textual representation and writes it to the out stream.
CborError | cbor_value_to_pretty (FILE *out, const CborValue *value)
| Converts the current CBOR type pointed to by value to its textual representation and writes it to the out stream.

## Detailed Description

> The <cbor.h> is the main header in TinyCBOR and defines the constants used by most functions as well as the structures for encoding (CborEncoder) and decoding (CborValue).

See also
  <cborjson.h>

## Function Documentation

## cbor_value_dup_byte_string()

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

Allocates memory for the string pointed by value and copies it into this buffer.

The pointer to the buffer is stored in buffer and the number of bytes copied is stored in buflen (those variables must not be NULL).

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 `malloc` returns a NULL pointer, this function will return error condition CborErrorOutOfMemory.

On success, ``{*buffer} will contain a valid pointer that must be freed by calling ``{free()}. This is the case even for zero-length strings.

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)) in addition to the malloc'ed block.

See also
  cbor_value_get_text_string_chunk(), cbor_value_copy_byte_string(), cbor_value_dup_text_string()

## cbor_value_dup_text_string()

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

Allocates memory for the string pointed by value and copies it into this buffer.

The pointer to the buffer is stored in buffer and the number of bytes copied is stored in buflen (those variables must not be NULL).

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 `malloc` returns a NULL pointer, this function will return error condition CborErrorOutOfMemory.

On success, ``{*buffer} will contain a valid pointer that must be freed by calling ``{free()}. This is the case even for zero-length strings.

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)) in addition to the malloc'ed block.

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

See also
  cbor_value_get_text_string_chunk(), cbor_value_copy_text_string(), cbor_value_dup_byte_string()

## cbor_value_get_half_float_as_float()

CBOR_API CborError cbor_value_get_half_float_as_float | ( | const CborValue * | value,
|  | float * | result
| ) |  |

Retrieves the CBOR half-precision floating point (16-bit) value that value points to, converts it to the float and store 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.

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

Referenced by cbor_value_get_half_float_as_float().

## cbor_value_to_pretty()

CborError cbor_value_to_pretty | ( | FILE * | out,
|  | const CborValue * | value
| ) |  |

Converts the current CBOR type pointed to by value to its textual representation and writes it to the out stream.

If an error occurs, this function returns an error code similar to CborParsing.

See also
  cbor_value_to_pretty_advance(), cbor_value_to_json_advance()

## cbor_value_to_pretty_advance()

CBOR_API CborError cbor_value_to_pretty_advance | ( | FILE * | out,
|  | CborValue * | value
| ) |  |

Converts the current CBOR type pointed to by value to its textual representation and writes it to the out stream.

If an error occurs, this function returns an error code similar to CborParsing.

If no error ocurred, this function advances value to the next element. Often, concatenating the text representation of multiple elements can be done by appending a comma to the output stream in between calls to this function.

See also
  cbor_value_to_pretty(), cbor_value_to_pretty_stream(), cbor_value_to_json_advance()

Referenced by cbor_value_to_pretty_advance().

## cbor_value_to_pretty_advance_flags()

CBOR_API CborError cbor_value_to_pretty_advance_flags | ( | FILE * | out,
|  | CborValue * | value,
|  | int | flags
| ) |  |

Converts the current CBOR type pointed to by value to its textual representation and writes it to the out stream.

If an error occurs, this function returns an error code similar to CborParsing.

The textual representation can be controlled by the flags parameter (see CborPrettyFlags for more information).

If no error ocurred, this function advances value to the next element. Often, concatenating the text representation of multiple elements can be done by appending a comma to the output stream in between calls to this function.

See also
  cbor_value_to_pretty_stream(), cbor_value_to_pretty(), cbor_value_to_json_advance()

Referenced by cbor_value_to_pretty(), and cbor_value_to_pretty_advance_flags().