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