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