Decoding

Another way to decode data using libcbor is to specify a callbacks that will be invoked when upon finding certain items in the input. This API is provided by

struct cbor_decoder_result cbor_stream_decode(cbor_data buffer, size_t buffer_size, const struct cbor_callbacks *callbacks, void *context)

Stateless decoder.

Will try parsing the buffer and will invoke the appropriate callback on success. Decodes one item at a time. No memory allocations occur.

Parameters

• buffer: Input buffer

• buffer_size: Length of the buffer

• callbacks: The callback bundle

• context: An arbitrary pointer to allow for maintaining context.

Usage example: https://github.com/PJK/libcbor/blob/master/examples/streaming_parser.c

The callbacks are defined by

struct cbor_callbacks

Callback bundle passed to the decoder.

Public Members

cbor_int8_callback uint8

Unsigned int.

cbor_int16_callback uint16

Unsigned int.

cbor_int32_callback uint32

Unsigned int.

cbor_int64_callback uint64

Unsigned int.

cbor_int64_callback negint64

Negative int.

cbor_int32_callback negint32

Negative int.

cbor_int16_callback negint16

Negative int.

cbor_int8_callback negint8

Negative int.

cbor_simple_callback byte_string_start

Definite byte string.

cbor_string_callback byte_string

Indefinite byte string start.

cbor_string_callback string

Definite string.

cbor_simple_callback string_start

Indefinite string start.

cbor_simple_callback indef_array_start

Definite array.

cbor_collection_callback array_start

Indefinite array.

cbor_simple_callback indef_map_start

Definite map.

cbor_collection_callback map_start

Indefinite map.

cbor_int64_callback tag

Tags.

cbor_float_callback float2

Half float.

cbor_float_callback float4

Single float.

cbor_double_callback float8

Double float.

cbor_simple_callback undefined

Undef.

cbor_simple_callback null

Null.

cbor_bool_callback boolean

Bool.

cbor_simple_callback indef_break

Indefinite item break.

When building custom sets of callbacks, feel free to start from

const struct cbor_callbacks cbor_empty_callbacks

Dummy callback bundle - does nothing.

Related structures

enum cbor_decoder_status

Streaming decoder result - status.

Values:

CBOR_DECODER_FINISHED

Decoding finished successfully (a callback has been invoked)

Note that this does not mean that the buffer has been fully decoded; there may still be unread bytes for which no callback has been involved.

CBOR_DECODER_NEDATA

Not enough data to invoke a callback.

CBOR_DECODER_ERROR

Bad data (reserved MTB, malformed value, etc.)

struct cbor_decoder_result

Streaming decoder result.

Public Members

size_t read

Input bytes read/consumed.

If this is less than the size of input buffer, the client will likely resume parsing starting at the next byte (e.g. buffer + result.read).

Set to 0 if the status is not CBOR_DECODER_FINISHED.

cbor_decoder_status status

The decoding status.

size_t required

Number of bytes in the input buffer needed to resume parsing.

Set to 0 unless the result status is CBOR_DECODER_NEDATA. If it is, then:

• If at least one byte was passed, required will be set to the minimum number of bytes needed to invoke a decoded callback on the current prefix.

  For example: Attempting to decode a 1B buffer containing 0x19 will set required to 3 as 0x19 signals a 2B integer item, so we need at least 3B to continue (the 0x19 MTB byte and two bytes of data needed to invoke cbor_callbacks.uint16).

• If there was no data at all, read will always be set to 1

Callback types definition

typedef void (*cbor_int8_callback)(void *, uint8_t)

Callback prototype.

typedef void (*cbor_int16_callback)(void *, uint16_t)

Callback prototype.

typedef void (*cbor_int32_callback)(void *, uint32_t)

Callback prototype.

typedef void (*cbor_int64_callback)(void *, uint64_t)

Callback prototype.

typedef void (*cbor_simple_callback)(void *)

Callback prototype.

typedef void (*cbor_string_callback)(void *, cbor_data, size_t)

Callback prototype.

typedef void (*cbor_collection_callback)(void *, size_t)

Callback prototype.

typedef void (*cbor_float_callback)(void *, float)

Callback prototype.

typedef void (*cbor_double_callback)(void *, double)

Callback prototype.

typedef void (*cbor_bool_callback)(void *, bool)

Callback prototype.