xref: /freebsd-src/contrib/libcbor/doc/source/api.rst (revision 5d3e7166f6a0187fa3f8831b16a06bd9955c21ff)
110ff414cSEd MasteAPI
210ff414cSEd Maste=======
310ff414cSEd Maste
410ff414cSEd MasteThe data API is centered around :type:`cbor_item_t`, a generic handle for any CBOR item. There are functions to
510ff414cSEd Maste
610ff414cSEd Maste - create items,
710ff414cSEd Maste - set items' data,
810ff414cSEd Maste - parse serialized data into items,
910ff414cSEd Maste - manage, move, and links item together.
1010ff414cSEd Maste
1110ff414cSEd MasteThe single most important thing to keep in mind is: :type:`cbor_item_t` **is an opaque type and should only be manipulated using the appropriate functions!** Think of it as an object.
1210ff414cSEd Maste
13*5d3e7166SEd MasteThe *libcbor* API closely follows the semantics outlined by `CBOR standard <https://tools.ietf.org/html/rfc7049>`_. 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.
1410ff414cSEd Maste
1510ff414cSEd MasteThe API is designed to allow both very tight control & flexibility and general convenience with sane defaults. [#]_ 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.
1610ff414cSEd Maste
1710ff414cSEd Maste
1810ff414cSEd Maste*libcbor* provides
1910ff414cSEd Maste - stateless encoders and decoders
2010ff414cSEd Maste - encoding and decoding *drivers*, routines that coordinate encoding and decoding of complex structures
2110ff414cSEd Maste - data structures to represent and transform CBOR structures
2210ff414cSEd Maste - routines for building and manipulating these structures
2310ff414cSEd Maste - utilities for inspection and debugging
2410ff414cSEd Maste
2510ff414cSEd Maste.. toctree::
2610ff414cSEd Maste
2710ff414cSEd Maste   api/item_types
2810ff414cSEd Maste   api/item_reference_counting
2910ff414cSEd Maste   api/decoding
3010ff414cSEd Maste   api/encoding
31*5d3e7166SEd Maste   api/streaming_decoding
32*5d3e7166SEd Maste   api/streaming_encoding
3310ff414cSEd Maste   api/type_0_1
3410ff414cSEd Maste   api/type_2
3510ff414cSEd Maste   api/type_3
3610ff414cSEd Maste   api/type_4
3710ff414cSEd Maste   api/type_5
3810ff414cSEd Maste   api/type_6
3910ff414cSEd Maste   api/type_7
4010ff414cSEd Maste
4110ff414cSEd Maste.. [#] http://softwareengineering.vazexqi.com/files/pattern.html
42