Type 2 – Byte strings

CBOR byte strings are just (ordered) series of bytes without further interpretation (unless there is a tag). Byte string’s length may or may not be known during encoding. These two kinds of byte strings can be distinguished using cbor_bytestring_is_definite() and cbor_bytestring_is_indefinite() respectively.

In case a byte string is indefinite, it is encoded as a series of definite byte strings. These are called “chunks”. For example, the encoded item

0xf5            Start indefinite byte string
    0x41        Byte string (1B long)
        0x00
    0x41        Byte string (1B long)
        0xff
    0xff        "Break" control token

represents two bytes, 0x00 and 0xff. This on one hand enables streaming messages even before they are fully generated, but on the other hand it adds more complexity to the client code.

Corresponding cbor_type CBOR_TYPE_BYTESTRING
Number of allocations (definite) One plus any manipulations with the data
Number of allocations (indefinite) One plus logarithmically many reallocations relative to chunk count
Storage requirements (definite) sizeof(cbor_item_t) + length(handle)
Storage requirements (indefinite) sizeof(cbor_item_t) * (1 + chunk_count) + chunks

Streaming indefinite byte strings

Please refer to Streaming & indefinite items.

Getting metadata

size_t cbor_bytestring_length(const cbor_item_t *item)

Returns the length of the binary data.

For definite byte strings only

Return
length of the binary data. Zero if no chunk has been attached yet
Parameters
  • item[borrow] -

    a definite bytestring

bool cbor_bytestring_is_definite(const cbor_item_t *item)

Is the byte string definite?

Return
Is the byte string definite?
Parameters
  • item[borrow] -

    a byte string

bool cbor_bytestring_is_indefinite(const cbor_item_t *item)

Is the byte string indefinite?

Return
Is the byte string indefinite?
Parameters
  • item[borrow] -

    a byte string

size_t cbor_bytestring_chunk_count(const cbor_item_t *item)

Get the number of chunks this string consist of.

Return
The chunk count. 0 for freshly created items.
Parameters
  • item[borrow] -

    A indefinite bytestring

Reading data

cbor_mutable_data cbor_bytestring_handle(const cbor_item_t *item)

Get the handle to the binary data.

Definite items only. Modifying the data is allowed. In that case, the caller takes responsibility for the effect on items this item might be a part of

Return
The address of the binary data. NULL if no data have been assigned yet.
Parameters
  • item[borrow] -

    A definite byte string

cbor_item_t **cbor_bytestring_chunks_handle(const cbor_item_t *item)

Get the handle to the array of chunks.

Manipulations with the memory block (e.g. sorting it) are allowed, but the validity and the number of chunks must be retained.

Return
array of cbor_bytestring_chunk_count definite bytestrings
Parameters
  • item[borrow] -

    A indefinite byte string

Creating new items

cbor_item_t *cbor_new_definite_bytestring()

Creates a new definite byte string.

The handle is initialized to NULL and length to 0

Return
new definite bytestring. NULL on malloc failure.

cbor_item_t *cbor_new_indefinite_bytestring()

Creates a new indefinite byte string.

The chunks array is initialized to NULL and chunkcount to 0

Return
new indefinite bytestring. NULL on malloc failure.

Building items

cbor_item_t *cbor_build_bytestring(cbor_data handle, size_t length)

Creates a new byte string and initializes it.

The handle will be copied to a newly allocated block

Return
A new byte string with content handle. NULL on malloc failure.
Parameters
  • handle -

    Block of binary data

  • length -

    Length of data

Manipulating existing items

void cbor_bytestring_set_handle(cbor_item_t * item, cbor_mutable_data restrict data, size_t length)

Set the handle to the binary data.

Parameters
  • item[borrow] -

    A definite byte string

  • data -

    The memory block. The caller gives up the ownership of the block. libcbor will deallocate it when appropriate using its free function

  • length -

    Length of the data block

bool cbor_bytestring_add_chunk(cbor_item_t *item, cbor_item_t *chunk)

Appends a chunk to the bytestring.

Indefinite byte strings only.

May realloc the chunk storage.

Return
true on success, false on realloc failure. In that case, the refcount of chunk is not increased and the item is left intact.
Parameters
  • item[borrow] -

    An indefinite byte string

  • item[incref] -

    A definite byte string