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

Getting metadata

size_t cbor_bytestring_length(const cbor_item_t *item)

Returns the length of the binary data.

For definite byte strings only

param item:

a definite bytestring

return:

length of the binary data. Zero if no chunk has been attached yet

bool cbor_bytestring_is_definite(const cbor_item_t *item)

Is the byte string definite?

param item:

a byte string

return:

Is the byte string definite?

bool cbor_bytestring_is_indefinite(const cbor_item_t *item)

Is the byte string indefinite?

param item:

a byte string

return:

Is the byte string indefinite?

size_t cbor_bytestring_chunk_count(const cbor_item_t *item)

Get the number of chunks this string consist of.

param item:

A indefinite bytestring

return:

The chunk count. 0 for freshly created items.

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

param item:

A definite byte string

return:

The address of the underlying binary data

return:

NULL if no data have been assigned yet.

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.

param item:

A indefinite byte string

return:

array of cbor_bytestring_chunk_count definite bytestrings

Creating new items

cbor_item_t *cbor_new_definite_bytestring(void)

Creates a new definite byte string.

The handle is initialized to NULL and length to 0

return:

Reference to the new bytestring item. The item’s reference count is initialized to one.

return:

NULL if memory allocation fails

cbor_item_t *cbor_new_indefinite_bytestring(void)

Creates a new indefinite byte string.

The chunks array is initialized to NULL and chunk count to 0

return:

Reference to the new bytestring item. The item’s reference count is initialized to one.

return:

NULL if memory allocation fails

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

param handle:

Block of binary data

param length:

Length of data

return:

Reference to the new bytestring item. The item’s reference count is initialized to one.

return:

NULL if memory allocation fails

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.

param item:

A definite byte string

param data:

The memory block. The caller gives up the ownership of the block. libcbor will deallocate it when appropriate using the free implementation configured using cbor_set_allocs

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

param item:

An indefinite byte string

param chunk:

A definite byte string. Its reference count will be be increased by one.

return:

true on success, false on realloc failure. In that case, the refcount of chunk is not increased and the item is left intact.