API

The data API is centered around cbor_item_t, a generic handle for any CBOR item. There are functions to

• create items,

• set items’ data,

• parse serialized data into items,

• manage, move, and links item together.

The single most important thing to keep in mind is: cbor_item_t is an opaque type and should only be manipulated using the appropriate functions! Think of it as an object.

The libcbor API closely follows the semantics outlined by CBOR standard. This part of the documentation provides a short overview of the CBOR constructs, as well as a general introduction to the libcbor API. Remaining reference can be found in the following files structured by data types.

The API is designed to allow both very tight control & flexibility and general convenience with sane defaults. 1 For example, client with very specific requirements (constrained environment, custom application protocol built on top of CBOR, etc.) may choose to take full control (and responsibility) of memory and data structures management by interacting directly with the decoder. Other clients might want to take control of specific aspects (streamed collections, hash maps storage), but leave other responsibilities to libcbor. More general clients might prefer to be abstracted away from all aforementioned details and only be presented complete data structures.

libcbor provides

• stateless encoders and decoders

• encoding and decoding drivers, routines that coordinate encoding and decoding of complex structures

• data structures to represent and transform CBOR structures

• routines for building and manipulating these structures

• utilities for inspection and debugging

• Types of items
  • Binary queries
  • Logical queries
• Memory management and reference counting
  • Using custom allocator
  • Reference counting
• Decoding
  • Associated data structures
• Encoding
  • Type-specific serializers
• Types 0 & 1 – Positive and negative integers
  • Type 0 - positive integers
  • Type 1 - negative integers
  • Type 0 & 1
  • Building new items
  • Retrieving values
  • Setting values
  • Dealing with width
  • Dealing with signedness
  • Creating new items
• Type 2 – Byte strings
  • Streaming indefinite byte strings
  • Getting metadata
  • Reading data
  • Creating new items
  • Building items
  • Manipulating existing items
• Type 3 – UTF-8 strings
  • Streaming indefinite strings
  • UTF-8 encoding validation
  • Getting metadata
  • Reading data
  • Creating new items
  • Building items
  • Manipulating existing items
• Type 4 – Arrays
  • Examples
  • Streaming indefinite arrays
  • Getting metadata
  • Reading data
  • Creating new items
  • Modifying items
• Type 5 – Maps
  • Streaming maps
  • Getting metadata
  • Reading data
  • Creating new items
  • Modifying items
• Type 6 – Semantic tags
• Type 7 – Floats & control tokens
  • Getting metadata
  • Reading data
  • Creating new items
  • Building items
  • Manipulating existing items
  • Half floats

1

http://softwareengineering.vazexqi.com/files/pattern.html