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