1 /****************************************************************************
3 ** Copyright (C) 2016 Intel Corporation
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:
12 ** The above copyright notice and this permission notice shall be included in
13 ** all copies or substantial portions of the Software.
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
23 ****************************************************************************/
26 #define _DEFAULT_SOURCE 1
27 #ifndef __STDC_LIMIT_MACROS
28 # define __STDC_LIMIT_MACROS 1
32 #include "cborconstants_p.h"
33 #include "compilersupport_p.h"
39 #include "assert_p.h" /* Always include last */
42 * \defgroup CborEncoding Encoding to CBOR
43 * \brief Group of functions used to encode data to CBOR.
45 * CborEncoder is used to encode data into a CBOR stream. The outermost
46 * CborEncoder is initialized by calling cbor_encoder_init(), with the buffer
47 * where the CBOR stream will be stored. The outermost CborEncoder is usually
48 * used to encode exactly one item, most often an array or map. It is possible
49 * to encode more than one item, but care must then be taken on the decoder
50 * side to ensure the state is reset after each item was decoded.
52 * Nested CborEncoder objects are created using cbor_encoder_create_array() and
53 * cbor_encoder_create_map(), later closed with cbor_encoder_close_container()
54 * or cbor_encoder_close_container_checked(). The pairs of creation and closing
55 * must be exactly matched and their parameters are always the same.
57 * CborEncoder writes directly to the user-supplied buffer, without extra
58 * buffering. CborEncoder does not allocate memory and CborEncoder objects are
59 * usually created on the stack of the encoding functions.
61 * The example below initializes a CborEncoder object with a buffer and encodes
66 * CborEncoder encoder;
67 * cbor_encoder_init(&encoder, &buf, sizeof(buf), 0);
68 * cbor_encode_int(&encoder, some_value);
71 * As explained before, usually the outermost CborEncoder object is used to add
72 * one array or map, which in turn contains multiple elements. The example
73 * below creates a CBOR map with one element: a key "foo" and a boolean value.
77 * CborEncoder encoder, mapEncoder;
78 * cbor_encoder_init(&encoder, &buf, sizeof(buf), 0);
79 * cbor_encoder_create_map(&encoder, &mapEncoder, 1);
80 * cbor_encode_text_stringz(&mapEncoder, "foo");
81 * cbor_encode_boolean(&mapEncoder, some_value);
82 * cbor_encoder_close_container(&encoder, &mapEncoder);
85 * <h3 class="groupheader">Error checking and buffer size</h2>
87 * All functions operating on CborEncoder return a condition of type CborError.
88 * If the encoding was successful, they return CborNoError. Some functions do
89 * extra checking on the input provided and may return some other error
90 * conditions (for example, cbor_encode_simple_value() checks that the type is
91 * of the correct type).
93 * In addition, all functions check whether the buffer has enough bytes to
94 * encode the item being appended. If that is not possible, they return
95 * CborErrorOutOfMemory.
97 * It is possible to continue with the encoding of data past the first function
98 * that returns CborErrorOutOfMemory. CborEncoder functions will not overrun
99 * the buffer, but will instead count how many more bytes are needed to
100 * complete the encoding. At the end, you can obtain that count by calling
101 * cbor_encoder_get_extra_bytes_needed().
103 * \section1 Finalizing the encoding
105 * Once all items have been appended and the containers have all been properly
106 * closed, the user-supplied buffer will contain the CBOR stream and may be
107 * immediately used. To obtain the size of the buffer, call
108 * cbor_encoder_get_buffer_size() with the original buffer pointer.
110 * The example below illustrates how one can encode an item with error checking
111 * and then pass on the buffer for network sending.
116 * CborEncoder encoder, mapEncoder;
117 * cbor_encoder_init(&encoder, &buf, sizeof(buf), 0);
118 * err = cbor_encoder_create_map(&encoder, &mapEncoder, 1);
121 * err = cbor_encode_text_stringz(&mapEncoder, "foo");
124 * err = cbor_encode_boolean(&mapEncoder, some_value);
127 * err = cbor_encoder_close_container_checked(&encoder, &mapEncoder);
131 * size_t len = cbor_encoder_get_buffer_size(&encoder, buf);
132 * send_payload(buf, len);
133 * return CborNoError;
136 * Finally, the example below illustrates expands on the one above and also
137 * deals with dynamically growing the buffer if the initial allocation wasn't
138 * big enough. Note the two places where the error checking was replaced with
139 * an assertion, showing where the author assumes no error can occur.
142 * uint8_t *encode_string_array(const char **strings, int n, size_t *bufsize)
145 * CborEncoder encoder, arrayEncoder;
147 * uint8_t *buf = NULL;
152 * uint8_t *nbuf = realloc(buf, size);
157 * cbor_encoder_init(&encoder, &buf, size, 0);
158 * err = cbor_encoder_create_array(&encoder, &arrayEncoder, n);
159 * assert(err); // can't fail, the buffer is always big enough
161 * for (i = 0; i < n; ++i) {
162 * err = cbor_encode_text_stringz(&arrayEncoder, strings[i]);
163 * if (err && err != CborErrorOutOfMemory)
167 * err = cbor_encoder_close_container_checked(&encoder, &arrayEncoder);
168 * assert(err); // shouldn't fail!
170 * more_bytes = cbor_encoder_get_extra_bytes_needed(encoder);
172 * // buffer wasn't big enough, try again
173 * size += more_bytes;
177 * *bufsize = cbor_encoder_get_buffer_size(encoder, buf);
188 * \addtogroup CborEncoding
193 * \struct CborEncoder
194 * Structure used to encode to CBOR.
198 * Initializes a CborEncoder structure \a encoder by pointing it to buffer \a
199 * buffer of size \a size. The \a flags field is currently unused and must be
202 void cbor_encoder_init(CborEncoder *encoder, uint8_t *buffer, size_t size, int flags)
204 encoder->ptr = buffer;
205 encoder->end = buffer + size;
207 encoder->flags = flags;
210 static inline void put16(void *where, uint16_t v)
213 memcpy(where, &v, sizeof(v));
216 /* Note: Since this is currently only used in situations where OOM is the only
217 * valid error, we KNOW this to be true. Thus, this function now returns just 'true',
218 * but if in the future, any function starts returning a non-OOM error, this will need
219 * to be changed to the test. At the moment, this is done to prevent more branches
220 * being created in the tinycbor output */
221 static inline bool isOomError(CborError err)
227 static inline void put32(void *where, uint32_t v)
230 memcpy(where, &v, sizeof(v));
233 static inline void put64(void *where, uint64_t v)
236 memcpy(where, &v, sizeof(v));
239 static inline bool would_overflow(CborEncoder *encoder, size_t len)
241 ptrdiff_t remaining = (ptrdiff_t)encoder->end;
242 remaining -= remaining ? (ptrdiff_t)encoder->ptr : encoder->bytes_needed;
243 remaining -= (ptrdiff_t)len;
244 return unlikely(remaining < 0);
247 static inline void advance_ptr(CborEncoder *encoder, size_t n)
252 encoder->bytes_needed += n;
255 static inline CborError append_to_buffer(CborEncoder *encoder, const void *data, size_t len)
257 if (would_overflow(encoder, len)) {
258 if (encoder->end != NULL) {
259 len -= encoder->end - encoder->ptr;
261 encoder->bytes_needed = 0;
264 advance_ptr(encoder, len);
265 return CborErrorOutOfMemory;
268 memcpy(encoder->ptr, data, len);
273 static inline CborError append_byte_to_buffer(CborEncoder *encoder, uint8_t byte)
275 return append_to_buffer(encoder, &byte, 1);
278 static inline CborError encode_number_no_update(CborEncoder *encoder, uint64_t ui, uint8_t shiftedMajorType)
280 /* Little-endian would have been so much more convenient here:
281 * We could just write at the beginning of buf but append_to_buffer
282 * only the necessary bytes.
283 * Since it has to be big endian, do it the other way around:
284 * write from the end. */
286 uint8_t *const bufend = (uint8_t *)buf + sizeof(buf);
287 uint8_t *bufstart = bufend - 1;
288 put64(buf + 1, ui); /* we probably have a bunch of zeros in the beginning */
290 if (ui < Value8Bit) {
291 *bufstart += shiftedMajorType;
298 if (ui > 0xffffffffU)
300 bufstart -= (size_t)1 << more;
301 *bufstart = shiftedMajorType + Value8Bit + more;
304 return append_to_buffer(encoder, bufstart, bufend - bufstart);
307 static inline CborError encode_number(CborEncoder *encoder, uint64_t ui, uint8_t shiftedMajorType)
310 return encode_number_no_update(encoder, ui, shiftedMajorType);
314 * Appends the unsigned 64-bit integer \a value to the CBOR stream provided by
317 * \sa cbor_encode_negative_int, cbor_encode_int
319 CborError cbor_encode_uint(CborEncoder *encoder, uint64_t value)
321 return encode_number(encoder, value, UnsignedIntegerType << MajorTypeShift);
325 * Appends the negative 64-bit integer whose absolute value is \a
326 * absolute_value to the CBOR stream provided by \a encoder.
328 * \sa cbor_encode_uint, cbor_encode_int
330 CborError cbor_encode_negative_int(CborEncoder *encoder, uint64_t absolute_value)
332 return encode_number(encoder, absolute_value, NegativeIntegerType << MajorTypeShift);
336 * Appends the signed 64-bit integer \a value to the CBOR stream provided by
339 * \sa cbor_encode_negative_int, cbor_encode_uint
341 CborError cbor_encode_int(CborEncoder *encoder, int64_t value)
343 /* adapted from code in RFC 7049 appendix C (pseudocode) */
344 uint64_t ui = value >> 63; /* extend sign to whole length */
345 uint8_t majorType = ui & 0x20; /* extract major type */
346 ui ^= value; /* complement negatives */
347 return encode_number(encoder, ui, majorType);
351 * Appends the CBOR Simple Type of value \a value to the CBOR stream provided by
354 * This function may return error CborErrorIllegalSimpleType if the \a value
355 * variable contains a number that is not a valid simple type.
357 CborError cbor_encode_simple_value(CborEncoder *encoder, uint8_t value)
359 #ifndef CBOR_ENCODER_NO_CHECK_USER
360 /* check if this is a valid simple type */
361 if (value >= HalfPrecisionFloat && value <= Break)
362 return CborErrorIllegalSimpleType;
364 return encode_number(encoder, value, SimpleTypesType << MajorTypeShift);
368 * Appends the floating-point value of type \a fpType and pointed to by \a
369 * value to the CBOR stream provided by \a encoder. The value of \a fpType must
370 * be one of CborHalfFloatType, CborFloatType or CborDoubleType, otherwise the
371 * behavior of this function is undefined.
373 * This function is useful for code that needs to pass through floating point
374 * values but does not wish to have the actual floating-point code.
376 * \sa cbor_encode_half_float, cbor_encode_float, cbor_encode_double
378 CborError cbor_encode_floating_point(CborEncoder *encoder, CborType fpType, const void *value)
380 uint8_t buf[1 + sizeof(uint64_t)];
381 assert(fpType == CborHalfFloatType || fpType == CborFloatType || fpType == CborDoubleType);
384 unsigned size = 2U << (fpType - CborHalfFloatType);
386 put64(buf + 1, *(const uint64_t*)value);
388 put32(buf + 1, *(const uint32_t*)value);
390 put16(buf + 1, *(const uint16_t*)value);
392 return append_to_buffer(encoder, buf, size + 1);
396 * Appends the CBOR tag \a tag to the CBOR stream provided by \a encoder.
400 CborError cbor_encode_tag(CborEncoder *encoder, CborTag tag)
402 /* tags don't count towards the number of elements in an array or map */
403 return encode_number_no_update(encoder, tag, TagType << MajorTypeShift);
406 static CborError encode_string(CborEncoder *encoder, size_t length, uint8_t shiftedMajorType, const void *string)
408 CborError err = encode_number(encoder, length, shiftedMajorType);
409 if (err && !isOomError(err))
411 return append_to_buffer(encoder, string, length);
415 * \fn CborError cbor_encode_text_stringz(CborEncoder *encoder, const char *string)
417 * Appends the null-terminated text string \a string to the CBOR stream
418 * provided by \a encoder. CBOR requires that \a string be valid UTF-8, but
419 * TinyCBOR makes no verification of correctness. The terminating null is not
420 * included in the stream.
422 * \sa cbor_encode_text_string, cbor_encode_byte_string
426 * Appends the text string \a string of length \a length to the CBOR stream
427 * provided by \a encoder. CBOR requires that \a string be valid UTF-8, but
428 * TinyCBOR makes no verification of correctness.
430 * \sa CborError cbor_encode_text_stringz, cbor_encode_byte_string
432 CborError cbor_encode_byte_string(CborEncoder *encoder, const uint8_t *string, size_t length)
434 return encode_string(encoder, length, ByteStringType << MajorTypeShift, string);
438 * Appends the byte string \a string of length \a length to the CBOR stream
439 * provided by \a encoder. CBOR byte strings are arbitrary raw data.
441 * \sa cbor_encode_text_stringz, cbor_encode_text_string
443 CborError cbor_encode_text_string(CborEncoder *encoder, const char *string, size_t length)
445 return encode_string(encoder, length, TextStringType << MajorTypeShift, string);
449 __attribute__((noinline))
451 static CborError create_container(CborEncoder *encoder, CborEncoder *container, size_t length, uint8_t shiftedMajorType)
454 container->ptr = encoder->ptr;
455 container->end = encoder->end;
457 container->added = 0;
459 cbor_static_assert(((MapType << MajorTypeShift) & CborIteratorFlag_ContainerIsMap) == CborIteratorFlag_ContainerIsMap);
460 cbor_static_assert(((ArrayType << MajorTypeShift) & CborIteratorFlag_ContainerIsMap) == 0);
461 container->flags = shiftedMajorType & CborIteratorFlag_ContainerIsMap;
463 if (length == CborIndefiniteLength) {
464 container->flags |= CborIteratorFlag_UnknownLength;
465 err = append_byte_to_buffer(container, shiftedMajorType + IndefiniteLength);
467 err = encode_number_no_update(container, length, shiftedMajorType);
473 * Creates a CBOR array in the CBOR stream provided by \a encoder and
474 * initializes \a arrayEncoder so that items can be added to the array using
475 * the CborEncoder functions. The array must be terminated by calling either
476 * cbor_encoder_close_container() or cbor_encoder_close_container_checked()
477 * with the same \a encoder and \a arrayEncoder parameters.
479 * The number of items inserted into the array must be exactly \a length items,
480 * otherwise the stream is invalid. If the number of items is not known when
481 * creating the array, the constant \ref CborIndefiniteLength may be passed as
484 * \sa cbor_encoder_create_map
486 CborError cbor_encoder_create_array(CborEncoder *encoder, CborEncoder *arrayEncoder, size_t length)
488 return create_container(encoder, arrayEncoder, length, ArrayType << MajorTypeShift);
492 * Creates a CBOR map in the CBOR stream provided by \a encoder and
493 * initializes \a mapEncoder so that items can be added to the map using
494 * the CborEncoder functions. The map must be terminated by calling either
495 * cbor_encoder_close_container() or cbor_encoder_close_container_checked()
496 * with the same \a encoder and \a mapEncoder parameters.
498 * The number of pair of items inserted into the map must be exactly \a length
499 * items, otherwise the stream is invalid. If the number of items is not known
500 * when creating the map, the constant \ref CborIndefiniteLength may be passed as
503 * \b{Implementation limitation:} TinyCBOR cannot encode more than SIZE_MAX/2
504 * key-value pairs in the stream. If the length \a length is larger than this
505 * value, this function returns error CborErrorDataTooLarge.
507 * \sa cbor_encoder_create_array
509 CborError cbor_encoder_create_map(CborEncoder *encoder, CborEncoder *mapEncoder, size_t length)
511 if (length != CborIndefiniteLength && length > SIZE_MAX / 2)
512 return CborErrorDataTooLarge;
513 return create_container(encoder, mapEncoder, length, MapType << MajorTypeShift);
517 * Closes the CBOR container (array or map) provided by \a containerEncoder and
518 * updates the CBOR stream provided by \a encoder. Both parameters must be the
519 * same as were passed to cbor_encoder_create_array() or
520 * cbor_encoder_create_map().
522 * This function does not verify that the number of items (or pair of items, in
523 * the case of a map) was correct. To execute that verification, call
524 * cbor_encoder_close_container_checked() instead.
526 * \sa cbor_encoder_create_array(), cbor_encoder_create_map()
528 CborError cbor_encoder_close_container(CborEncoder *encoder, const CborEncoder *containerEncoder)
531 encoder->ptr = containerEncoder->ptr;
533 encoder->bytes_needed = containerEncoder->bytes_needed;
534 encoder->end = containerEncoder->end;
535 if (containerEncoder->flags & CborIteratorFlag_UnknownLength)
536 return append_byte_to_buffer(encoder, BreakByte);
541 * \fn CborError cbor_encode_boolean(CborEncoder *encoder, bool value)
543 * Appends the boolean value \a value to the CBOR stream provided by \a encoder.
547 * \fn CborError cbor_encode_null(CborEncoder *encoder)
549 * Appends the CBOR type representing a null value to the CBOR stream provided
552 * \sa cbor_encode_undefined()
556 * \fn CborError cbor_encode_undefined(CborEncoder *encoder)
558 * Appends the CBOR type representing an undefined value to the CBOR stream
559 * provided by \a encoder.
561 * \sa cbor_encode_null()
565 * \fn CborError cbor_encode_half_float(CborEncoder *encoder, const void *value)
567 * Appends the IEEE 754 half-precision (16-bit) floating point value pointed to
568 * by \a value to the CBOR stream provided by \a encoder.
570 * \sa cbor_encode_floating_point(), cbor_encode_float(), cbor_encode_double()
574 * \fn CborError cbor_encode_float(CborEncoder *encoder, float value)
576 * Appends the IEEE 754 single-precision (32-bit) floating point value \a value
577 * to the CBOR stream provided by \a encoder.
579 * \sa cbor_encode_floating_point(), cbor_encode_half_float(), cbor_encode_double()
583 * \fn CborError cbor_encode_double(CborEncoder *encoder, double value)
585 * Appends the IEEE 754 double-precision (64-bit) floating point value \a value
586 * to the CBOR stream provided by \a encoder.
588 * \sa cbor_encode_floating_point(), cbor_encode_half_float(), cbor_encode_float()
592 * \fn size_t cbor_encoder_get_buffer_size(const CborEncoder *encoder, const uint8_t *buffer)
594 * Returns the total size of the buffer starting at \a buffer after the
595 * encoding finished without errors. The \a encoder and \a buffer arguments
596 * must be the same as supplied to cbor_encoder_init().
598 * If the encoding process had errors, the return value of this function is
599 * meaningless. If the only errors were CborErrorOutOfMemory, instead use
600 * cbor_encoder_get_extra_bytes_needed() to find out by how much to grow the
601 * buffer before encoding again.
603 * See \ref CborEncoding for an example of using this function.
605 * \sa cbor_encoder_init(), cbor_encoder_get_extra_bytes_needed(), CborEncoding
609 * \fn size_t cbor_encoder_get_extra_bytes_needed(const CborEncoder *encoder)
611 * Returns how many more bytes the original buffer supplied to
612 * cbor_encoder_init() needs to be extended by so that no CborErrorOutOfMemory
613 * condition will happen for the encoding. If the buffer was big enough, this
614 * function returns 0. The \a encoder must be the original argument as passed
615 * to cbor_encoder_init().
617 * This function is usually called after an encoding sequence ended with one or
618 * more CborErrorOutOfMemory errors, but no other error. If any other error
619 * happened, the return value of this function is meaningless.
621 * See \ref CborEncoding for an example of using this function.
623 * \sa cbor_encoder_init(), cbor_encoder_get_buffer_size(), CborEncoding