1 | /**************************************************************************** |
2 | ** |
3 | ** Copyright (C) 2018 Intel Corporation |
4 | ** |
5 | ** Permission is hereby granted, free of charge, to any person obtaining a copy |
6 | ** of this software and associated documentation files (the "Software"), to deal |
7 | ** in the Software without restriction, including without limitation the rights |
8 | ** to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
9 | ** copies of the Software, and to permit persons to whom the Software is |
10 | ** furnished to do so, subject to the following conditions: |
11 | ** |
12 | ** The above copyright notice and this permission notice shall be included in |
13 | ** all copies or substantial portions of the Software. |
14 | ** |
15 | ** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
16 | ** IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
17 | ** FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
18 | ** AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
19 | ** LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
20 | ** OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN |
21 | ** THE SOFTWARE. |
22 | ** |
23 | ****************************************************************************/ |
24 | |
25 | #ifndef _BSD_SOURCE |
26 | #define _BSD_SOURCE 1 |
27 | #endif |
28 | #ifndef _DEFAULT_SOURCE |
29 | #define _DEFAULT_SOURCE 1 |
30 | #endif |
31 | #ifndef __STDC_LIMIT_MACROS |
32 | # define __STDC_LIMIT_MACROS 1 |
33 | #endif |
34 | |
35 | #include "cbor.h" |
36 | #include "cborinternal_p.h" |
37 | #include "compilersupport_p.h" |
38 | |
39 | #include <stdlib.h> |
40 | #include <string.h> |
41 | |
42 | /** |
43 | * \defgroup CborEncoding Encoding to CBOR |
44 | * \brief Group of functions used to encode data to CBOR. |
45 | * |
46 | * CborEncoder is used to encode data into a CBOR stream. The outermost |
47 | * CborEncoder is initialized by calling cbor_encoder_init(), with the buffer |
48 | * where the CBOR stream will be stored. The outermost CborEncoder is usually |
49 | * used to encode exactly one item, most often an array or map. It is possible |
50 | * to encode more than one item, but care must then be taken on the decoder |
51 | * side to ensure the state is reset after each item was decoded. |
52 | * |
53 | * Nested CborEncoder objects are created using cbor_encoder_create_array() and |
54 | * cbor_encoder_create_map(), later closed with cbor_encoder_close_container() |
55 | * or cbor_encoder_close_container_checked(). The pairs of creation and closing |
56 | * must be exactly matched and their parameters are always the same. |
57 | * |
58 | * CborEncoder writes directly to the user-supplied buffer, without extra |
59 | * buffering. CborEncoder does not allocate memory and CborEncoder objects are |
60 | * usually created on the stack of the encoding functions. |
61 | * |
62 | * The example below initializes a CborEncoder object with a buffer and encodes |
63 | * a single integer. |
64 | * |
65 | * \code |
66 | * uint8_t buf[16]; |
67 | * CborEncoder encoder; |
68 | * cbor_encoder_init(&encoder, &buf, sizeof(buf), 0); |
69 | * cbor_encode_int(&encoder, some_value); |
70 | * \endcode |
71 | * |
72 | * As explained before, usually the outermost CborEncoder object is used to add |
73 | * one array or map, which in turn contains multiple elements. The example |
74 | * below creates a CBOR map with one element: a key "foo" and a boolean value. |
75 | * |
76 | * \code |
77 | * uint8_t buf[16]; |
78 | * CborEncoder encoder, mapEncoder; |
79 | * cbor_encoder_init(&encoder, buf, sizeof(buf), 0); |
80 | * cbor_encoder_create_map(&encoder, &mapEncoder, 1); |
81 | * cbor_encode_text_stringz(&mapEncoder, "foo"); |
82 | * cbor_encode_boolean(&mapEncoder, some_value); |
83 | * cbor_encoder_close_container(&encoder, &mapEncoder); |
84 | * \endcode |
85 | * |
86 | * <h3 class="groupheader">Error checking and buffer size</h3> |
87 | * |
88 | * All functions operating on CborEncoder return a condition of type CborError. |
89 | * If the encoding was successful, they return CborNoError. Some functions do |
90 | * extra checking on the input provided and may return some other error |
91 | * conditions (for example, cbor_encode_simple_value() checks that the type is |
92 | * of the correct type). |
93 | * |
94 | * In addition, all functions check whether the buffer has enough bytes to |
95 | * encode the item being appended. If that is not possible, they return |
96 | * CborErrorOutOfMemory. |
97 | * |
98 | * It is possible to continue with the encoding of data past the first function |
99 | * that returns CborErrorOutOfMemory. CborEncoder functions will not overrun |
100 | * the buffer, but will instead count how many more bytes are needed to |
101 | * complete the encoding. At the end, you can obtain that count by calling |
102 | * cbor_encoder_get_extra_bytes_needed(). |
103 | * |
104 | * \section1 Finalizing the encoding |
105 | * |
106 | * Once all items have been appended and the containers have all been properly |
107 | * closed, the user-supplied buffer will contain the CBOR stream and may be |
108 | * immediately used. To obtain the size of the buffer, call |
109 | * cbor_encoder_get_buffer_size() with the original buffer pointer. |
110 | * |
111 | * The example below illustrates how one can encode an item with error checking |
112 | * and then pass on the buffer for network sending. |
113 | * |
114 | * \code |
115 | * uint8_t buf[16]; |
116 | * CborError err; |
117 | * CborEncoder encoder, mapEncoder; |
118 | * cbor_encoder_init(&encoder, buf, sizeof(buf), 0); |
119 | * err = cbor_encoder_create_map(&encoder, &mapEncoder, 1); |
120 | * if (!err) |
121 | * return err; |
122 | * err = cbor_encode_text_stringz(&mapEncoder, "foo"); |
123 | * if (!err) |
124 | * return err; |
125 | * err = cbor_encode_boolean(&mapEncoder, some_value); |
126 | * if (!err) |
127 | * return err; |
128 | * err = cbor_encoder_close_container_checked(&encoder, &mapEncoder); |
129 | * if (!err) |
130 | * return err; |
131 | * |
132 | * size_t len = cbor_encoder_get_buffer_size(&encoder, buf); |
133 | * send_payload(buf, len); |
134 | * return CborNoError; |
135 | * \endcode |
136 | * |
137 | * Finally, the example below expands on the one above and also |
138 | * deals with dynamically growing the buffer if the initial allocation wasn't |
139 | * big enough. Note the two places where the error checking was replaced with |
140 | * an cbor_assertion, showing where the author assumes no error can occur. |
141 | * |
142 | * \code |
143 | * uint8_t *encode_string_array(const char **strings, int n, size_t *bufsize) |
144 | * { |
145 | * CborError err; |
146 | * CborEncoder encoder, arrayEncoder; |
147 | * size_t size = 256; |
148 | * uint8_t *buf = NULL; |
149 | * |
150 | * while (1) { |
151 | * int i; |
152 | * size_t more_bytes; |
153 | * uint8_t *nbuf = realloc(buf, size); |
154 | * if (nbuf == NULL) |
155 | * goto error; |
156 | * buf = nbuf; |
157 | * |
158 | * cbor_encoder_init(&encoder, buf, size, 0); |
159 | * err = cbor_encoder_create_array(&encoder, &arrayEncoder, n); |
160 | * cbor_assert(err); // can't fail, the buffer is always big enough |
161 | * |
162 | * for (i = 0; i < n; ++i) { |
163 | * err = cbor_encode_text_stringz(&arrayEncoder, strings[i]); |
164 | * if (err && err != CborErrorOutOfMemory) |
165 | * goto error; |
166 | * } |
167 | * |
168 | * err = cbor_encoder_close_container_checked(&encoder, &arrayEncoder); |
169 | * cbor_assert(err); // shouldn't fail! |
170 | * |
171 | * more_bytes = cbor_encoder_get_extra_bytes_needed(encoder); |
172 | * if (more_size) { |
173 | * // buffer wasn't big enough, try again |
174 | * size += more_bytes; |
175 | * continue; |
176 | * } |
177 | * |
178 | * *bufsize = cbor_encoder_get_buffer_size(encoder, buf); |
179 | * return buf; |
180 | * } |
181 | * error: |
182 | * free(buf); |
183 | * return NULL; |
184 | * } |
185 | * \endcode |
186 | */ |
187 | |
188 | /** |
189 | * \addtogroup CborEncoding |
190 | * @{ |
191 | */ |
192 | |
193 | /** |
194 | * \struct CborEncoder |
195 | * Structure used to encode to CBOR. |
196 | */ |
197 | |
198 | /** |
199 | * Initializes a CborEncoder structure \a encoder by pointing it to buffer \a |
200 | * buffer of size \a size. The \a flags field is currently unused and must be |
201 | * zero. |
202 | */ |
203 | void cbor_encoder_init(CborEncoder *encoder, uint8_t *buffer, size_t size, int flags) |
204 | { |
205 | encoder->data.ptr = buffer; |
206 | encoder->end = buffer + size; |
207 | encoder->remaining = 2; |
208 | encoder->flags = flags; |
209 | } |
210 | |
211 | void cbor_encoder_init_writer(CborEncoder *encoder, CborEncoderWriteFunction writer, void *token) |
212 | { |
213 | #ifdef CBOR_ENCODER_WRITE_FUNCTION |
214 | (void) writer; |
215 | #else |
216 | encoder->data.writer = writer; |
217 | #endif |
218 | encoder->end = (uint8_t *)token; |
219 | encoder->remaining = 2; |
220 | encoder->flags = CborIteratorFlag_WriterFunction; |
221 | } |
222 | |
223 | static inline void put16(void *where, uint16_t v) |
224 | { |
225 | v = cbor_htons(v); |
226 | memcpy(dest: where, src: &v, n: sizeof(v)); |
227 | } |
228 | |
229 | /* Note: Since this is currently only used in situations where OOM is the only |
230 | * valid error, we KNOW this to be true. Thus, this function now returns just 'true', |
231 | * but if in the future, any function starts returning a non-OOM error, this will need |
232 | * to be changed to the test. At the moment, this is done to prevent more branches |
233 | * being created in the tinycbor output */ |
234 | static inline bool isOomError(CborError err) |
235 | { |
236 | if (CBOR_ENCODER_WRITER_CONTROL < 0) |
237 | return true; |
238 | |
239 | /* CborErrorOutOfMemory is the only negative error code, intentionally |
240 | * so we can write the test like this */ |
241 | return (int)err < 0; |
242 | } |
243 | |
244 | static inline void put32(void *where, uint32_t v) |
245 | { |
246 | v = cbor_htonl(v); |
247 | memcpy(dest: where, src: &v, n: sizeof(v)); |
248 | } |
249 | |
250 | static inline void put64(void *where, uint64_t v) |
251 | { |
252 | v = cbor_htonll(v); |
253 | memcpy(dest: where, src: &v, n: sizeof(v)); |
254 | } |
255 | |
256 | static inline bool would_overflow(CborEncoder *encoder, size_t len) |
257 | { |
258 | ptrdiff_t remaining = (ptrdiff_t)encoder->end; |
259 | remaining -= remaining ? (ptrdiff_t)encoder->data.ptr : encoder->data.bytes_needed; |
260 | remaining -= (ptrdiff_t)len; |
261 | return unlikely(remaining < 0); |
262 | } |
263 | |
264 | static inline void advance_ptr(CborEncoder *encoder, size_t n) |
265 | { |
266 | if (encoder->end) |
267 | encoder->data.ptr += n; |
268 | else |
269 | encoder->data.bytes_needed += n; |
270 | } |
271 | |
272 | static inline CborError append_to_buffer(CborEncoder *encoder, const void *data, size_t len, |
273 | CborEncoderAppendType appendType) |
274 | { |
275 | if (CBOR_ENCODER_WRITER_CONTROL >= 0) { |
276 | if (encoder->flags & CborIteratorFlag_WriterFunction || CBOR_ENCODER_WRITER_CONTROL != 0) { |
277 | # ifdef CBOR_ENCODER_WRITE_FUNCTION |
278 | return CBOR_ENCODER_WRITE_FUNCTION(self: encoder->end, ptr: data, len, t: appendType); |
279 | # else |
280 | return encoder->data.writer(encoder->end, data, len, appendType); |
281 | # endif |
282 | } |
283 | } |
284 | |
285 | #if CBOR_ENCODER_WRITER_CONTROL <= 0 |
286 | if (would_overflow(encoder, len)) { |
287 | if (encoder->end != NULL) { |
288 | len -= encoder->end - encoder->data.ptr; |
289 | encoder->end = NULL; |
290 | encoder->data.bytes_needed = 0; |
291 | } |
292 | |
293 | advance_ptr(encoder, len); |
294 | return CborErrorOutOfMemory; |
295 | } |
296 | |
297 | memcpy(encoder->data.ptr, data, len); |
298 | encoder->data.ptr += len; |
299 | #endif |
300 | return CborNoError; |
301 | } |
302 | |
303 | static inline CborError append_byte_to_buffer(CborEncoder *encoder, uint8_t byte) |
304 | { |
305 | return append_to_buffer(encoder, data: &byte, len: 1, appendType: CborEncoderAppendCborData); |
306 | } |
307 | |
308 | static inline CborError encode_number_no_update(CborEncoder *encoder, uint64_t ui, uint8_t shiftedMajorType) |
309 | { |
310 | /* Little-endian would have been so much more convenient here: |
311 | * We could just write at the beginning of buf but append_to_buffer |
312 | * only the necessary bytes. |
313 | * Since it has to be big endian, do it the other way around: |
314 | * write from the end. */ |
315 | uint64_t buf[2]; |
316 | uint8_t *const bufend = (uint8_t *)buf + sizeof(buf); |
317 | uint8_t *bufstart = bufend - 1; |
318 | put64(where: buf + 1, v: ui); /* we probably have a bunch of zeros in the beginning */ |
319 | |
320 | if (ui < Value8Bit) { |
321 | *bufstart += shiftedMajorType; |
322 | } else { |
323 | uint8_t more = 0; |
324 | if (ui > 0xffU) |
325 | ++more; |
326 | if (ui > 0xffffU) |
327 | ++more; |
328 | if (ui > 0xffffffffU) |
329 | ++more; |
330 | bufstart -= (size_t)1 << more; |
331 | *bufstart = shiftedMajorType + Value8Bit + more; |
332 | } |
333 | |
334 | return append_to_buffer(encoder, data: bufstart, len: bufend - bufstart, appendType: CborEncoderAppendCborData); |
335 | } |
336 | |
337 | static inline void saturated_decrement(CborEncoder *encoder) |
338 | { |
339 | if (encoder->remaining) |
340 | --encoder->remaining; |
341 | } |
342 | |
343 | static inline CborError encode_number(CborEncoder *encoder, uint64_t ui, uint8_t shiftedMajorType) |
344 | { |
345 | saturated_decrement(encoder); |
346 | return encode_number_no_update(encoder, ui, shiftedMajorType); |
347 | } |
348 | |
349 | /** |
350 | * Appends the unsigned 64-bit integer \a value to the CBOR stream provided by |
351 | * \a encoder. |
352 | * |
353 | * \sa cbor_encode_negative_int, cbor_encode_int |
354 | */ |
355 | CborError cbor_encode_uint(CborEncoder *encoder, uint64_t value) |
356 | { |
357 | return encode_number(encoder, ui: value, shiftedMajorType: UnsignedIntegerType << MajorTypeShift); |
358 | } |
359 | |
360 | /** |
361 | * Appends the negative 64-bit integer whose absolute value is \a |
362 | * absolute_value to the CBOR stream provided by \a encoder. |
363 | * |
364 | * If the value \a absolute_value is zero, this function encodes -2^64. |
365 | * |
366 | * \sa cbor_encode_uint, cbor_encode_int |
367 | */ |
368 | CborError cbor_encode_negative_int(CborEncoder *encoder, uint64_t absolute_value) |
369 | { |
370 | return encode_number(encoder, ui: absolute_value - 1, shiftedMajorType: NegativeIntegerType << MajorTypeShift); |
371 | } |
372 | |
373 | /** |
374 | * Appends the signed 64-bit integer \a value to the CBOR stream provided by |
375 | * \a encoder. |
376 | * |
377 | * \sa cbor_encode_negative_int, cbor_encode_uint |
378 | */ |
379 | CborError cbor_encode_int(CborEncoder *encoder, int64_t value) |
380 | { |
381 | /* adapted from code in RFC 7049 appendix C (pseudocode) */ |
382 | uint64_t ui = value >> 63; /* extend sign to whole length */ |
383 | uint8_t majorType = ui & 0x20; /* extract major type */ |
384 | ui ^= value; /* complement negatives */ |
385 | return encode_number(encoder, ui, shiftedMajorType: majorType); |
386 | } |
387 | |
388 | /** |
389 | * Appends the CBOR Simple Type of value \a value to the CBOR stream provided by |
390 | * \a encoder. |
391 | * |
392 | * This function may return error CborErrorIllegalSimpleType if the \a value |
393 | * variable contains a number that is not a valid simple type. |
394 | */ |
395 | CborError cbor_encode_simple_value(CborEncoder *encoder, uint8_t value) |
396 | { |
397 | #ifndef CBOR_ENCODER_NO_CHECK_USER |
398 | /* check if this is a valid simple type */ |
399 | if (value >= HalfPrecisionFloat && value <= Break) |
400 | return CborErrorIllegalSimpleType; |
401 | #endif |
402 | return encode_number(encoder, ui: value, shiftedMajorType: SimpleTypesType << MajorTypeShift); |
403 | } |
404 | |
405 | /** |
406 | * Appends the floating-point value of type \a fpType and pointed to by \a |
407 | * value to the CBOR stream provided by \a encoder. The value of \a fpType must |
408 | * be one of CborHalfFloatType, CborFloatType or CborDoubleType, otherwise the |
409 | * behavior of this function is undefined. |
410 | * |
411 | * This function is useful for code that needs to pass through floating point |
412 | * values but does not wish to have the actual floating-point code. |
413 | * |
414 | * \sa cbor_encode_half_float, cbor_encode_float_as_half_float, cbor_encode_float, cbor_encode_double |
415 | */ |
416 | CborError cbor_encode_floating_point(CborEncoder *encoder, CborType fpType, const void *value) |
417 | { |
418 | unsigned size; |
419 | uint8_t buf[1 + sizeof(uint64_t)]; |
420 | cbor_assert(fpType == CborHalfFloatType || fpType == CborFloatType || fpType == CborDoubleType); |
421 | buf[0] = fpType; |
422 | |
423 | size = 2U << (fpType - CborHalfFloatType); |
424 | if (size == 8) |
425 | put64(where: buf + 1, v: *(const uint64_t*)value); |
426 | else if (size == 4) |
427 | put32(where: buf + 1, v: *(const uint32_t*)value); |
428 | else |
429 | put16(where: buf + 1, v: *(const uint16_t*)value); |
430 | saturated_decrement(encoder); |
431 | return append_to_buffer(encoder, data: buf, len: size + 1, appendType: CborEncoderAppendCborData); |
432 | } |
433 | |
434 | /** |
435 | * Appends the CBOR tag \a tag to the CBOR stream provided by \a encoder. |
436 | * |
437 | * \sa CborTag |
438 | */ |
439 | CborError cbor_encode_tag(CborEncoder *encoder, CborTag tag) |
440 | { |
441 | /* tags don't count towards the number of elements in an array or map */ |
442 | return encode_number_no_update(encoder, ui: tag, shiftedMajorType: TagType << MajorTypeShift); |
443 | } |
444 | |
445 | static CborError encode_string(CborEncoder *encoder, size_t length, uint8_t shiftedMajorType, const void *string) |
446 | { |
447 | CborError err = encode_number(encoder, ui: length, shiftedMajorType); |
448 | if (err && !isOomError(err)) |
449 | return err; |
450 | return append_to_buffer(encoder, data: string, len: length, appendType: CborEncoderAppendStringData); |
451 | } |
452 | |
453 | /** |
454 | * \fn CborError cbor_encode_text_stringz(CborEncoder *encoder, const char *string) |
455 | * |
456 | * Appends the null-terminated text string \a string to the CBOR stream |
457 | * provided by \a encoder. CBOR requires that \a string be valid UTF-8, but |
458 | * TinyCBOR makes no verification of correctness. The terminating null is not |
459 | * included in the stream. |
460 | * |
461 | * \sa cbor_encode_text_string, cbor_encode_byte_string |
462 | */ |
463 | |
464 | /** |
465 | * Appends the text string \a string of length \a length to the CBOR stream |
466 | * provided by \a encoder. CBOR requires that \a string be valid UTF-8, but |
467 | * TinyCBOR makes no verification of correctness. |
468 | * |
469 | * \sa CborError cbor_encode_text_stringz, cbor_encode_byte_string |
470 | */ |
471 | CborError cbor_encode_byte_string(CborEncoder *encoder, const uint8_t *string, size_t length) |
472 | { |
473 | return encode_string(encoder, length, shiftedMajorType: ByteStringType << MajorTypeShift, string); |
474 | } |
475 | |
476 | /** |
477 | * Appends the byte string \a string of length \a length to the CBOR stream |
478 | * provided by \a encoder. CBOR byte strings are arbitrary raw data. |
479 | * |
480 | * \sa cbor_encode_text_stringz, cbor_encode_text_string |
481 | */ |
482 | CborError cbor_encode_text_string(CborEncoder *encoder, const char *string, size_t length) |
483 | { |
484 | return encode_string(encoder, length, shiftedMajorType: TextStringType << MajorTypeShift, string); |
485 | } |
486 | |
487 | #ifdef __GNUC__ |
488 | __attribute__((noinline)) |
489 | #endif |
490 | static CborError create_container(CborEncoder *encoder, CborEncoder *container, size_t length, uint8_t shiftedMajorType) |
491 | { |
492 | CborError err; |
493 | container->data.ptr = encoder->data.ptr; |
494 | container->end = encoder->end; |
495 | saturated_decrement(encoder); |
496 | container->remaining = length + 1; /* overflow ok on CborIndefiniteLength */ |
497 | |
498 | cbor_static_assert((int)CborIteratorFlag_ContainerIsMap_ == (int)CborIteratorFlag_ContainerIsMap); |
499 | cbor_static_assert(((MapType << MajorTypeShift) & CborIteratorFlag_ContainerIsMap) == CborIteratorFlag_ContainerIsMap); |
500 | cbor_static_assert(((ArrayType << MajorTypeShift) & CborIteratorFlag_ContainerIsMap) == 0); |
501 | container->flags = shiftedMajorType & CborIteratorFlag_ContainerIsMap; |
502 | if (CBOR_ENCODER_WRITER_CONTROL == 0) |
503 | container->flags |= encoder->flags & CborIteratorFlag_WriterFunction; |
504 | |
505 | if (length == CborIndefiniteLength) { |
506 | container->flags |= CborIteratorFlag_UnknownLength; |
507 | err = append_byte_to_buffer(encoder: container, byte: shiftedMajorType + IndefiniteLength); |
508 | } else { |
509 | if (shiftedMajorType & CborIteratorFlag_ContainerIsMap) |
510 | container->remaining += length; |
511 | err = encode_number_no_update(encoder: container, ui: length, shiftedMajorType); |
512 | } |
513 | return err; |
514 | } |
515 | |
516 | /** |
517 | * Creates a CBOR array in the CBOR stream provided by \a encoder and |
518 | * initializes \a arrayEncoder so that items can be added to the array using |
519 | * the CborEncoder functions. The array must be terminated by calling either |
520 | * cbor_encoder_close_container() or cbor_encoder_close_container_checked() |
521 | * with the same \a encoder and \a arrayEncoder parameters. |
522 | * |
523 | * The number of items inserted into the array must be exactly \a length items, |
524 | * otherwise the stream is invalid. If the number of items is not known when |
525 | * creating the array, the constant \ref CborIndefiniteLength may be passed as |
526 | * length instead. |
527 | * |
528 | * \sa cbor_encoder_create_map |
529 | */ |
530 | CborError cbor_encoder_create_array(CborEncoder *encoder, CborEncoder *arrayEncoder, size_t length) |
531 | { |
532 | return create_container(encoder, container: arrayEncoder, length, shiftedMajorType: ArrayType << MajorTypeShift); |
533 | } |
534 | |
535 | /** |
536 | * Creates a CBOR map in the CBOR stream provided by \a encoder and |
537 | * initializes \a mapEncoder so that items can be added to the map using |
538 | * the CborEncoder functions. The map must be terminated by calling either |
539 | * cbor_encoder_close_container() or cbor_encoder_close_container_checked() |
540 | * with the same \a encoder and \a mapEncoder parameters. |
541 | * |
542 | * The number of pair of items inserted into the map must be exactly \a length |
543 | * items, otherwise the stream is invalid. If the number is not known |
544 | * when creating the map, the constant \ref CborIndefiniteLength may be passed as |
545 | * length instead. |
546 | * |
547 | * \b{Implementation limitation:} TinyCBOR cannot encode more than SIZE_MAX/2 |
548 | * key-value pairs in the stream. If the length \a length is larger than this |
549 | * value (and is not \ref CborIndefiniteLength), this function returns error |
550 | * CborErrorDataTooLarge. |
551 | * |
552 | * \sa cbor_encoder_create_array |
553 | */ |
554 | CborError cbor_encoder_create_map(CborEncoder *encoder, CborEncoder *mapEncoder, size_t length) |
555 | { |
556 | if (length != CborIndefiniteLength && length > SIZE_MAX / 2) |
557 | return CborErrorDataTooLarge; |
558 | return create_container(encoder, container: mapEncoder, length, shiftedMajorType: MapType << MajorTypeShift); |
559 | } |
560 | |
561 | /** |
562 | * Closes the CBOR container (array or map) provided by \a containerEncoder and |
563 | * updates the CBOR stream provided by \a encoder. Both parameters must be the |
564 | * same as were passed to cbor_encoder_create_array() or |
565 | * cbor_encoder_create_map(). |
566 | * |
567 | * Since version 0.5, this function verifies that the number of items (or pairs |
568 | * of items, in the case of a map) was correct. It is no longer necessary to call |
569 | * cbor_encoder_close_container_checked() instead. |
570 | * |
571 | * \sa cbor_encoder_create_array(), cbor_encoder_create_map() |
572 | */ |
573 | CborError cbor_encoder_close_container(CborEncoder *encoder, const CborEncoder *containerEncoder) |
574 | { |
575 | if (encoder->end && !(encoder->flags & CborIteratorFlag_WriterFunction)) |
576 | encoder->data.ptr = containerEncoder->data.ptr; |
577 | else |
578 | encoder->data.bytes_needed = containerEncoder->data.bytes_needed; |
579 | encoder->end = containerEncoder->end; |
580 | if (containerEncoder->flags & CborIteratorFlag_UnknownLength) |
581 | return append_byte_to_buffer(encoder, byte: BreakByte); |
582 | |
583 | if (containerEncoder->remaining != 1) |
584 | return containerEncoder->remaining == 0 ? CborErrorTooManyItems : CborErrorTooFewItems; |
585 | |
586 | if (!encoder->end) |
587 | return CborErrorOutOfMemory; /* keep the state */ |
588 | return CborNoError; |
589 | } |
590 | |
591 | /** |
592 | * \fn CborError cbor_encode_boolean(CborEncoder *encoder, bool value) |
593 | * |
594 | * Appends the boolean value \a value to the CBOR stream provided by \a encoder. |
595 | */ |
596 | |
597 | /** |
598 | * \fn CborError cbor_encode_null(CborEncoder *encoder) |
599 | * |
600 | * Appends the CBOR type representing a null value to the CBOR stream provided |
601 | * by \a encoder. |
602 | * |
603 | * \sa cbor_encode_undefined() |
604 | */ |
605 | |
606 | /** |
607 | * \fn CborError cbor_encode_undefined(CborEncoder *encoder) |
608 | * |
609 | * Appends the CBOR type representing an undefined value to the CBOR stream |
610 | * provided by \a encoder. |
611 | * |
612 | * \sa cbor_encode_null() |
613 | */ |
614 | |
615 | /** |
616 | * \fn CborError cbor_encode_half_float(CborEncoder *encoder, const void *value) |
617 | * |
618 | * Appends the IEEE 754 half-precision (16-bit) floating point value pointed to |
619 | * by \a value to the CBOR stream provided by \a encoder. |
620 | * |
621 | * \sa cbor_encode_floating_point(), cbor_encode_float(), cbor_encode_double() |
622 | */ |
623 | |
624 | /** |
625 | * \fn CborError cbor_encode_float_as_half_float(CborEncoder *encoder, float value) |
626 | * |
627 | * Convert the IEEE 754 single-precision (32-bit) floating point value \a value |
628 | * to the IEEE 754 half-precision (16-bit) floating point value and append it |
629 | * to the CBOR stream provided by \a encoder. |
630 | * The \a value should be in the range of the IEEE 754 half-precision floating point type, |
631 | * INFINITY, -INFINITY, or NAN, otherwise the behavior of this function is undefined. |
632 | * |
633 | * \sa cbor_encode_floating_point(), cbor_encode_float(), cbor_encode_double() |
634 | */ |
635 | |
636 | /** |
637 | * \fn CborError cbor_encode_float(CborEncoder *encoder, float value) |
638 | * |
639 | * Appends the IEEE 754 single-precision (32-bit) floating point value \a value |
640 | * to the CBOR stream provided by \a encoder. |
641 | * |
642 | * \sa cbor_encode_floating_point(), cbor_encode_half_float(), cbor_encode_float_as_half_float(), cbor_encode_double() |
643 | */ |
644 | |
645 | /** |
646 | * \fn CborError cbor_encode_double(CborEncoder *encoder, double value) |
647 | * |
648 | * Appends the IEEE 754 double-precision (64-bit) floating point value \a value |
649 | * to the CBOR stream provided by \a encoder. |
650 | * |
651 | * \sa cbor_encode_floating_point(), cbor_encode_half_float(), cbor_encode_float_as_half_float(), cbor_encode_float() |
652 | */ |
653 | |
654 | /** |
655 | * \fn size_t cbor_encoder_get_buffer_size(const CborEncoder *encoder, const uint8_t *buffer) |
656 | * |
657 | * Returns the total size of the buffer starting at \a buffer after the |
658 | * encoding finished without errors. The \a encoder and \a buffer arguments |
659 | * must be the same as supplied to cbor_encoder_init(). |
660 | * |
661 | * If the encoding process had errors, the return value of this function is |
662 | * meaningless. If the only errors were CborErrorOutOfMemory, instead use |
663 | * cbor_encoder_get_extra_bytes_needed() to find out by how much to grow the |
664 | * buffer before encoding again. |
665 | * |
666 | * See \ref CborEncoding for an example of using this function. |
667 | * |
668 | * \sa cbor_encoder_init(), cbor_encoder_get_extra_bytes_needed(), CborEncoding |
669 | */ |
670 | |
671 | /** |
672 | * \fn size_t cbor_encoder_get_extra_bytes_needed(const CborEncoder *encoder) |
673 | * |
674 | * Returns how many more bytes the original buffer supplied to |
675 | * cbor_encoder_init() needs to be extended by so that no CborErrorOutOfMemory |
676 | * condition will happen for the encoding. If the buffer was big enough, this |
677 | * function returns 0. The \a encoder must be the original argument as passed |
678 | * to cbor_encoder_init(). |
679 | * |
680 | * This function is usually called after an encoding sequence ended with one or |
681 | * more CborErrorOutOfMemory errors, but no other error. If any other error |
682 | * happened, the return value of this function is meaningless. |
683 | * |
684 | * See \ref CborEncoding for an example of using this function. |
685 | * |
686 | * \sa cbor_encoder_init(), cbor_encoder_get_buffer_size(), CborEncoding |
687 | */ |
688 | |
689 | /** @} */ |
690 | |