Streaming Decoding

libcbor exposes a stateless decoder that reads a stream of input bytes from a buffer and invokes user-provided callbacks as it decodes the input:

struct cbor_decoder_result cbor_stream_decode(cbor_data source, size_t source_size, const struct cbor_callbacks *callbacks, void *context)

Stateless decoder.

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

param source:

Input buffer

param source_size:

Length of the buffer

param callbacks:

The callback bundle

param context:

An arbitrary pointer to allow for maintaining context.

For example, when cbor_stream_decode() encounters a 1B unsigned integer, it will invoke the function pointer stored in cbor_callbacks.uint8. Complete usage example: 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

Indefinite byte string start.

cbor_string_callback byte_string

Definite byte string.

cbor_string_callback string

Definite string.

cbor_simple_callback string_start

Indefinite string start.

cbor_simple_callback indef_array_start

Indefinite array start.

cbor_collection_callback array_start

Definite array.

cbor_simple_callback indef_map_start

Indefinite map start.

cbor_collection_callback map_start

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

Handling failures in callbacks

Callbacks receive no return value, so there is no built-in channel to signal failure back to cbor_stream_decode(). Any error that occurs inside a callback — including allocation failures, validation errors, or application-level rejections — must be tracked by the callback itself, typically via a flag in the context struct passed to cbor_stream_decode():

struct my_context {
    bool failed;
    /* ... */
};

void my_string_callback(void *context, cbor_data data, uint64_t length) {
    struct my_context *ctx = context;
    if (length > MAX_ALLOWED) {
        ctx->failed = true;
        return;
    }
    char *copy = malloc(length);
    if (copy == NULL) {
        ctx->failed = true;
        return;
    }
    /* ... */
}

After each call to cbor_stream_decode(), check the flag before continuing. Note that cbor_load() handles allocation failures internally — the CBOR_ERR_MEMERROR result code is set when a builder callback fails to allocate memory.

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, uint64_t)

Callback prototype.

typedef void (*cbor_collection_callback)(void*, uint64_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.