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