1LIBCBOR(1)                          libcbor                         LIBCBOR(1)
2
3
4

NAME

6       libcbor - libcbor Documentation
7
8       Documentation for version 0.7.0, updated on Jan 19, 2023.
9

OVERVIEW

11       libcbor  is  a  C  library  for  parsing  and generating CBOR, the gen‐
12       eral-purpose schema-less binary data format.
13
14       Main features
15
16              • Complete RFC conformance [1]
17
18              • Robust C99 implementation
19
20              • Layered architecture offers both control and convenience
21
22              • Flexible memory management
23
24              • No shared global state - threading friendly [2]
25
26              • Proper handling of UTF-8
27
28              • Full support for streams & incremental processing
29
30              • Extensive documentation and test suite
31
32              • No runtime dependencies, small footprint
33
34       [1]  See RFC conformance
35
36       [2]  With the exception of custom memory allocators (see Memory manage‐
37            ment and reference counting)
38

CONTENTS

40   Getting started
41       Pre-built Linux packages are distributed from the libcbor website.
42
43       OS X users can use Homebrew:
44
45          brew tap pjk/libcbor
46          brew install libcbor
47
48       For other platforms, you will need to compile it from source.
49
50   Building & installing libcbor
51       Prerequisites:
52
53              • C99 compiler
54
55CMake 2.8 or newer (might also be called cmakesetup, cmake-gui
56                or ccmake depending on the installed version and system)
57
58              • C build system CMake can target  (make,  Apple  Xcode,  MinGW,
59                ...)
60
61       NOTE:
62          As of May 2015, not even the 2015 release candidate of Visual Studio
63          supports C99. While CMake will be happy to generate  a  VS  solution
64          that  you  can play with, libcbor currently cannot be compiled using
65          the MSVC toolchain. ICC, GCC under Cygwin, and MinGW's GCC will  all
66          work. The MinGW build process is described below.
67
68       Configuration options
69
70       A  handful of configuration flags can be passed to cmake. The following
71       table lists  libcbor  compile-time  directives  and  several  important
72       generic flags.
73
74     ┌─────────────────┬──────────────────┬──────────────────┬──────────────────┐
75     │Option           │ Meaning          │ Default          │ Possible values  │
76     ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
77CMAKE_C_COMPILER │ C   compiler  to │ cc               gcc,      clang, │
78     │                 │ use              │                  │ clang-3.5, ...   │
79     ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
80CMAKE_IN‐        │ Installation     │ System-dependent │ /usr/local/lib,  │
81STALL_PREFIX     │ prefix           │                  │ ...              │
82     ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
83HUGE_FUZZ        Fuzz  test  with │ OFF              ON, OFF          
84     │                 │ 8GB of data      │                  │                  │
85     ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
86SANE_MALLOC      │ Assume    malloc OFF              ON, OFF          
87     │                 │ will refuse  un‐ │                  │                  │
88     │                 │ reasonable allo‐ │                  │                  │
89     │                 │ cations          │                  │                  │
90     ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
91COVERAGE         │ Generate    test │ OFF              ON, OFF          
92     │                 │ coverage instru‐ │                  │                  │
93     │                 │ mentation        │                  │                  │
94     ├─────────────────┼──────────────────┼──────────────────┼──────────────────┤
95WITH_TESTS       │ Build unit tests │ OFF              ON, OFF          
96     │                 │ (see             │                  │                  │
97     │                 │ Development)     │                  │                  │
98     └─────────────────┴──────────────────┴──────────────────┴──────────────────┘
99
100       The following configuration options will also be defined as  macros[#]_
101       in <cbor/common.h> and can therefore be used in client code:
102
103        ┌────────────────────┬──────────────────┬─────────┬─────────────────┐
104        │Option              │ Meaning          │ Default │ Possible values │
105        ├────────────────────┼──────────────────┼─────────┼─────────────────┤
106CBOR_CUSTOM_AL‐     │ Enable    custom │ OFF     ON, OFF         
107LOC                 │ allocator   sup‐ │         │                 │
108        │                    │ port             │         │                 │
109        ├────────────────────┼──────────────────┼─────────┼─────────────────┤
110CBOR_PRETTY_PRINTER │ Include        a │ ON      ON, OFF         
111        │                    │ pretty-printing  │         │                 │
112        │                    │ routine          │         │                 │
113        ├────────────────────┼──────────────────┼─────────┼─────────────────┤
114CBOR_BUFFER_GROWTH  │ Factor  for buf‐ │ 2       │ Decimals > 1    │
115        │                    │ fer   growth   & │         │                 │
116        │                    │ shrinking        │         │                 │
117        └────────────────────┴──────────────────┴─────────┴─────────────────┘
118
119       [1]  ON & OFF will be translated to 1 and 0 using cmakedefine.
120
121            If you want to pass other custom configuration options, please re‐
122            fer to http://www.cmake.org/Wiki/CMake_Useful_Variables.
123
124            Building using make
125
126            CMake will generate a Makefile and other configuration  files  for
127            the build. As a rule of thumb, you should configure the build out‐
128            side of the source tree in order to keep different  configurations
129            isolated. If you are unsure where to execute the build, just use a
130            temporary directory:
131
132          cd $(mktemp -d /tmp/cbor_build.XXXX)
133
134       Now, assuming you are in the directory where you want to build, execute
135       the following to configure the build and run make
136
137          cmake -DCMAKE_BUILD_TYPE=Release path_to_libcbor_dir
138          make cbor cbor_shared
139
140       Both  the  shared  (libcbor.so)  and  the  static (libcbor.a) libraries
141       should now be in the src subdirectory.
142
143       In order to install the libcbor headers and libraries, the usual
144
145          make install
146
147       is what your're looking for. Root permissions are required on most sys‐
148       tems when using the default installation prefix.
149
150       Portability
151
152       libcbor  is  highly  portable  and works on both little- and big-endian
153       systems regardless of the operating system. After building on an exotic
154       platform,  you  might  wish  to  verify  the result by running the test
155       suite. If you encounter any problems, please report them to  the  issue
156       tracker.
157
158       libcbor   is  known  to  successfully  work  on  ARM  Android  devices.
159       Cross-compilation is possible with arm-linux-gnueabi-gcc.
160
161   Linking with libcbor
162       If you include and linker paths include the directories to which  libc‐
163       bor  has  been installed, compiling programs that uses libcbor requires
164       no extra considerations.
165
166       You can verify that everything has been set up properly by  creating  a
167       file with the following contents
168
169          #include <cbor.h>
170          #include <stdio.h>
171
172          int main(int argc, char * argv[])
173          {
174              printf("Hello from libcbor %s\n", CBOR_VERSION);
175          }
176
177       and compiling it
178
179          cc hello_cbor.c -lcbor -o hello_cbor
180
181       libcbor also comes with pkg-config support. If you install libcbor with
182       a custom prefix, you can use pkg-config to resolve the headers and  ob‐
183       jects:
184
185          cc $(pkg-config --cflags libcbor) hello_cbor.c $(pkg-config --libs libcbor) -o hello_cbor
186
187       A note on linkage
188
189       libcbor  is  primarily intended to be linked statically. The shared li‐
190       brary versioning scheme generally follows SemVer, but is irregular  for
191       the 0.X.Y development branch for historical reasons. The following ver‐
192       sion identifiers are used as a part of the SONAME (Linux) or the  dylib
193       "Compatibility version" (OS X):
194
195          • 0.Y  for the 0.Y.Z branch. Patches are backwards compatible, minor
196            releases are generally not and require re-compilation of  any  de‐
197            pendent code.
198
199          • X  for the X.Y.Z stable versions starting 1.X.Y. All minor release
200            of the major version are backwards compatible.
201
202       WARNING:
203          Please note that releases up to and including v0.6.0 may export mis‐
204          leading .so/.dylib version number.
205
206   MinGW build instructions
207       Prerequisites:
208
209              • MinGW
210
211              • CMake GUI
212
213       First  of  all,  create  a folder that will be used for the output. For
214       this demonstration, we will use cbor_out. Start CMake  and  select  the
215       source path and the destination folder.  [image]
216
217       Then  hit  the  'Configure'  button. You will be prompted to select the
218       build system: [image]
219
220       Choose MinGW and confirm.
221
222       NOTE:
223          If you select Visual Studio at this point, a MSVC  project  will  be
224          generated for you. This is useful if you just want to browse through
225          the source code.
226
227       You can then adjust the build options.  The  defaults  will  work  just
228       fine. Hit 'Generate' when you are done.  [image]
229
230       You  can  then  adjust  the  build options. The defaults will work just
231       fine. Hit 'Generate' when you are done.
232
233       Open the shell, navigate to the output directory, and run  mingw32-make
234       cbor cbor_shared.  [image]
235
236       libcbor  will be built and your .dll should be ready at this point [im‐
237       age]
238
239       Feel free to also try building and running some of the  examples,  e.g.
240       mingw32-make sort [image]
241
242   Troubleshooting
243       cbor.h not found: The headers directory is probably not in your include
244       path. First, verify the installation location by checking the installa‐
245       tion log. If you used make, it will look something like
246
247          ...
248          -- Installing: /usr/local/include/cbor
249          -- Installing: /usr/local/include/cbor/callbacks.h
250          -- Installing: /usr/local/include/cbor/encoding.h
251          ...
252
253       Make  sure  that CMAKE_INSTALL_PREFIX (if you provided it) was correct.
254       Including the path path during compilation should suffice, e.g.:
255
256          cc -I/usr/local/include hello_cbor.c -lcbor -o hello_cbor
257
258       cannot find -lcbor during linking: Most likely the same problem as  be‐
259       fore.  Include the installation directory in the linker shared path us‐
260       ing -R, e.g.:
261
262          cc -Wl,-rpath,/usr/local/lib -lcbor -o hello_cbor
263
264       shared library missing during execution: Verify the linkage using  ldd,
265       otool, or similar and adjust the compilation directives accordingly:
266
267          ⇒  ldd hello_cbor
268              linux-vdso.so.1 =>  (0x00007ffe85585000)
269              libcbor.so => /usr/local/lib/libcbor.so (0x00007f9af69da000)
270              libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f9af65eb000)
271              /lib64/ld-linux-x86-64.so.2 (0x00007f9af6be9000)
272
273       compilation  failed:  If your compiler supports C99 yet the compilation
274       has failed, please report the issue to the issue tracker.
275
276   Usage & preliminaries
277   Version information
278       libcbor exports its version using three self-explanatory macros:
279
280CBOR_MAJOR_VERSION
281
282CBOR_MINOR_VERSION
283
284CBOR_PATCH_VERSION
285
286       The CBOR_VERSION is a string concatenating these three identifiers into
287       one (e.g. 0.2.0).
288
289       In  order to simplify version comparisons, the version is also exported
290       as
291
292          #define CBOR_HEX_VERSION ((CBOR_MAJOR_VERSION << 16) | (CBOR_MINOR_VERSION << 8) | CBOR_PATCH_VERSION)
293
294       Since macros are difficult to work with through FFIs, the same informa‐
295       tion is also available through three uint8_t constants, namely
296
297cbor_major_version
298
299cbor_minor_version
300
301cbor_patch_version
302
303   Headers to include
304       The  cbor.h  header  includes  all the symbols. If, for any reason, you
305       don't want to include all the exported symbols, feel free to  use  just
306       some of the cbor/*.h headers:
307
308cbor/arrays.h - Type 4  Arrays
309
310cbor/bytestrings.h - Type 2  Byte strings
311
312cbor/callbacks.h - Callbacks used for Decoding
313
314cbor/common.h - Common utilities - always transitively included
315
316cbor/data.h  -  Data  types  definitions - always transitively in‐
317            cluded
318
319cbor/encoding.h - Streaming encoders for Encoding
320
321cbor/floats_ctrls.h - Type 7  Floats & control tokens
322
323cbor/ints.h - Types 0 & 1  Positive and negative integers
324
325cbor/maps.h - Type 5  Maps
326
327cbor/serialization.h  -   High   level   serialization   such   as
328            cbor_serialize()
329
330cbor/streaming.h - Home of cbor_stream_decode()
331
332cbor/strings.h - Type 3  UTF-8 strings
333
334cbor/tags.h - Type 6  Semantic tags
335
336   Using libcbor
337       If  you  want  to get more familiar with CBOR, we recommend the cbor.io
338       website. Once you get the grasp of what is it CBOR does,  the  examples
339       (located  in the examples directory) should give you a good feel of the
340       API. The API documentation should then provide with all the information
341       you may need.
342
343       Creating and serializing items
344
345          #include "cbor.h"
346          #include <stdio.h>
347
348          int main(int argc, char * argv[])
349          {
350              /* Preallocate the map structure */
351              cbor_item_t * root = cbor_new_definite_map(2);
352              /* Add the content */
353              cbor_map_add(root, (struct cbor_pair) {
354                  .key = cbor_move(cbor_build_string("Is CBOR awesome?")),
355                  .value = cbor_move(cbor_build_bool(true))
356              });
357              cbor_map_add(root, (struct cbor_pair) {
358                  .key = cbor_move(cbor_build_uint8(42)),
359                  .value = cbor_move(cbor_build_string("Is the answer"))
360              });
361              /* Output: `length` bytes of data in the `buffer` */
362              unsigned char * buffer;
363              size_t buffer_size, length = cbor_serialize_alloc(root, &buffer, &buffer_size);
364
365              fwrite(buffer, 1, length, stdout);
366              free(buffer);
367
368              fflush(stdout);
369              cbor_decref(&root);
370          }
371
372       Reading serialized data
373
374          #include "cbor.h"
375          #include <stdio.h>
376
377          /*
378           * Reads data from a file. Example usage:
379           * $ ./examples/readfile examples/data/nested_array.cbor
380           */
381
382          int main(int argc, char * argv[])
383          {
384              FILE * f = fopen(argv[1], "rb");
385              fseek(f, 0, SEEK_END);
386              size_t length = (size_t)ftell(f);
387              fseek(f, 0, SEEK_SET);
388              unsigned char * buffer = malloc(length);
389              fread(buffer, length, 1, f);
390
391              /* Assuming `buffer` contains `info.st_size` bytes of input data */
392              struct cbor_load_result result;
393              cbor_item_t * item = cbor_load(buffer, length, &result);
394              /* Pretty-print the result */
395              cbor_describe(item, stdout);
396              fflush(stdout);
397              /* Deallocate the result */
398              cbor_decref(&item);
399
400              fclose(f);
401          }
402
403       Using the streaming parser
404
405          #include "cbor.h"
406          #include <stdio.h>
407          #include <string.h>
408
409          /*
410           * Illustrates how one might skim through a map (which is assumed to have
411           * string keys and values only), looking for the value of a specific key
412           *
413           * Use the examples/data/map.cbor input to test this.
414           */
415
416          const char * key = "a secret key";
417          bool key_found = false;
418
419          void find_string(void * _ctx, cbor_data buffer, size_t len)
420          {
421              if (key_found) {
422                  printf("Found the value: %*s\n", (int) len, buffer);
423                  key_found = false;
424              } else if (len == strlen(key)) {
425                  key_found = (memcmp(key, buffer, len) == 0);
426              }
427          }
428
429          int main(int argc, char * argv[])
430          {
431              FILE * f = fopen(argv[1], "rb");
432              fseek(f, 0, SEEK_END);
433              size_t length = (size_t)ftell(f);
434              fseek(f, 0, SEEK_SET);
435              unsigned char * buffer = malloc(length);
436              fread(buffer, length, 1, f);
437
438              struct cbor_callbacks callbacks = cbor_empty_callbacks;
439              struct cbor_decoder_result decode_result;
440              size_t bytes_read = 0;
441              callbacks.string = find_string;
442              while (bytes_read < length) {
443                  decode_result = cbor_stream_decode(buffer + bytes_read,
444                                                     length - bytes_read,
445                                                     &callbacks, NULL);
446                  bytes_read += decode_result.read;
447              }
448
449              fclose(f);
450          }
451
452   API
453       The  data  API is centered around cbor_item_t, a generic handle for any
454       CBOR item. There are functions to
455
456          • create items,
457
458          • set items' data,
459
460          • parse serialized data into items,
461
462          • manage, move, and links item together.
463
464       The single most important thing to keep in mind is: cbor_item_t  is  an
465       opaque  type and should only be manipulated using the appropriate func‐
466       tions! Think of it as an object.
467
468       The libcbor API closely follows the semantics outlined  by  CBOR  stan‐
469       dard.  This  part of the documentation provides a short overview of the
470       CBOR constructs, as well as a general introduction to the libcbor  API.
471       Remaining  reference  can be found in the following files structured by
472       data types.
473
474       The API is designed to allow both very tight control & flexibility  and
475       general  convenience  with  sane defaults. [1] For example, client with
476       very specific requirements (constrained environment, custom application
477       protocol  built  on  top of CBOR, etc.) may choose to take full control
478       (and responsibility) of memory and data structures management by inter‐
479       acting directly with the decoder. Other clients might want to take con‐
480       trol of specific aspects (streamed collections, hash maps storage), but
481       leave  other  responsibilities  to  libcbor. More general clients might
482       prefer to be abstracted away from all aforementioned details  and  only
483       be presented complete data structures.
484
485       libcbor provides
486
487              • stateless encoders and decoders
488
489              • encoding and decoding drivers, routines that coordinate encod‐
490                ing and decoding of complex structures
491
492              • data structures to represent and transform CBOR structures
493
494              • routines for building and manipulating these structures
495
496              • utilities for inspection and debugging
497
498   Types of items
499       Every cbor_item_t has a cbor_type associated with it - these  constants
500       correspond to the types specified by the CBOR standard:
501
502       enum cbor_type
503              Specifies the Major type of cbor_item_t.
504
505              Values:
506
507              enumerator CBOR_TYPE_UINT
508                     0 - positive integers
509
510              enumerator CBOR_TYPE_NEGINT
511                     1 - negative integers
512
513              enumerator CBOR_TYPE_BYTESTRING
514                     2 - byte strings
515
516              enumerator CBOR_TYPE_STRING
517                     3 - strings
518
519              enumerator CBOR_TYPE_ARRAY
520                     4 - arrays
521
522              enumerator CBOR_TYPE_MAP
523                     5 - maps
524
525              enumerator CBOR_TYPE_TAG
526                     6 - tags
527
528              enumerator CBOR_TYPE_FLOAT_CTRL
529                     7 - decimals and special values (true, false, nil, ...)
530
531       To find out the type of an item, one can use
532
533       cbor_type cbor_typeof(const cbor_item_t *item)
534              Get the type of the item.
535
536              param item[borrow]
537
538
539              return The type
540
541       Please  note the distinction between functions like cbor_isa_uint() and
542       cbor_is_int(). The following functions work solely with the major  type
543       value.
544
545   Binary queries
546       Alternatively, there are functions to query each particular type.
547
548       WARNING:
549          Passing  an  invalid cbor_item_t reference to any of these functions
550          results in undefined behavior.
551
552       bool cbor_isa_uint(const cbor_item_t *item)
553              Does the item have the appropriate major type?
554
555              param item[borrow]
556                     the item
557
558              return Is the item an CBOR_TYPE_UINT?
559
560       bool cbor_isa_negint(const cbor_item_t *item)
561              Does the item have the appropriate major type?
562
563              param item[borrow]
564                     the item
565
566              return Is the item a CBOR_TYPE_NEGINT?
567
568       bool cbor_isa_bytestring(const cbor_item_t *item)
569              Does the item have the appropriate major type?
570
571              param item[borrow]
572                     the item
573
574              return Is the item a CBOR_TYPE_BYTESTRING?
575
576       bool cbor_isa_string(const cbor_item_t *item)
577              Does the item have the appropriate major type?
578
579              param item[borrow]
580                     the item
581
582              return Is the item a CBOR_TYPE_STRING?
583
584       bool cbor_isa_array(const cbor_item_t *item)
585              Does the item have the appropriate major type?
586
587              param item[borrow]
588                     the item
589
590              return Is the item an CBOR_TYPE_ARRAY?
591
592       bool cbor_isa_map(const cbor_item_t *item)
593              Does the item have the appropriate major type?
594
595              param item[borrow]
596                     the item
597
598              return Is the item a CBOR_TYPE_MAP?
599
600       bool cbor_isa_tag(const cbor_item_t *item)
601              Does the item have the appropriate major type?
602
603              param item[borrow]
604                     the item
605
606              return Is the item a CBOR_TYPE_TAG?
607
608       bool cbor_isa_float_ctrl(const cbor_item_t *item)
609              Does the item have the appropriate major type?
610
611              param item[borrow]
612                     the item
613
614              return Is the item a CBOR_TYPE_FLOAT_CTRL?
615
616   Logical queries
617       These functions provide information about the item  type  from  a  more
618       high-level perspective
619
620       bool cbor_is_int(const cbor_item_t *item)
621              Is the item an integer, either positive or negative?
622
623              param item[borrow]
624                     the item
625
626              return Is the item an integer, either positive or negative?
627
628       bool cbor_is_float(const cbor_item_t *item)
629              Is the item an a floating point number?
630
631              param item[borrow]
632                     the item
633
634              return Is the item a floating point number?
635
636       bool cbor_is_bool(const cbor_item_t *item)
637              Is the item an a boolean?
638
639              param item[borrow]
640                     the item
641
642              return Is the item a boolean?
643
644       bool cbor_is_null(const cbor_item_t *item)
645              Does this item represent null
646
647              null pointer will most likely result in a crash.
648
649
650
651              WARNING:
652                 This  is in no way related to the value of the pointer. Pass‐
653                 ing a
654
655              param item[borrow]
656                     the item
657
658              return Is the item (CBOR logical) null?
659
660       bool cbor_is_undef(const cbor_item_t *item)
661              Does this item represent undefined
662
663
664              C.
665
666
667
668              WARNING:
669                 Care must be taken to distinguish nulls and undefined  values
670                 in
671
672              param item[borrow]
673                     the item
674
675              return Is the item (CBOR logical) undefined?
676
677   Memory management and reference counting
678       Due  to  the  nature of its domain, libcbor will need to work with heap
679       memory. The stateless decoder and encoder don't allocate any memory.
680
681       If you have specific requirements, you should consider rolling your own
682       driver for the stateless API.
683
684   Using custom allocator
685       libcbor  gives you with the ability to provide your own implementations
686       of malloc, realloc, and free. This can be useful if  you  are  using  a
687       custom  allocator throughout your application, or if you want to imple‐
688       ment custom policies (e.g. tighter restrictions on the amount of  allo‐
689       cated memory).
690
691       In  order  to  use  this  feature,  libcbor has to be compiled with the
692       appropriate flags. You can verify the configuration using the CBOR_CUS‐
693       TOM_ALLOC macro. A simple usage might be as follows:
694
695          #if CBOR_CUSTOM_ALLOC
696                  cbor_set_allocs(malloc, realloc, free);
697          #else
698             #error "libcbor built with support for custom allocation is required"
699          #endif
700
701       void cbor_set_allocs(_cbor_malloc_t custom_malloc, _cbor_realloc_t cus‐
702       tom_realloc, _cbor_free_t custom_free)
703              Sets the memory management routines to use.
704
705              Only available when CBOR_CUSTOM_ALLOC is truthy
706
707              used accordingly. Changing the memory handlers  while  allocated
708              items exist will result in a free/malloc mismatch. This function
709              is not thread safe with respect to both itself and all the other
710              libcbor  functions  that  work with the heap.  .. note:: realloc
711              implementation must correctly  support  NULL  reallocation  (see
712              e.g. http://en.cppreference.com/w/c/memory/realloc)
713
714
715              WARNING:
716                 This  function modifies the global state and should therefore
717                 be
718
719              param custom_malloc
720                     malloc implementation
721
722              param custom_realloc
723                     realloc implementation
724
725              param custom_free
726                     free implementation
727
728   Reference counting
729       As CBOR items may require complex cleanups at the end  of  their  life‐
730       time,  there  is a reference counting mechanism in place. This also en‐
731       ables very simple GC when integrating libcbor into managed environment.
732       Every item starts its life (by either explicit creation, or as a result
733       of parsing) with reference count set to 1. When  the  refcount  reaches
734       zero, it will be destroyed.
735
736       Items  containing nested items will be destroyed recursively - refcount
737       of every nested item will be decreased by one.
738
739       The destruction is synchronous and renders any pointers to  items  with
740       refcount zero invalid immediately after calling the cbor_decref().
741
742       cbor_item_t *cbor_incref(cbor_item_t *item)
743              Increases the reference count by one.
744
745              No dependent items are affected.
746
747              param item[incref]
748                     item the item
749
750              return the input reference
751
752       void cbor_decref(cbor_item_t **item)
753              Decreases  the  reference count by one, deallocating the item if
754              needed.
755
756              In case the item is deallocated, the reference count of any  de‐
757              pendent items is adjusted accordingly in a recursive manner.
758
759              param item[take]
760                     the item. Set to NULL if deallocated
761
762       void cbor_intermediate_decref(cbor_item_t *item)
763              Decreases  the  reference count by one, deallocating the item if
764              needed.
765
766              Convenience wrapper for cbor_decref when its set-to-null  behav‐
767              ior is not needed
768
769              param item[take]
770                     the item
771
772       size_t cbor_refcount(const cbor_item_t *item)
773              Get the reference count.
774
775              WARNING:
776                 This does not account for transitive references.
777
778              param item[borrow]
779                     the item
780
781              return the reference count
782
783       cbor_item_t *cbor_move(cbor_item_t *item)
784              Provides CPP-like move construct.
785
786              Decreases  the  reference  count by one, but does not deallocate
787              the item even if its refcount reaches zero. This is  useful  for
788              passing intermediate values to functions that increase reference
789              count. Should only be used with functions that incref their  ar‐
790              guments.
791
792              count afterwards, the memory will be leaked.
793
794
795              WARNING:
796                 If  the item is moved without correctly increasing the refer‐
797                 ence
798
799              param item[take]
800                     the item
801
802              return the item with reference count decreased by one
803
804       cbor_item_t *cbor_copy(cbor_item_t *item)
805              Deep copy of an item.
806
807              All the reference counts in the new structure are set to one.
808
809              param item[borrow]
810                     item to copy
811
812              return new CBOR deep copy
813
814   Decoding
815       The following diagram  illustrates  the  relationship  among  different
816       parts of libcbor from the decoding standpoint.
817
818          ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
819          │                                                                                              │
820          │                                      Client application                                      │
821          │                                                                                              │
822          │                                                 ┌────────────────────────────────────────────┘
823          │                                                 │                     ↕
824          │                                                 │ ┌──────────────────────────────────────────┐
825          │                                                 │ │                                          │
826          │                                                 │ │          Manipulation routines           │
827          │                                                 │ │                                          │
828          │           ┌─────────────────────────────────────┘ └──────────────────────────────────────────┘
829          │           │     ↑    ↑                  ↑                              ↑
830          │           │     │    │    ┌─────────────╫──────────┬───────────────────┴─┐
831          │           │     │   CDS   │             ║          │                     │
832          │           │     │    │   PDS            ║         PDS                   PDS
833          │           │     ↓    ↓    ↓             ↓          ↓                     ↓
834          │           │ ┌─────────────────┐   ┌────────────────────┐   ┌────────────────────────────┐
835          │           │ │                 │   │                    │   │                            │
836          │           │ │  Custom driver  │ ↔ │  Streaming driver  │ ↔ │       Default driver       │ ↔ CD
837          │           │ │                 │   │                    │   │                            │
838          └───────────┘ └─────────────────┘   └────────────────────┘   └────────────────────────────┘
839                ↕                ↕                        ↕                           ↕
840          ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
841          │                                                                                              │
842          │                            Stateless event─driven decoder                                    │
843          │                                                                                              │
844          └──────────────────────────────────────────────────────────────────────────────────────────────┘
845
846                        (PSD = Provided Data Structures, CDS = Custom Data Structures)
847
848       This  section  will  deal  with the API that is labeled as the "Default
849       driver" in the diagram. That is, routines that decode complete  libcbor
850       data items
851
852       cbor_item_t  *cbor_load(cbor_data  source,  size_t  source_size, struct
853       cbor_load_result *result)
854              Loads data item from a buffer.
855
856              param source
857                     The buffer
858
859              param source_size
860
861
862              param result[out]
863                     Result indicator. CBOR_ERR_NONE on success
864
865              return new CBOR item or NULL on failure. In  that  case,  result
866                     contains location and description of the error.
867
868   Associated data structures
869       enum cbor_error_code
870              Possible decoding errors.
871
872              Values:
873
874              enumerator CBOR_ERR_NONE
875
876              enumerator CBOR_ERR_NOTENOUGHDATA
877
878              enumerator CBOR_ERR_NODATA
879
880              enumerator CBOR_ERR_MALFORMATED
881
882              enumerator CBOR_ERR_MEMERROR
883                     Memory error - item allocation failed.
884
885                     Is it too big for your allocator?
886
887              enumerator CBOR_ERR_SYNTAXERROR
888                     Stack parsing algorithm failed.
889
890       struct cbor_load_result
891              High-level decoding result.
892
893              Public Members
894
895              struct cbor_error error
896                     Error indicator.
897
898              size_t read
899                     Number of bytes read.
900
901       struct cbor_error
902              High-level decoding error.
903
904              Public Members
905
906              size_t position
907                     Aproximate position.
908
909              cbor_error_code code
910                     Description.
911
912   Encoding
913       The  easiest  way to encode data items is using the cbor_serialize() or
914       cbor_serialize_alloc() functions:
915
916       size_t cbor_serialize(const cbor_item_t *item,  cbor_mutable_data  buf‐
917       fer, size_t buffer_size)
918              Serialize the given item.
919
920              param item[borrow]
921                     A data item
922
923              param buffer
924                     Buffer to serialize to
925
926              param buffer_size
927                     Size of the buffer
928
929              return Length of the result. 0 on failure.
930
931       size_t  cbor_serialize_alloc(const cbor_item_t *item, cbor_mutable_data
932       *buffer, size_t *buffer_size)
933              Serialize the given item, allocating buffers as needed.
934
935              appropriate free implementation.
936
937
938              WARNING:
939                 It is your responsibility to free the buffer using an
940
941              param item[borrow]
942                     A data item
943
944              param buffer[out]
945                     Buffer containing the result
946
947              param buffer_size[out]
948                     Size of the buffer
949
950              return Length of the result. 0 on failure, in which case  buffer
951                     is NULL.
952
953   Type-specific serializers
954       In case you know the type of the item you want to serialize beforehand,
955       you can use one of the type-specific serializers.
956
957       NOTE:
958          Unless compiled in debug mode, these do not verify the type. Passing
959          an incorrect item will result in an undefined behavior.
960
961       size_t  cbor_serialize_uint(const  cbor_item_t *item, cbor_mutable_data
962       buffer, size_t buffer_size)
963              Serialize an uint.
964
965              param item[borrow]
966                     A uint
967
968              param buffer
969                     Buffer to serialize to
970
971              param buffer_size
972                     Size of the buffer
973
974              return Length of the result. 0 on failure.
975
976       size_t cbor_serialize_negint(const cbor_item_t *item, cbor_mutable_data
977       buffer, size_t buffer_size)
978              Serialize a negint.
979
980              param item[borrow]
981                     A neging
982
983              param buffer
984                     Buffer to serialize to
985
986              param buffer_size
987                     Size of the buffer
988
989              return Length of the result. 0 on failure.
990
991       size_t  cbor_serialize_bytestring(const  cbor_item_t  *item, cbor_muta‐
992       ble_data buffer, size_t buffer_size)
993              Serialize a bytestring.
994
995              param item[borrow]
996                     A bytestring
997
998              param buffer
999                     Buffer to serialize to
1000
1001              param buffer_size
1002                     Size of the buffer
1003
1004              return Length of the result. 0 on failure.
1005
1006       size_t cbor_serialize_string(const cbor_item_t *item, cbor_mutable_data
1007       buffer, size_t buffer_size)
1008              Serialize a string.
1009
1010              param item[borrow]
1011                     A string
1012
1013              param buffer
1014                     Buffer to serialize to
1015
1016              param buffer_size
1017                     Size of the buffer
1018
1019              return Length of the result. 0 on failure.
1020
1021       size_t  cbor_serialize_array(const cbor_item_t *item, cbor_mutable_data
1022       buffer, size_t buffer_size)
1023              Serialize an array.
1024
1025              param item[borrow]
1026                     An array
1027
1028              param buffer
1029                     Buffer to serialize to
1030
1031              param buffer_size
1032                     Size of the buffer
1033
1034              return Length of the result. 0 on failure.
1035
1036       size_t cbor_serialize_map(const  cbor_item_t  *item,  cbor_mutable_data
1037       buffer, size_t buffer_size)
1038              Serialize a map.
1039
1040              param item[borrow]
1041                     A map
1042
1043              param buffer
1044                     Buffer to serialize to
1045
1046              param buffer_size
1047                     Size of the buffer
1048
1049              return Length of the result. 0 on failure.
1050
1051       size_t  cbor_serialize_tag(const  cbor_item_t  *item, cbor_mutable_data
1052       buffer, size_t buffer_size)
1053              Serialize a tag.
1054
1055              param item[borrow]
1056                     A tag
1057
1058              param buffer
1059                     Buffer to serialize to
1060
1061              param buffer_size
1062                     Size of the buffer
1063
1064              return Length of the result. 0 on failure.
1065
1066       size_t cbor_serialize_float_ctrl(const  cbor_item_t  *item,  cbor_muta‐
1067       ble_data buffer, size_t buffer_size)
1068              Serialize a.
1069
1070              param item[borrow]
1071                     A float or ctrl
1072
1073              param buffer
1074                     Buffer to serialize to
1075
1076              param buffer_size
1077                     Size of the buffer
1078
1079              return Length of the result. 0 on failure.
1080
1081   Types 0 & 1 – Positive and negative integers
1082       CBOR has two types of integers – positive (which may be effectively re‐
1083       garded as unsigned), and negative. There are four possible  widths  for
1084       an integer – 1, 2, 4, or 8 bytes. These are represented by
1085
1086       enum cbor_int_width
1087              Possible widths of CBOR_TYPE_UINT items.
1088
1089              Values:
1090
1091              enumerator CBOR_INT_8
1092
1093              enumerator CBOR_INT_16
1094
1095              enumerator CBOR_INT_32
1096
1097              enumerator CBOR_INT_64
1098
1099   Type 0 - positive integers
1100               ┌────────────────────────┬────────────────────────────┐
1101               │Corresponding cbor_typeCBOR_TYPE_UINT             
1102               ├────────────────────────┼────────────────────────────┤
1103               │Number of allocations   │ One per lifetime           │
1104               ├────────────────────────┼────────────────────────────┤
1105               │Storage requirements    │ sizeof(cbor_item_t)      + 
1106               │                        │ sizeof(uint*_t)            
1107               └────────────────────────┴────────────────────────────┘
1108
1109       Note: once a positive integer has been created,  its  width  cannot  be
1110       changed.
1111
1112   Type 1 - negative integers
1113               ┌────────────────────────┬────────────────────────────┐
1114               │Corresponding cbor_typeCBOR_TYPE_NEGINT           
1115               ├────────────────────────┼────────────────────────────┤
1116               │Number of allocations   │ One per lifetime           │
1117               ├────────────────────────┼────────────────────────────┤
1118               │Storage requirements    │ sizeof(cbor_item_t)      + 
1119               │                        │ sizeof(uint*_t)            
1120               └────────────────────────┴────────────────────────────┘
1121
1122       Note: once a positive integer has been created,  its  width  cannot  be
1123       changed.
1124
1125   Type 0 & 1
1126       Due  to their largely similar semantics, the following functions can be
1127       used for both Type 0 and Type 1 items. One  can  convert  between  them
1128       freely using the conversion functions.
1129
1130       Actual Type of the integer can be checked using item types API.
1131
1132       An  integer  item is created with one of the four widths. Because inte‐
1133       gers' storage is bundled together with the handle, the width cannot  be
1134       changed over its lifetime.
1135
1136       WARNING:
1137          Due  to  the  fact that CBOR negative integers represent integers in
1138          the range [-1, -2^N], cbor_set_uint API  is  somewhat  counter-intu‐
1139          itive  as  the  resulting  logical value is 1 less. This behavior is
1140          necessary in order to permit  uniform  manipulation  with  the  full
1141          range of permitted values. For example, the following snippet
1142
1143              cbor_item_t * item = cbor_new_int8();
1144              cbor_mark_negint(item);
1145              cbor_set_uint8(0);
1146
1147          will  produce  an  item with the logical value of -1. There is, how‐
1148          ever, an upside to this as well: There is only one representation of
1149          zero.
1150
1151   Building new items
1152       cbor_item_t *cbor_build_uint8(uint8_t value)
1153              Constructs a new positive integer.
1154
1155              param value
1156                     the value to use
1157
1158              return new positive integer or NULL on memory allocation failure
1159
1160       cbor_item_t *cbor_build_uint16(uint16_t value)
1161              Constructs a new positive integer.
1162
1163              param value
1164                     the value to use
1165
1166              return new positive integer or NULL on memory allocation failure
1167
1168       cbor_item_t *cbor_build_uint32(uint32_t value)
1169              Constructs a new positive integer.
1170
1171              param value
1172                     the value to use
1173
1174              return new positive integer or NULL on memory allocation failure
1175
1176       cbor_item_t *cbor_build_uint64(uint64_t value)
1177              Constructs a new positive integer.
1178
1179              param value
1180                     the value to use
1181
1182              return new positive integer or NULL on memory allocation failure
1183
1184   Retrieving values
1185       uint8_t cbor_get_uint8(const cbor_item_t *item)
1186              Extracts the integer value.
1187
1188              param item[borrow]
1189                     positive or negative integer
1190
1191              return the value
1192
1193       uint16_t cbor_get_uint16(const cbor_item_t *item)
1194              Extracts the integer value.
1195
1196              param item[borrow]
1197                     positive or negative integer
1198
1199              return the value
1200
1201       uint32_t cbor_get_uint32(const cbor_item_t *item)
1202              Extracts the integer value.
1203
1204              param item[borrow]
1205                     positive or negative integer
1206
1207              return the value
1208
1209       uint64_t cbor_get_uint64(const cbor_item_t *item)
1210              Extracts the integer value.
1211
1212              param item[borrow]
1213                     positive or negative integer
1214
1215              return the value
1216
1217   Setting values
1218       void cbor_set_uint8(cbor_item_t *item, uint8_t value)
1219              Assigns the integer value.
1220
1221              param item[borrow]
1222                     positive or negative integer item
1223
1224              param value
1225                     the  value  to  assign. For negative integer, the logical
1226                     value is -value - 1
1227
1228       void cbor_set_uint16(cbor_item_t *item, uint16_t value)
1229              Assigns the integer value.
1230
1231              param item[borrow]
1232                     positive or negative integer item
1233
1234              param value
1235                     the value to assign. For negative  integer,  the  logical
1236                     value is -value - 1
1237
1238       void cbor_set_uint32(cbor_item_t *item, uint32_t value)
1239              Assigns the integer value.
1240
1241              param item[borrow]
1242                     positive or negative integer item
1243
1244              param value
1245                     the  value  to  assign. For negative integer, the logical
1246                     value is -value - 1
1247
1248       void cbor_set_uint64(cbor_item_t *item, uint64_t value)
1249              Assigns the integer value.
1250
1251              param item[borrow]
1252                     positive or negative integer item
1253
1254              param value
1255                     the value to assign. For negative  integer,  the  logical
1256                     value is -value - 1
1257
1258   Dealing with width
1259       cbor_int_width cbor_int_get_width(const cbor_item_t *item)
1260              Queries the integer width.
1261
1262              param item[borrow]
1263                     positive or negative integer item
1264
1265              return the width
1266
1267   Dealing with signedness
1268       void cbor_mark_uint(cbor_item_t *item)
1269              Marks the integer item as a positive integer.
1270
1271              The data value is not changed
1272
1273              param item[borrow]
1274                     positive or negative integer item
1275
1276       void cbor_mark_negint(cbor_item_t *item)
1277              Marks the integer item as a negative integer.
1278
1279              The data value is not changed
1280
1281              param item[borrow]
1282                     positive or negative integer item
1283
1284   Creating new items
1285       cbor_item_t *cbor_new_int8()
1286              Allocates new integer with 1B width.
1287
1288              The width cannot be changed once allocated
1289
1290              return new  positive  integer or NULL on memory allocation fail‐
1291                     ure. The value is not initialized
1292
1293       cbor_item_t *cbor_new_int16()
1294              Allocates new integer with 2B width.
1295
1296              The width cannot be changed once allocated
1297
1298              return new positive integer or NULL on memory  allocation  fail‐
1299                     ure. The value is not initialized
1300
1301       cbor_item_t *cbor_new_int32()
1302              Allocates new integer with 4B width.
1303
1304              The width cannot be changed once allocated
1305
1306              return new  positive  integer or NULL on memory allocation fail‐
1307                     ure. The value is not initialized
1308
1309       cbor_item_t *cbor_new_int64()
1310              Allocates new integer with 8B width.
1311
1312              The width cannot be changed once allocated
1313
1314              return new positive integer or NULL on memory  allocation  fail‐
1315                     ure. The value is not initialized
1316
1317   Type 2 – Byte strings
1318       CBOR  byte  strings  are just (ordered) series of bytes without further
1319       interpretation (unless there is a tag). Byte string's length may or may
1320       not  be  known  during encoding. These two kinds of byte strings can be
1321       distinguished       using       cbor_bytestring_is_definite()       and
1322       cbor_bytestring_is_indefinite() respectively.
1323
1324       In case a byte string is indefinite, it is encoded as a series of defi‐
1325       nite byte strings. These are called "chunks". For example, the  encoded
1326       item
1327
1328          0xf5            Start indefinite byte string
1329              0x41        Byte string (1B long)
1330                  0x00
1331              0x41        Byte string (1B long)
1332                  0xff
1333              0xff        "Break" control token
1334
1335       represents two bytes, 0x00 and 0xff. This on one hand enables streaming
1336       messages even before they are fully generated, but on the other hand it
1337       adds more complexity to the client code.
1338
1339              ┌───────────────────────────┬────────────────────────────┐
1340              │Corresponding cbor_typeCBOR_TYPE_BYTESTRING       
1341              ├───────────────────────────┼────────────────────────────┤
1342              │Number    of   allocations │ One plus any manipulations │
1343              │(definite)                 │ with the data              │
1344              ├───────────────────────────┼────────────────────────────┤
1345              │Number of allocations (in‐ │ One  plus  logarithmically │
1346              │definite)                  │ many  reallocations  rela‐ │
1347              │                           │ tive  to chunk count       │
1348              ├───────────────────────────┼────────────────────────────┤
1349              │Storage requirements (def‐ │ sizeof(cbor_item_t)      + 
1350              │inite)                     │ length(handle)             
1351              ├───────────────────────────┼────────────────────────────┤
1352              │Storage requirements  (in‐ │ sizeof(cbor_item_t) * (1 + 
1353              │definite)                  │ chunk_count) + chunks      
1354              └───────────────────────────┴────────────────────────────┘
1355
1356   Streaming indefinite byte strings
1357       Please refer to Streaming & indefinite items.
1358
1359   Getting metadata
1360       size_t cbor_bytestring_length(const cbor_item_t *item)
1361              Returns the length of the binary data.
1362
1363              For definite byte strings only
1364
1365              param item[borrow]
1366                     a definite bytestring
1367
1368              return length of the binary data. Zero if no chunk has been  at‐
1369                     tached yet
1370
1371       bool cbor_bytestring_is_definite(const cbor_item_t *item)
1372              Is the byte string definite?
1373
1374              param item[borrow]
1375                     a byte string
1376
1377              return Is the byte string definite?
1378
1379       bool cbor_bytestring_is_indefinite(const cbor_item_t *item)
1380              Is the byte string indefinite?
1381
1382              param item[borrow]
1383                     a byte string
1384
1385              return Is the byte string indefinite?
1386
1387       size_t cbor_bytestring_chunk_count(const cbor_item_t *item)
1388              Get the number of chunks this string consist of.
1389
1390              param item[borrow]
1391                     A indefinite bytestring
1392
1393              return The chunk count. 0 for freshly created items.
1394
1395   Reading data
1396       cbor_mutable_data cbor_bytestring_handle(const cbor_item_t *item)
1397              Get the handle to the binary data.
1398
1399              Definite  items  only.  Modifying  the  data is allowed. In that
1400              case, the caller takes responsibility for the  effect  on  items
1401              this item might be a part of
1402
1403              param item[borrow]
1404                     A definite byte string
1405
1406              return The address of the binary data. NULL if no data have been
1407                     assigned yet.
1408
1409       cbor_item_t **cbor_bytestring_chunks_handle(const cbor_item_t *item)
1410              Get the handle to the array of chunks.
1411
1412              Manipulations with the memory block (e.g. sorting  it)  are  al‐
1413              lowed,  but  the  validity  and the number of chunks must be re‐
1414              tained.
1415
1416              param item[borrow]
1417                     A indefinite byte string
1418
1419              return array of cbor_bytestring_chunk_count definite bytestrings
1420
1421   Creating new items
1422       cbor_item_t *cbor_new_definite_bytestring()
1423              Creates a new definite byte string.
1424
1425              The handle is initialized to NULL and length to 0
1426
1427              return new definite bytestring. NULL on malloc failure.
1428
1429       cbor_item_t *cbor_new_indefinite_bytestring()
1430              Creates a new indefinite byte string.
1431
1432              The chunks array is initialized to NULL and chunkcount to 0
1433
1434              return new indefinite bytestring. NULL on malloc failure.
1435
1436   Building items
1437       cbor_item_t *cbor_build_bytestring(cbor_data handle, size_t length)
1438              Creates a new byte string and initializes it.
1439
1440              The handle will be copied to a newly allocated block
1441
1442              param handle
1443                     Block of binary data
1444
1445              param length
1446                     Length of data
1447
1448              return A new byte string with content  handle.  NULL  on  malloc
1449                     failure.
1450
1451   Manipulating existing items
1452       void  cbor_bytestring_set_handle(cbor_item_t  *item,  cbor_mutable_data
1453       data, size_t length)
1454              Set the handle to the binary data.
1455
1456              param item[borrow]
1457                     A definite byte string
1458
1459              param data
1460                     The memory block. The caller gives up  the  ownership  of
1461                     the  block.  libcbor  will deallocate it when appropriate
1462                     using its free function
1463
1464              param length
1465                     Length of the data block
1466
1467       bool cbor_bytestring_add_chunk(cbor_item_t *item, cbor_item_t *chunk)
1468              Appends a chunk to the bytestring.
1469
1470              Indefinite byte strings only.
1471
1472              May realloc the chunk storage.
1473
1474              param item[borrow]
1475                     An indefinite byte string
1476
1477              param item[incref]
1478                     A definite byte string
1479
1480              return true on success, false on realloc failure. In that  case,
1481                     the  refcount  of  chunk is not increased and the item is
1482                     left intact.
1483
1484   Type 3 – UTF-8 strings
1485       CBOR strings work in much the same ways as Type 2  Byte strings.
1486
1487              ┌───────────────────────────┬────────────────────────────┐
1488              │Corresponding cbor_typeCBOR_TYPE_STRING           
1489              ├───────────────────────────┼────────────────────────────┤
1490              │Number   of    allocations │ One plus any manipulations │
1491              │(definite)                 │ with the data              │
1492              ├───────────────────────────┼────────────────────────────┤
1493              │Number of allocations (in‐ │ One  plus  logarithmically │
1494              │definite)                  │ many  reallocations  rela‐ │
1495              │                           │ tive  to chunk count       │
1496              ├───────────────────────────┼────────────────────────────┤
1497              │Storage requirements (def‐ │ sizeof(cbor_item_t)      + 
1498              │inite)                     │ length(handle)             
1499              ├───────────────────────────┼────────────────────────────┤
1500              │Storage  requirements (in‐ │ sizeof(cbor_item_t) * (1 + 
1501              │definite)                  │ chunk_count) + chunks      
1502              └───────────────────────────┴────────────────────────────┘
1503
1504   Streaming indefinite strings
1505       Please refer to Streaming & indefinite items.
1506
1507   UTF-8 encoding validation
1508       libcbor  considers  UTF-8  encoding  validity  to  be  a  part  of  the
1509       well-formedness notion of CBOR and therefore invalid UTF-8 strings will
1510       be rejected by the parser. Strings created by the user are not checked.
1511
1512   Getting metadata
1513       size_t cbor_string_length(const cbor_item_t *item)
1514              Returns the length of the underlying string.
1515
1516              For definite strings only
1517
1518              param item[borrow]
1519                     a definite string
1520
1521              return length  of the string. Zero if no chunk has been attached
1522                     yet
1523
1524       bool cbor_string_is_definite(const cbor_item_t *item)
1525              Is the string definite?
1526
1527              param item[borrow]
1528                     a string
1529
1530              return Is the string definite?
1531
1532       bool cbor_string_is_indefinite(const cbor_item_t *item)
1533              Is the string indefinite?
1534
1535              param item[borrow]
1536                     a string
1537
1538              return Is the string indefinite?
1539
1540       size_t cbor_string_chunk_count(const cbor_item_t *item)
1541              Get the number of chunks this string consist of.
1542
1543              param item[borrow]
1544                     A indefinite string
1545
1546              return The chunk count. 0 for freshly created items.
1547
1548   Reading data
1549       cbor_mutable_data cbor_string_handle(const cbor_item_t *item)
1550              Get the handle to the underlying string.
1551
1552              Definite items only. Modifying the  data  is  allowed.  In  that
1553              case,  the  caller  takes responsibility for the effect on items
1554              this item might be a part of
1555
1556              param item[borrow]
1557                     A definite string
1558
1559              return The address of the underlying string.  NULL  if  no  data
1560                     have been assigned yet.
1561
1562       cbor_item_t **cbor_string_chunks_handle(const cbor_item_t *item)
1563              Get the handle to the array of chunks.
1564
1565              Manipulations  with  the  memory block (e.g. sorting it) are al‐
1566              lowed, but the validity and the number of  chunks  must  be  re‐
1567              tained.
1568
1569              param item[borrow]
1570                     A indefinite string
1571
1572              return array of cbor_string_chunk_count definite strings
1573
1574   Creating new items
1575       cbor_item_t *cbor_new_definite_string()
1576              Creates a new definite string.
1577
1578              The handle is initialized to NULL and length to 0
1579
1580              return new definite string. NULL on malloc failure.
1581
1582       cbor_item_t *cbor_new_indefinite_string()
1583              Creates a new indefinite string.
1584
1585              The chunks array is initialized to NULL and chunkcount to 0
1586
1587              return new indefinite string. NULL on malloc failure.
1588
1589   Building items
1590       cbor_item_t *cbor_build_string(const char *val)
1591              Creates a new string and initializes it.
1592
1593              The val will be copied to a newly allocated block
1594
1595              param val
1596                     A null-terminated UTF-8 string
1597
1598              return A new string with content handle. NULL on malloc failure.
1599
1600   Manipulating existing items
1601       void  cbor_string_set_handle(cbor_item_t *item, cbor_mutable_data data,
1602       size_t length)
1603              Set the handle to the underlying string.
1604
1605              mistake. Lifetime of the string will expire when it goes out  of
1606              scope and the CBOR item will be left inconsistent.
1607
1608
1609              WARNING:
1610                 Using a pointer to a stack allocated constant is a common
1611
1612              param item[borrow]
1613                     A definite string
1614
1615              param data
1616                     The  memory  block.  The caller gives up the ownership of
1617                     the block. libcbor will deallocate  it  when  appropriate
1618                     using its free function
1619
1620              param length
1621                     Length of the data block
1622
1623       bool cbor_string_add_chunk(cbor_item_t *item, cbor_item_t *chunk)
1624              Appends a chunk to the string.
1625
1626              Indefinite strings only.
1627
1628              May realloc the chunk storage.
1629
1630              param item[borrow]
1631                     An indefinite string
1632
1633              param item[incref]
1634                     A definite string
1635
1636              return true  on success. false on realloc failure. In that case,
1637                     the refcount of chunk is not increased and  the  item  is
1638                     left intact.
1639
1640   Type 4 – Arrays
1641       CBOR  arrays, just like byte strings and strings, can be encoded either
1642       as definite, or as indefinite.
1643
1644              ┌───────────────────────────┬────────────────────────────┐
1645              │Corresponding cbor_typeCBOR_TYPE_ARRAY            
1646              ├───────────────────────────┼────────────────────────────┤
1647              │Number   of    allocations │ Two plus any manipulations │
1648              │(definite)                 │ with the data              │
1649              ├───────────────────────────┼────────────────────────────┤
1650              │Number of allocations (in‐ │ Two  plus  logarithmically │
1651              │definite)                  │ many  reallocations  rela‐ │
1652              │                           │ tive to additions          │
1653              ├───────────────────────────┼────────────────────────────┤
1654              │Storage requirements (def‐ │ (sizeof(cbor_item_t) +  1) 
1655              │inite)                     │ * size                     
1656              ├───────────────────────────┼────────────────────────────┤
1657              │Storage  requirements (in‐ │ <=  sizeof(cbor_item_t)  + 
1658              │definite)                  │ sizeof(cbor_item_t) * size 
1659              │                           │ * BUFFER_GROWTH            
1660              └───────────────────────────┴────────────────────────────┘
1661
1662   Examples
1663          0x9f        Start indefinite array
1664              0x01        Unsigned integer 1
1665              0xff        "Break" control token
1666
1667          0x9f        Start array, 1B length follows
1668          0x20        Unsigned integer 32
1669              ...        32 items follow
1670
1671   Streaming indefinite arrays
1672       Please refer to Streaming & indefinite items.
1673
1674   Getting metadata
1675       size_t cbor_array_size(const cbor_item_t *item)
1676              Get the number of members.
1677
1678              param item[borrow]
1679                     An array
1680
1681              return The number of members
1682
1683       size_t cbor_array_allocated(const cbor_item_t *item)
1684              Get the size of the allocated storage.
1685
1686              param item[borrow]
1687                     An array
1688
1689              return The size of the allocated storage (number of items)
1690
1691       bool cbor_array_is_definite(const cbor_item_t *item)
1692              Is the array definite?
1693
1694              param item[borrow]
1695                     An array
1696
1697              return Is the array definite?
1698
1699       bool cbor_array_is_indefinite(const cbor_item_t *item)
1700              Is the array indefinite?
1701
1702              param item[borrow]
1703                     An array
1704
1705              return Is the array indefinite?
1706
1707   Reading data
1708       cbor_item_t **cbor_array_handle(const cbor_item_t *item)
1709              Get the array contents.
1710
1711              The items may be reordered and modified as  long  as  references
1712              remain consistent.
1713
1714              param item[borrow]
1715                     An array
1716
1717              return cbor_array_size items
1718
1719       cbor_item_t *cbor_array_get(const cbor_item_t *item, size_t index)
1720              Get item by index.
1721
1722              param item[borrow]
1723                     An array
1724
1725              param index
1726                     The index
1727
1728              return incref The item, or NULL in case of boundary violation
1729
1730   Creating new items
1731       cbor_item_t *cbor_new_definite_array(size_t size)
1732              Create new definite array.
1733
1734              param size
1735                     Number of slots to preallocate
1736
1737              return new array or NULL upon malloc failure
1738
1739       cbor_item_t *cbor_new_indefinite_array()
1740              Create new indefinite array.
1741
1742              return new array or NULL upon malloc failure
1743
1744   Modifying items
1745       bool cbor_array_push(cbor_item_t *array, cbor_item_t *pushee)
1746              Append to the end.
1747
1748              For  indefinite  items, storage may be realloacted. For definite
1749              items, only the preallocated capacity is available.
1750
1751              param array[borrow]
1752                     An array
1753
1754              param pushee[incref]
1755                     The item to push
1756
1757              return true on success, false on failure
1758
1759       bool cbor_array_replace(cbor_item_t *item,  size_t  index,  cbor_item_t
1760       *value)
1761              Replace item at an index.
1762
1763              The item being replace will be cbor_decref 'ed.
1764
1765              param item[borrow]
1766                     An array
1767
1768              param value[incref]
1769                     The item to assign
1770
1771              param index
1772                     The index, first item is 0.
1773
1774              return true on success, false on allocation failure.
1775
1776       bool   cbor_array_set(cbor_item_t   *item,  size_t  index,  cbor_item_t
1777       *value)
1778              Set item by index.
1779
1780              Creating arrays with holes is not possible
1781
1782              param item[borrow]
1783                     An array
1784
1785              param value[incref]
1786                     The item to assign
1787
1788              param index
1789                     The index, first item is 0.
1790
1791              return true on success, false on allocation failure.
1792
1793   Type 5 – Maps
1794       CBOR maps are the plain old associate hash maps  known  from  JSON  and
1795       many  other  formats  and  languages, with one exception: any CBOR data
1796       item can be a key, not just strings. This is somewhat unusual and  you,
1797       as an application developer, should keep that in mind.
1798
1799       Maps can be either definite or indefinite, in much the same way as Type
1800       4  Arrays.
1801
1802              ┌───────────────────────────┬────────────────────────────┐
1803              │Corresponding cbor_typeCBOR_TYPE_MAP              
1804              ├───────────────────────────┼────────────────────────────┤
1805              │Number   of    allocations │ Two plus any manipulations │
1806              │(definite)                 │ with the data              │
1807              ├───────────────────────────┼────────────────────────────┤
1808              │Number of allocations (in‐ │ Two  plus  logarithmically │
1809              │definite)                  │ many  reallocations  rela‐ │
1810              │                           │ tive to additions          │
1811              ├───────────────────────────┼────────────────────────────┤
1812              │Storage requirements (def‐ │ sizeof(cbor_pair) * size + 
1813              │inite)                     │ sizeof(cbor_item_t)        
1814              ├───────────────────────────┼────────────────────────────┤
1815              │Storage  requirements (in‐ │ <=  sizeof(cbor_item_t)  + 
1816              │definite)                  │ sizeof(cbor_pair) * size * 
1817              │                           │ BUFFER_GROWTH              
1818              └───────────────────────────┴────────────────────────────┘
1819
1820   Streaming maps
1821       Please refer to Streaming & indefinite items.
1822
1823   Getting metadata
1824       size_t cbor_map_size(const cbor_item_t *item)
1825              Get the number of pairs.
1826
1827              param item[borrow]
1828                     A map
1829
1830              return The number of pairs
1831
1832       size_t cbor_map_allocated(const cbor_item_t *item)
1833              Get the size of the allocated storage.
1834
1835              param item[borrow]
1836                     A map
1837
1838              return Allocated storage size (as the number of cbor_pair items)
1839
1840       bool cbor_map_is_definite(const cbor_item_t *item)
1841              Is this map definite?
1842
1843              param item[borrow]
1844                     A map
1845
1846              return Is this map definite?
1847
1848       bool cbor_map_is_indefinite(const cbor_item_t *item)
1849              Is this map indefinite?
1850
1851              param item[borrow]
1852                     A map
1853
1854              return Is this map indefinite?
1855
1856   Reading data
1857       struct cbor_pair *cbor_map_handle(const cbor_item_t *item)
1858              Get the pairs storage.
1859
1860              param item[borrow]
1861                     A map
1862
1863              return Array of cbor_map_size pairs. Manipulation is possible as
1864                     long as references remain valid.
1865
1866   Creating new items
1867       cbor_item_t *cbor_new_definite_map(size_t size)
1868              Create a new definite map.
1869
1870              param size
1871                     The number of slots to preallocate
1872
1873              return new definite map. NULL on malloc failure.
1874
1875       cbor_item_t *cbor_new_indefinite_map()
1876              Create a new indefinite map.
1877
1878              param size
1879                     The number of slots to preallocate
1880
1881              return new definite map. NULL on malloc failure.
1882
1883   Modifying items
1884       bool cbor_map_add(cbor_item_t *item, struct cbor_pair pair)
1885              Add a pair to the map.
1886
1887              For  definite  maps, items can only be added to the preallocated
1888              space. For indefinite maps, the  storage  will  be  expanded  as
1889              needed
1890
1891              param item[borrow]
1892                     A map
1893
1894              param pair[incref]
1895                     The key-value pair to add (incref is member-wise)
1896
1897              return true  on  success, false if either reallocation failed or
1898                     the preallcoated storage is full
1899
1900   Type 6 – Semantic tags
1901       Tag are additional metadata that can be used to  extend  or  specialize
1902       the meaning or interpretation of the other data items.
1903
1904       For  example,  one might tag an array of numbers to communicate that it
1905       should be interpreted as a vector.
1906
1907       Please consult the official IANA repository of CBOR tags before invent‐
1908       ing new ones.
1909
1910               ┌────────────────────────┬────────────────────────────┐
1911               │Corresponding cbor_typeCBOR_TYPE_TAG              
1912               ├────────────────────────┼────────────────────────────┤
1913               │Number of allocations   │ One plus any manipulations │
1914               │                        │ with  the  data  realloca‐ │
1915               │                        │ tions  relative   to chunk │
1916               │                        │ count                      │
1917               ├────────────────────────┼────────────────────────────┤
1918               │Storage requirements    │ sizeof(cbor_item_t) +  the 
1919               │                        │ tagged item                
1920               └────────────────────────┴────────────────────────────┘
1921
1922       cbor_item_t *cbor_new_tag(uint64_t value)
1923              Create a new tag.
1924
1925              param value
1926                     The tag value. Please consult the tag repository
1927
1928              return new tag. Item reference is NULL. Returns NULL upon memory
1929                     allocation failure
1930
1931       cbor_item_t *cbor_tag_item(const cbor_item_t *item)
1932              Get the tagged item.
1933
1934              param item[borrow]
1935                     A tag
1936
1937              return incref the tagged item
1938
1939       uint64_t cbor_tag_value(const cbor_item_t *item)
1940              Get tag value.
1941
1942              param item[borrow]
1943                     A tag
1944
1945              return The tag value. Please consult the tag repository
1946
1947       void cbor_tag_set_item(cbor_item_t *item, cbor_item_t *tagged_item)
1948              Set the tagged item.
1949
1950              param item[borrow]
1951                     A tag
1952
1953              param tagged_item[incref]
1954                     The item to tag
1955
1956   Type 7 – Floats & control tokens
1957       This type combines two completely unrelated types of items --  floating
1958       point numbers and special values such as true, false, null, etc. We re‐
1959       fer to these special values as 'control values' or  'ctrls'  for  short
1960       throughout the code.
1961
1962       Just  like  integers,  they have different possible width (resulting in
1963       different value ranges and precisions).
1964
1965       enum cbor_float_width
1966              Possible widths of CBOR_TYPE_FLOAT_CTRL items.
1967
1968              Values:
1969
1970              enumerator CBOR_FLOAT_0
1971                     Internal use - ctrl and special values.
1972
1973              enumerator CBOR_FLOAT_16
1974                     Half float.
1975
1976              enumerator CBOR_FLOAT_32
1977                     Single float.
1978
1979              enumerator CBOR_FLOAT_64
1980                     Double.
1981
1982               ┌────────────────────────┬────────────────────────────┐
1983               │Corresponding cbor_typeCBOR_TYPE_FLOAT_CTRL       
1984               ├────────────────────────┼────────────────────────────┤
1985               │Number of allocations   │ One per lifetime           │
1986               ├────────────────────────┼────────────────────────────┤
1987               │Storage requirements    │ sizeof(cbor_item_t)      + 
1988               │                        │ 1/4/8                      
1989               └────────────────────────┴────────────────────────────┘
1990
1991   Getting metadata
1992       bool cbor_float_ctrl_is_ctrl(const cbor_item_t *item)
1993              Is this a ctrl value?
1994
1995              param item[borrow]
1996                     A float or ctrl item
1997
1998              return Is this a ctrl value?
1999
2000       cbor_float_width cbor_float_get_width(const cbor_item_t *item)
2001              Get the float width.
2002
2003              param item[borrow]
2004                     A float or ctrl item
2005
2006              return The width.
2007
2008   Reading data
2009       float cbor_float_get_float2(const cbor_item_t *item)
2010              Get a half precision float.
2011
2012              The item must have the corresponding width
2013
2014              param [borrow]
2015                     A half precision float
2016
2017              return half precision value
2018
2019       float cbor_float_get_float4(const cbor_item_t *item)
2020              Get a single precision float.
2021
2022              The item must have the corresponding width
2023
2024              param [borrow]
2025                     A signle precision float
2026
2027              return single precision value
2028
2029       double cbor_float_get_float8(const cbor_item_t *item)
2030              Get a double precision float.
2031
2032              The item must have the corresponding width
2033
2034              param [borrow]
2035                     A double precision float
2036
2037              return double precision value
2038
2039       double cbor_float_get_float(const cbor_item_t *item)
2040              Get the float value represented as double.
2041
2042              Can be used regardless of the width.
2043
2044              param [borrow]
2045                     Any float
2046
2047              return double precision value
2048
2049       uint8_t cbor_ctrl_value(const cbor_item_t *item)
2050              Reads the control value.
2051
2052              param item[borrow]
2053                     A ctrl item
2054
2055              return the simple value
2056
2057       bool cbor_get_bool(const cbor_item_t *item)
2058              Get value from a boolean ctrl item.
2059
2060              param item[borrow]
2061                     A ctrl item
2062
2063              return boolean value
2064
2065   Creating new items
2066       cbor_item_t *cbor_new_ctrl()
2067              Constructs a new ctrl item.
2068
2069              The width cannot be changed once the item is created
2070
2071              return new 1B ctrl or NULL upon memory allocation failure
2072
2073       cbor_item_t *cbor_new_float2()
2074              Constructs a new float item.
2075
2076              The width cannot be changed once the item is created
2077
2078              return new 2B float or NULL upon memory allocation failure
2079
2080       cbor_item_t *cbor_new_float4()
2081              Constructs a new float item.
2082
2083              The width cannot be changed once the item is created
2084
2085              return new 4B float or NULL upon memory allocation failure
2086
2087       cbor_item_t *cbor_new_float8()
2088              Constructs a new float item.
2089
2090              The width cannot be changed once the item is created
2091
2092              return new 8B float or NULL upon memory allocation failure
2093
2094       cbor_item_t *cbor_new_null()
2095              Constructs new null ctrl item.
2096
2097              return new null ctrl item or NULL upon memory allocation failure
2098
2099       cbor_item_t *cbor_new_undef()
2100              Constructs new undef ctrl item.
2101
2102              return new  undef ctrl item or NULL upon memory allocation fail‐
2103                     ure
2104
2105   Building items
2106       cbor_item_t *cbor_build_bool(bool value)
2107              Constructs new boolean ctrl item.
2108
2109              param value
2110                     The value to use
2111
2112              return new boolen ctrl item or NULL upon memory allocation fail‐
2113                     ure
2114
2115       cbor_item_t *cbor_build_ctrl(uint8_t value)
2116              Constructs a ctrl item.
2117
2118              param value
2119                     the value to use
2120
2121              return new ctrl item or NULL upon memory allocation failure
2122
2123       cbor_item_t *cbor_build_float2(float value)
2124              Constructs a new float.
2125
2126              param value
2127                     the value to use
2128
2129              return new float
2130
2131       cbor_item_t *cbor_build_float4(float value)
2132              Constructs a new float.
2133
2134              param value
2135                     the value to use
2136
2137              return new float or NULL upon memory allocation failure
2138
2139       cbor_item_t *cbor_build_float8(double value)
2140              Constructs a new float.
2141
2142              param value
2143                     the value to use
2144
2145              return new float or NULL upon memory allocation failure
2146
2147   Manipulating existing items
2148       void cbor_set_ctrl(cbor_item_t *item, uint8_t value)
2149              Assign a control value.
2150
2151              invalid  value using this mechanism. Please consult the standard
2152              before use.
2153
2154
2155              WARNING:
2156                 It is possible to produce an invalid CBOR value by  assigning
2157                 a
2158
2159              param item[borrow]
2160                     A ctrl item
2161
2162              param value
2163                     The  simple  value to assign. Please consult the standard
2164                     for allowed values
2165
2166       void cbor_set_bool(cbor_item_t *item, bool value)
2167              Assign a boolean value to a boolean ctrl item.
2168
2169              param item[borrow]
2170                     A ctrl item
2171
2172              param value
2173                     The simple value to assign.
2174
2175       void cbor_set_float2(cbor_item_t *item, float value)
2176              Assigns a float value.
2177
2178              param item[borrow]
2179                     A half precision float
2180
2181              param value
2182                     The value to assign
2183
2184       void cbor_set_float4(cbor_item_t *item, float value)
2185              Assigns a float value.
2186
2187              param item[borrow]
2188                     A single precision float
2189
2190              param value
2191                     The value to assign
2192
2193       void cbor_set_float8(cbor_item_t *item, double value)
2194              Assigns a float value.
2195
2196              param item[borrow]
2197                     A double precision float
2198
2199              param value
2200                     The value to assign
2201
2202   Half floats
2203       CBOR supports two bytes wide ("half-precision") floats  which  are  not
2204       supported  by  the  C  language.  libcbor  represents  them using float
2205       <https://en.cppreference.com/w/c/language/type> values  throughout  the
2206       API, which has important implications when manipulating these values.
2207
2208       In  particular,  if  a  user  uses  some of the manipulation APIs (e.g.
2209       cbor_set_float2(), cbor_new_float2()) to introduce a value that doesn't
2210       have  an  exect  half-float  representation, the encoding semantics are
2211       given by cbor_encode_half() as follows:
2212
2213       size_t cbor_encode_half(float value, unsigned char *buffer, size_t buf‐
2214       fer_size)
2215              Encodes a half-precision float.
2216
2217              Since  there  is  no native representation or semantics for half
2218              floats in the language, we use single-precision floats, as every
2219              value  that  can  be  expressed  as a half-float can also be ex‐
2220              pressed as a float.
2221
2222              This however means that not all floats passed to  this  function
2223              can be unambiguously encoded. The behavior is as follows:.INDENT
2224              7.0
2225
2226       • Infinity, NaN are preserved
2227
2228       • Zero is preserved
2229
2230       • Denormalized numbers keep their sign bit and 10 most significant  bit
2231         of the significand
2232
2233       • All other numbers.INDENT 2.0
2234
2235       • If the logical value of the exponent is < -24, the output is zero
2236
2237       • If the logical value of the exponent is between -23 and -14, the out‐
2238         put is cut off to represent the 'magnitude' of the input, by which we
2239         mean (-1)^{signbit} x 1.0e{exponent}. The value in the significand is
2240         lost.
2241
2242       • In all other cases, the sign bit, the exponent, and 10 most  signifi‐
2243         cant bits of the significand are kept
2244
2245
2246
2247              param value
2248
2249
2250              param buffer
2251                     Target buffer
2252
2253              param buffer_size
2254                     Available space in the buffer
2255
2256              return number of bytes written
2257
2258       [1]  http://softwareengineering.vazexqi.com/files/pattern.html
2259
2260   Streaming & indefinite items
2261       CBOR  strings, byte strings, arrays, and maps can be encoded as indefi‐
2262       nite, meaning their length or size is not specified. Instead, they  are
2263       divided  into  chunks (strings, byte strings), or explicitly terminated
2264       (arrays, maps).
2265
2266       This is one of the most important (and due to poor implementations, un‐
2267       derutilized)  features  of CBOR. It enables low-overhead streaming just
2268       about anywhere without dealing with channels or pub/sub  mechanism.  It
2269       is,  however,  important to recognize that CBOR streaming is not a sub‐
2270       stitute for  Websockets [1] and similar technologies.
2271
2272       [1]  RFC 6455
2273
2274   Decoding
2275       Another way to decode data using libcbor is to specify a callbacks that
2276       will be invoked when upon finding certain items in the input. This ser‐
2277       vice is provided by
2278
2279       struct cbor_decoder_result cbor_stream_decode(cbor_data buffer,  size_t
2280       buffer_size, const struct cbor_callbacks *callbacks, void *context)
2281              Stateless decoder.
2282
2283              Will  try  parsing  the  buffer  and will invoke the appropriate
2284              callback on success. Decodes one item at a time. No memory allo‐
2285              cations occur.
2286
2287              param buffer
2288                     Input buffer
2289
2290              param buffer_size
2291                     Length of the buffer
2292
2293              param callbacks
2294                     The callback bundle
2295
2296              param context
2297                     An arbitrary pointer to allow for maintaining context.
2298
2299       To  get  started, you might want to have a look at the simple streaming
2300       example:
2301
2302          #include "cbor.h"
2303          #include <stdio.h>
2304          #include <string.h>
2305
2306          /*
2307           * Illustrates how one might skim through a map (which is assumed to have
2308           * string keys and values only), looking for the value of a specific key
2309           *
2310           * Use the examples/data/map.cbor input to test this.
2311           */
2312
2313          const char * key = "a secret key";
2314          bool key_found = false;
2315
2316          void find_string(void * _ctx, cbor_data buffer, size_t len)
2317          {
2318              if (key_found) {
2319                  printf("Found the value: %*s\n", (int) len, buffer);
2320                  key_found = false;
2321              } else if (len == strlen(key)) {
2322                  key_found = (memcmp(key, buffer, len) == 0);
2323              }
2324          }
2325
2326          int main(int argc, char * argv[])
2327          {
2328              FILE * f = fopen(argv[1], "rb");
2329              fseek(f, 0, SEEK_END);
2330              size_t length = (size_t)ftell(f);
2331              fseek(f, 0, SEEK_SET);
2332              unsigned char * buffer = malloc(length);
2333              fread(buffer, length, 1, f);
2334
2335              struct cbor_callbacks callbacks = cbor_empty_callbacks;
2336              struct cbor_decoder_result decode_result;
2337              size_t bytes_read = 0;
2338              callbacks.string = find_string;
2339              while (bytes_read < length) {
2340                  decode_result = cbor_stream_decode(buffer + bytes_read,
2341                                                     length - bytes_read,
2342                                                     &callbacks, NULL);
2343                  bytes_read += decode_result.read;
2344              }
2345
2346              free(buffer);
2347              fclose(f);
2348          }
2349
2350       The callbacks are defined by
2351
2352       struct cbor_callbacks
2353              Callback bundle &#8212; passed to the decoder.
2354
2355              Public Members
2356
2357              cbor_int8_callback uint8
2358                     Unsigned int.
2359
2360              cbor_int16_callback uint16
2361                     Unsigned int.
2362
2363              cbor_int32_callback uint32
2364                     Unsigned int.
2365
2366              cbor_int64_callback uint64
2367                     Unsigned int.
2368
2369              cbor_int64_callback negint64
2370                     Negative int.
2371
2372              cbor_int32_callback negint32
2373                     Negative int.
2374
2375              cbor_int16_callback negint16
2376                     Negative int.
2377
2378              cbor_int8_callback negint8
2379                     Negative int.
2380
2381              cbor_simple_callback byte_string_start
2382                     Definite byte string.
2383
2384              cbor_string_callback byte_string
2385                     Indefinite byte string start.
2386
2387              cbor_string_callback string
2388                     Definite string.
2389
2390              cbor_simple_callback string_start
2391                     Indefinite string start.
2392
2393              cbor_simple_callback indef_array_start
2394                     Definite array.
2395
2396              cbor_collection_callback array_start
2397                     Indefinite array.
2398
2399              cbor_simple_callback indef_map_start
2400                     Definite map.
2401
2402              cbor_collection_callback map_start
2403                     Indefinite map.
2404
2405              cbor_int64_callback tag
2406                     Tags.
2407
2408              cbor_float_callback float2
2409                     Half float.
2410
2411              cbor_float_callback float4
2412                     Single float.
2413
2414              cbor_double_callback float8
2415                     Double float.
2416
2417              cbor_simple_callback undefined
2418                     Undef.
2419
2420              cbor_simple_callback null
2421                     Null.
2422
2423              cbor_bool_callback boolean
2424                     Bool.
2425
2426              cbor_simple_callback indef_break
2427                     Indefinite item break.
2428
2429       When building custom sets of callbacks, feel free to start from
2430
2431       const struct cbor_callbacks cbor_empty_callbacks
2432              Dummy callback bundle - does nothing.
2433
2434   Related structures
2435       enum cbor_decoder_status
2436              Streaming decoder result - status.
2437
2438              Values:
2439
2440              enumerator CBOR_DECODER_FINISHED
2441                     OK, finished.
2442
2443              enumerator CBOR_DECODER_NEDATA
2444                     Not enough data - mismatch with MTB.
2445
2446              enumerator CBOR_DECODER_EBUFFER
2447                     Buffer manipulation problem.
2448
2449              enumerator CBOR_DECODER_ERROR
2450                     Malformed or reserved MTB/value.
2451
2452       struct cbor_decoder_result
2453              Streaming decoder result.
2454
2455              Public Members
2456
2457              size_t read
2458                     Bytes read.
2459
2460              enum cbor_decoder_status status
2461                     The result.
2462
2463              size_t required
2464                     When status == CBOR_DECODER_NEDATA, the minimum number of
2465                     bytes required to continue parsing.
2466
2467   Callback types definition
2468       typedef void (*cbor_int8_callback)(void*, uint8_t)
2469              Callback prototype.
2470
2471       typedef void (*cbor_int16_callback)(void*, uint16_t)
2472              Callback prototype.
2473
2474       typedef void (*cbor_int32_callback)(void*, uint32_t)
2475              Callback prototype.
2476
2477       typedef void (*cbor_int64_callback)(void*, uint64_t)
2478              Callback prototype.
2479
2480       typedef void (*cbor_simple_callback)(void*)
2481              Callback prototype.
2482
2483       typedef void (*cbor_string_callback)(void*, cbor_data, size_t)
2484              Callback prototype.
2485
2486       typedef void (*cbor_collection_callback)(void*, size_t)
2487              Callback prototype.
2488
2489       typedef void (*cbor_float_callback)(void*, float)
2490              Callback prototype.
2491
2492       typedef void (*cbor_double_callback)(void*, double)
2493              Callback prototype.
2494
2495       typedef void (*cbor_bool_callback)(void*, bool)
2496              Callback prototype.
2497
2498   Encoding
2499       TODO
2500
2501   Tests
2502   Unit tests
2503       There  is  a comprehensive test suite employing CMocka. You can run all
2504       of them using ctest in the build directory. Individual tests are  them‐
2505       selves  runnable.  Please refer to CTest documentation for detailed in‐
2506       formation on how to specify particular subset of tests.
2507
2508   Testing for memory leaks
2509       Every release is tested for memory correctness. You can run these tests
2510       by passing the -T memcheck flag to ctest. [1]
2511
2512       [1]  Project  should be configured with -DCMAKE_BUILD_TYPE=Debug to ob‐
2513            tain meaningful description of location of  the  leak.  You  might
2514            also need --dsymutil=yes on OS X.
2515
2516   Code coverage
2517       Every  release  is inspected using GCOV/LCOV. Platform-independent code
2518       should be fully covered by the test suite. Simply run
2519
2520          make coverage
2521
2522       or alternatively run lcov by hand using
2523
2524          lcov --capture --directory . --output-file coverage.info
2525          genhtml coverage.info --output-directory out
2526
2527   Fuzz testing
2528       Every release is tested using a fuzz test. In this test, a huge  buffer
2529       filled  with  random  data is passed to the decoder. We require that it
2530       either succeeds or fail with a sensible error, without leaking any mem‐
2531       ory.  This is intended to simulate real-world situations where data re‐
2532       ceived from the network are CBOR-decoded before any further processing.
2533
2534   RFC conformance
2535       libcbor is, generally speaking, very  faithful  implementation  of  RFC
2536       7049.  There  are,  however, some limitations imposed by technical con‐
2537       straints.
2538
2539   Bytestring length
2540       There is no explicit limitation of indefinite length byte strings.  [1]
2541       libcbor  will not handle byte strings with more chunks than the maximum
2542       value of size_t. On any sane platform, such string would not fit in the
2543       memory  anyway.  It  is,  however, possible to process arbitrarily long
2544       strings and byte strings using the streaming decoder.
2545
2546       [1]  http://tools.ietf.org/html/rfc7049#section-2.2.2
2547
2548   "Half-precision" IEEE 754 floats
2549       As of C99 and even C11, there is no standard implementation for 2 bytes
2550       floats.   libcbor   packs   them   as   a  float  <https://en.cpprefer
2551       ence.com/w/c/language/type>. When encoding, libcbor selects the  appro‐
2552       priate wire representation based on metadata and the actual value. This
2553       applies both to canonical and normal mode.
2554
2555       For more information on half-float serialization, please refer  to  the
2556       section on Half floats.
2557
2558   Internal mechanics
2559       Internal workings of libcbor are mostly derived from the specification.
2560       The purpose of this document is to describe technical choices made dur‐
2561       ing design & implementation and to explicate the reasoning behind those
2562       choices.
2563
2564   Terminology
2565     ┌────┬─────────────────────┬────────────────────────────────────────────────┐
2566     │MTB │ Major Type Byte     │ http://tools.ietf.org/html/rfc7049#section-2.1
2567     ├────┼─────────────────────┼────────────────────────────────────────────────┤
2568     │DST │ Dynamically   Sized │ Type whose storage requirements cannot be  de‐ │
2569     │    │ Type                │ termined                                       │
2570     │    │                     │                                                │
2571     │    │                     │ during  compilation  (originated  in  the Rust
2572     │    │                     │ community)                                     │
2573     └────┴─────────────────────┴────────────────────────────────────────────────┘
2574
2575   Conventions
2576       API symbols start with cbor_ or CBOR_  prefix,  internal  symbols  have
2577       _cbor_ or _CBOR_ prefix.
2578
2579   Inspiration & related projects
2580       Most  of the API is largely modelled after existing JSON libraries, in‐
2581       cluding
2582
2583Jansson
2584
2585json-c
2586
2587          • Gnome's JsonGlib
2588
2589       and also borrowing from
2590
2591msgpack-c
2592
2593Google Protocol Buffers.
2594
2595   General notes on the API design
2596       The API design has two main driving priciples:
2597
2598          1. Let the client manage the memory as much as possible
2599
2600          2. Behave exactly as specified by the standard
2601
2602       Combining these two principles in practice turns out to be quite diffi‐
2603       cult.  Indefinite-length  strings,  arrays,  and maps require client to
2604       handle every fixed-size chunk explicitly in order to
2605
2606          • ensure the client never runs out of memory due to libcbor
2607
2608          • use realloc() sparsely and predictably [1]
2609
2610                • provide strong guarantees about its usage  (to  prevent  la‐
2611                  tency spikes)
2612
2613                • provide APIs to avoid realloc() altogether
2614
2615          • allow  proper  handling  of  (streamed) data bigger than available
2616            memory
2617
2618          [1]  Reasonable handling of DSTs requires reallocation if the API is
2619               to remain sane.
2620
2621   Coding style
2622       This code loosely follows the Linux kernel coding style. Tabs are tabs,
2623       and they are 4 characters wide.
2624
2625   Memory layout
2626       CBOR is very dynamic in the sense that it contains many  data  elements
2627       of  variable length, sometimes even indefinite length. This section de‐
2628       scribes internal representation of all CBOR data types.
2629
2630       Generally speaking, data items consist of three parts:
2631
2632          • a generic handle,
2633
2634          • the associated metadata,
2635
2636          • and the actual data
2637
2638       type cbor_item_t
2639              Represents the item. Used as an opaque type
2640
2641              cbor_type type
2642                     Type discriminator
2643
2644              size_t refcount
2645                     Reference counter. Used by cbor_decref(), cbor_incref()
2646
2647              union cbor_item_metadata metadata
2648                     Union discriminated by type. Contains type-specific meta‐
2649                     data
2650
2651              unsigned char *data
2652                     Contains  pointer  to  the actual data. Small, fixed size
2653                     items (Types 0 & 1  Positive and negative integers, Type
2654                     6   Semantic tags, Type 7  Floats & control tokens) are
2655                     allocated as a single memory block.
2656
2657                     Consider the following snippet
2658
2659                        cbor_item_t * item = cbor_new_int8();
2660
2661                     then the memory is laid out as follows
2662
2663                        +-----------+---------------+---------------+-----------------------------------++-----------+
2664                        |           |               |               |                                   ||           |
2665                        |   type    |   refcount    |   metadata    |              data                 ||  uint8_t  |
2666                        |           |               |               |   (= item + sizeof(cbor_item_t))  ||           |
2667                        +-----------+---------------+---------------+-----------------------------------++-----------+
2668                        ^                                                                                ^
2669                        |                                                                                |
2670                        +--- item                                                                        +--- item->data
2671
2672                     Dynamically sized types (Type 2  Byte strings, Type 3  
2673                     UTF-8  strings, Type 4  Arrays, Type 5  Maps) may store
2674                     handle and data in separate locations. This enables  cre‐
2675                     ating large items (e.g byte strings) without realloc() or
2676                     copying large blocks of memory. One simply  attaches  the
2677                     correct pointer to the handle.
2678
2679       type cbor_item_metadata
2680              Union type of the following members, based on the item type:
2681
2682              struct _cbor_int_metadata int_metadata
2683                     Used both by both Types 0 & 1  Positive and negative in‐
2684                     tegers
2685
2686              struct _cbor_bytestring_metadata bytestring_metadata
2687
2688              struct _cbor_string_metadata string_metadata
2689
2690              struct _cbor_array_metadata array_metadata
2691
2692              struct _cbor_map_metadata map_metadata
2693
2694              struct _cbor_tag_metadata tag_metadata
2695
2696              struct _cbor_float_ctrl_metadata float_ctrl_metadata
2697
2698   Decoding
2699       As outlined in API, there decoding is based on  the  streaming  decoder
2700       Essentially, the decoder is a custom set of callbacks for the streaming
2701       decoder.
2702
2703   Changelog
2704   Next
2705   0.7.0 (2020-04-25)
2706
2707
2708         Fix   bad   encoding   of    NaN    half-floats    [[Fixes    #53]](‐
2709         https://github.com/PJK/libcbor/issues/53)        (discovered       by
2710         [BSipos-RKF](https://github.com/BSipos-RKF))
2711
2712Warning: Previous versions encoded NaNs as 0xf9e700  instead
2713                  of  0xf97e00;  if you rely on the broken behavior, this will
2714                  be a breaking change
2715
2716       • Fix potentially bad encoding of negative half-float with  exponent  <
2717         -14  [[Fixes  #112]](https://github.com/PJK/libcbor/issues/112) (dis‐
2718         covered by [yami36](https://github.com/yami36))
2719
2720
2721
2722         BREAKING:     Improved     bool     support      [[Fixes      #63]](‐
2723         https://github.com/PJK/libcbor/issues/63)
2724
2725                • Rename cbor_ctrl_is_bool to cbor_get_bool and fix the behav‐
2726                  ior
2727
2728                • Add cbor_set_bool
2729
2730       • Fix memory_allocation_test breaking the build without CBOR_CUSTOM_AL‐
2731         LOC   [[Fixes  #128]](https://github.com/PJK/libcbor/issues/128)  (by
2732         [panlinux](https://github.com/panlinux))
2733
2734       • [Fix  a  potential  build  issue  where   cJSON   includes   may   be
2735         misconfigured](https://github.com/PJK/libcbor/pull/132)
2736
2737
2738
2739         Breaking:  [Add  a limit on the size of the decoding context stack](‐
2740         https://github.com/PJK/libcbor/pull/138)     (by      [James-ZHANG](‐
2741         https://github.com/James-ZHANG))
2742
2743                • If  your  usecase requires parsing very deeply nested struc‐
2744                  tures, you might need to increase the default 2k  limit  via
2745                  CBOR_MAX_STACK_SIZE
2746
2747
2748
2749         Enable       LTO/IPO       based       on       [CheckIPOSupported](‐
2750         https://cmake.org/cmake/help/latest/module/CheckIPOSup
2751         ported.html#module:CheckIPOSupported)                      [[#143]](‐
2752         https://github.com/PJK/libcbor/pull/143)      (by      [xanderlent](‐
2753         https://github.com/xanderlent))
2754
2755                • If you rely on LTO being enabled and use CMake version older
2756                  than 3.9, you will need to re-enable it manually or  upgrade
2757                  your CMake
2758
2759   0.6.1 (2020-03-26)
2760
2761
2762         [Fix       bad       shared       library      version      number](‐
2763         https://github.com/PJK/libcbor/pull/131)
2764
2765Warning: Shared library built from the 0.6.0 release is  er‐
2766                  roneously  marked  as version "0.6.0", which makes it incom‐
2767                  patible with future releases including the v0.6.X line  even
2768                  though  they  may  be  compatible API/ABI-wise. Refer to the
2769                  documentation for the new SO versioning scheme.
2770
2771   0.6.0 (2020-03-15)
2772
2773
2774         Correctly      set      .so       version       [[Fixes       #52]](‐
2775         https://github.com/PJK/libcbor/issues/52).
2776
2777Warning:  All previous releases will be identified as 0.0 by
2778                  the linker.
2779
2780       • Fix  &  prevent  heap  overflow  error  in  example  code   [[#74]](‐
2781         https://github.com/PJK/libcbor/pull/74)                     [[#76]](‐
2782         https://github.com/PJK/libcbor/pull/76) (by @nevun)
2783
2784       • Correctly  set  OSX   dynamic   library   version   [[Fixes   #75]](‐
2785         https://github.com/PJK/libcbor/issues/75)
2786
2787       • [Fix   misplaced   0xFF   bytes   in  maps  possibly  causing  memory
2788         corruption](https://github.com/PJK/libcbor/pull/82)
2789
2790       • BREAKING: Fix handling & cleanup of failed memory allocation in  con‐
2791         structor    and    builder    helper    functions   [[Fixes   #84]](‐
2792         https://github.com/PJK/libcbor/issues/84)  -   All   cbor_new_*   and
2793         cbor_build_*  functions  will  now explicitly return NULL when memory
2794         allocation fails - It is up to the client to handle such cases
2795
2796       • Globally      enforced      code      style      [[Fixes      #83]](‐
2797         https://github.com/PJK/libcbor/issues/83)
2798
2799       • Fix    issue    possible    memory   corruption   bug   on   repeated
2800         cbor_(byte)string_add_chunk calls with intermittently failing realloc
2801         calls
2802
2803       • Fix  possibly  misaligned  reads  and writes when endian.h is uses or
2804         when   running   on   a    big-endian    machine    [[Fixes    #99](‐
2805         https://github.com/PJK/libcbor/issues/99),                   [#100](‐
2806         https://github.com/PJK/libcbor/issues/100)]
2807
2808       • [Improved   CI   setup   with    Travis-native    arm64    support](‐
2809         https://github.com/PJK/libcbor/pull/116)
2810
2811       • [Docs      migrated      to     Sphinx     2.4     and     Python3](‐
2812         https://github.com/PJK/libcbor/pull/117)
2813
2814   0.5.0 (2017-02-06)
2815       • Remove cmocka from the subtree (always rely on  system  or  user-pro‐
2816         vided version)
2817
2818       • Windows CI
2819
2820       • Only build tests if explicitly enabled (-DWITH_TESTS=ON)
2821
2822       • Fixed static header declarations (by cedric-d)
2823
2824       • Improved documentation (by Michael Richardson)
2825
2826       • Improved examples/readfile.c
2827
2828       • Reworked (re)allocation to handle huge inputs and overflows in size_t
2829         [[Fixes #16]](https://github.com/PJK/libcbor/issues/16)
2830
2831       • Improvements to C++ linkage  (corrected  cbor_empty_callbacks,  fixed
2832         restrict pointers) (by Dennis Bijwaard)
2833
2834       • Fixed  Linux installation directory depending on architecture [[Fixes
2835         #34]](https://github.com/PJK/libcbor/issues/34) (by jvymazal)
2836
2837       • Improved        32-bit        support         [[Fixes         #35]](‐
2838         https://github.com/PJK/libcbor/issues/35)
2839
2840       • Fixed         MSVC        compatibility        [[Fixes        #31]](‐
2841         https://github.com/PJK/libcbor/issues/31)
2842
2843       • Fixed   and    improved    half-float    encoding    [[Fixes    #5](‐
2844         https://github.com/PJK/libcbor/issues/5),                     [#11](‐
2845         https://github.com/PJK/libcbor/issues/11)]
2846
2847   0.4.0 (2015-12-25)
2848       Breaks build & header compatibility due to:
2849
2850       • Improved build configuration and feature check macros
2851
2852       • Endianess configuration fixes (by Erwin Kroon and David Grigsby)
2853
2854       • pkg-config compatibility (by Vincent Bernat)
2855
2856       • enable use of versioned SONAME (by Vincent Bernat)
2857
2858       • better fuzzer (wasn't random until now, ooops)
2859
2860   0.3.1 (2015-05-21)
2861       • documentation and comments improvements, mostly for the API reference
2862
2863   0.3.0 (2015-05-21)
2864       • Fixes, polishing, niceties across the code base
2865
2866       • Updated examples
2867
2868cbor_copy
2869
2870cbor_build_negint8, 16, 32, 64, matching asserts
2871
2872cbor_build_stringn
2873
2874cbor_build_tag
2875
2876cbor_build_float2, ...
2877
2878   0.2.1 (2015-05-17)
2879       • C99 support
2880
2881   0.2.0 (2015-05-17)
2882cbor_ctrl_bool -> cbor_ctrl_is_bool
2883
2884       • Added cbor_array_allocated & map equivalent
2885
2886       • Overhauled endianess conversion - ARM now works as expected
2887
2888       • 'sort.c' example added
2889
2890       • Significantly improved and doxyfied documentation
2891
2892   0.1.0 (2015-05-06)
2893       The initial release, yay!
2894
2895   Development
2896   Vision and principles
2897       Consistency and coherence are one of the key  characteristics  of  good
2898       software.   While the reality is never black and white, it is important
2899       libcbor contributors are working towards the same high-level goal. This
2900       document  attempts  to  set out the basic principles of libcbor and the
2901       rationale behind them. If you are contributing to libcbor or looking to
2902       evaluate whether libcbor is the right choice for your project, it might
2903       be worthwhile to skim through the section below.
2904
2905   Mission statement
2906       libcbor is the compact, full-featured, and safe CBOR library that works
2907       everywhere.
2908
2909   Goals
2910   RFC-conformance and full feature support
2911       Anything the standard allows, libcbor can do.
2912
2913       Why?  Because conformance and interoperability is the point of defining
2914       standards. Clients expect the support to be feature-complete and  there
2915       is no significant complexity reduction that can be achieved by slightly
2916       cutting corners, which means that the incremental cost of full RFC sup‐
2917       port  is comparatively small over "almost-conformance" seen in many al‐
2918       ternatives.
2919
2920   Safety
2921       Untrusted bytes from the network are the typical input.
2922
2923       Why? Because it is the client expectation. Vast  majority  of  security
2924       vulnerabilities  are violations of contracts -- in other words, bugs --
2925       anyway.
2926
2927   Self-containment
2928       libcbor has no runtime dependencies.
2929
2930       Why? Because any constraint imposed on libcbor has to be enforced tran‐
2931       sitively, which is difficult and leads to incompatibilities and distri‐
2932       bution issues, especially in IoT applications.
2933
2934   Portability
2935       If you can compile C for it, libcbor will work there.
2936
2937       Why? Lowest-common-denominator solution for system-level and IoT  soft‐
2938       ware  was  the original niche of libcbor. Users who rely on libcbor ex‐
2939       pect future updates to work on their target platform.
2940
2941   Stable and predictable API
2942       libcbor will not break without a warning.
2943
2944       Why? Industry-standard versioning is a basic  requirement  for  produc‐
2945       tion-quality  software. This is especially relevant in IoT environments
2946       where updates may be costly.
2947
2948   Performance
2949       libcbor is fast and resource-efficient by design
2950
2951       Why? Because the main maintainer is an avid hater of slow bloated soft‐
2952       ware.  Who wouldn't want more bang per their electricity buck?
2953
2954   Non-goals
2955          • Convenience  --  libcbor only provides the minimum surface to make
2956            it usable
2957
2958          • FFI/SWIG/interop support -- libcbor is primarily a C library for C
2959            clients
2960
2961          • One-off  usecases  support -- although there are primitives to re‐
2962            use, the basic assumption is that most clients want most  of  CBOR
2963            features
2964
2965   Development dependencies
2966CMocka (testing)
2967
2968Python and pip (Sphinx platform)
2969
2970Doxygen
2971
2972Sphinx (documentation)
2973
2974       • There are some Ruby scripts in misc
2975
2976Valgrind (memory correctness & profiling)
2977
2978GCOV/LCOV (test coverage)
2979
2980clang-format
2981
2982   Installing sphinx
2983          pip install sphinx
2984          pip install sphinx_rtd_theme
2985          pip install breathe
2986          pip install https://github.com/lepture/python-livereload/archive/master.zip
2987          pip install sphinx-autobuild
2988
2989       Further  instructions  on configuring advanced features can be found at
2990       http://read-the-docs.readthedocs.org/en/latest/install.html.
2991
2992   Live preview of docs
2993          cd doc
2994          make livehtml
2995
2996   Set up git hooks
2997       A catch-all git hook that runs clang-format and automatically refreshes
2998       the GH pages  contents located in docs can be symlinked:
2999
3000          ln -sf $(pwd)/misc/hooks/pre-commit .git/hooks
3001
3002   Testing and code coverage
3003       Please refer to Tests
3004

AUTHOR

3006       Pavel Kalvoda
3007
3009       2023 - 2020, Pavel Kalvoda
3010
3011
3012
3013
30140.7                              Jan 19, 2023                       LIBCBOR(1)
Impressum