Public interface comment and function formatting improvements
All documentation comments are now /* */ and have a leading *.
All public functions have the type returned on one line and the function name on a new line.
All header files have less than 2% lines longer than 80 columns, no trailing spaces or tabs.
There is no behavior change at all in this PR, even though it is pretty large.
* Comment formatting improvements
* More comment formatting
* More comment formatting
* more comment improvements
* uniform formatting for function declarations
* More function and comment formatting
---------
Co-authored-by: Laurence Lundblade <lgl@securitytheory.com>
diff --git a/inc/qcbor/UsefulBuf.h b/inc/qcbor/UsefulBuf.h
index aa24507..5f53044 100644
--- a/inc/qcbor/UsefulBuf.h
+++ b/inc/qcbor/UsefulBuf.h
@@ -1,34 +1,35 @@
-/*============================================================================
- Copyright (c) 2016-2018, The Linux Foundation.
- Copyright (c) 2018-2022, Laurence Lundblade.
- Copyright (c) 2021, Arm Limited. All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above
- copyright notice, this list of conditions and the following
- disclaimer in the documentation and/or other materials provided
- with the distribution.
- * Neither the name of The Linux Foundation nor the names of its
- contributors, nor the name "Laurence Lundblade" may be used to
- endorse or promote products derived from this software without
- specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
-WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
-ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
-BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
-BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
-WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
-IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- =============================================================================*/
+/* =========================================================================
+ * Copyright (c) 2016-2018, The Linux Foundation.
+ * Copyright (c) 2018-2022, Laurence Lundblade.
+ * Copyright (c) 2021, Arm Limited. All rights reserved.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following
+ * disclaimer in the documentation and/or other materials provided
+ * with the distribution.
+ * * Neither the name of The Linux Foundation nor the names of its
+ * contributors, nor the name "Laurence Lundblade" may be used to
+ * endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+ * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+ * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+ * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
+ * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ * ========================================================================= */
/*============================================================================
FILE: UsefulBuf.h
@@ -674,7 +675,7 @@
{
UsefulBuf UB;
- // See UsefulBuf_Unconst() implementation for comment
+ /* See UsefulBuf_Unconst() implementation for comment */
UB.ptr = (void *)(uintptr_t)UBC.ptr;
UB.len = UBC.len;
@@ -1844,7 +1845,7 @@
return SIZE_MAX;
}
- // Cast to size_t (from ptrdiff_t) is OK because of check above
+ /* Cast to size_t (from ptrdiff_t) is OK because of check above */
const size_t uOffset = (size_t)((const uint8_t *)p - (const uint8_t *)UB.ptr);
if(uOffset >= UB.len) {
diff --git a/inc/qcbor/qcbor_decode.h b/inc/qcbor/qcbor_decode.h
index bf30e6d..c75c923 100644
--- a/inc/qcbor/qcbor_decode.h
+++ b/inc/qcbor/qcbor_decode.h
@@ -1,35 +1,35 @@
-/*==============================================================================
- Copyright (c) 2016-2018, The Linux Foundation.
- Copyright (c) 2018-2022, Laurence Lundblade.
- Copyright (c) 2021, Arm Limited.
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions are
- met:
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above
- copyright notice, this list of conditions and the following
- disclaimer in the documentation and/or other materials provided
- with the distribution.
- * Neither the name of The Linux Foundation nor the names of its
- contributors, nor the name "Laurence Lundblade" may be used to
- endorse or promote products derived from this software without
- specific prior written permission.
-
- THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
- WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
- ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
- BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
- SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
- BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
- WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
- OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
- IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- =============================================================================*/
+/* ===========================================================================
+ * Copyright (c) 2016-2018, The Linux Foundation.
+ * Copyright (c) 2018-2023, Laurence Lundblade.
+ * Copyright (c) 2021, Arm Limited.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following
+ * disclaimer in the documentation and/or other materials provided
+ * with the distribution.
+ * * Neither the name of The Linux Foundation nor the names of its
+ * contributors, nor the name "Laurence Lundblade" may be used to
+ * endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+ * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+ * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+ * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
+ * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ * ========================================================================= */
#ifndef qcbor_decode_h
@@ -175,7 +175,7 @@
* Decode functions like QCBORDecode_GetEpochDate() and
* QCBORDecode_GetDecimalFraction() that can decode the tag content
* even if the tag number is absent are still available. Typically
- * they won't be linked in because of dead stripping. The
+ * they won't be linked in because of dead stripping. The
* @c uTagRequirement parameter has no effect, but if it is
* @ref QCBOR_TAG_REQUIREMENT_TAG, @ref QCBOR_ERR_TAGS_DISABLED
* will be set.
@@ -215,11 +215,11 @@
#define QCBOR_TYPE_ANY 1
/** Type for an integer that decoded either between @c INT64_MIN and
- @c INT32_MIN or @c INT32_MAX and @c INT64_MAX. Data is in member
- @c val.int64. */
+ * @c INT32_MIN or @c INT32_MAX and @c INT64_MAX. Data is in member
+ * @c val.int64. */
#define QCBOR_TYPE_INT64 2
/** Type for an integer that decoded to a more than @c INT64_MAX and
- @c UINT64_MAX. Data is in member @c val.uint64. */
+ * @c UINT64_MAX. Data is in member @c val.uint64. */
#define QCBOR_TYPE_UINT64 3
/** Type for an array. See comments on @c val.uCount. */
#define QCBOR_TYPE_ARRAY 4
@@ -228,54 +228,54 @@
/** Type for a buffer full of bytes. Data is in @c val.string. */
#define QCBOR_TYPE_BYTE_STRING 6
/** Type for a UTF-8 string. It is not NULL-terminated. See
- QCBOREncode_AddText() for a discussion of line endings in CBOR. Data
- is in @c val.string. */
+ * QCBOREncode_AddText() for a discussion of line endings in CBOR. Data
+ * is in @c val.string. */
#define QCBOR_TYPE_TEXT_STRING 7
/** Type for a positive big number. Data is in @c val.bignum, a
- pointer and a length. */
+ * pointer and a length. */
#define QCBOR_TYPE_POSBIGNUM 9
/** Type for a negative big number. Data is in @c val.bignum, a
- pointer and a length. */
+ * pointer and a length. */
#define QCBOR_TYPE_NEGBIGNUM 10
/** Type for [RFC 3339] (https://tools.ietf.org/html/rfc3339) date
- string, possibly with time zone. Data is in @c val.string . Note this
- was previously in @c val.dateString, however this is the same as
- val.string being the same type in same union. */
+ * string, possibly with time zone. Data is in @c val.string . Note this
+ * was previously in @c val.dateString, however this is the same as
+ * val.string being the same type in same union. */
#define QCBOR_TYPE_DATE_STRING 11
/** Type for integer seconds since Jan 1970 + floating-point
- fraction. Data is in @c val.epochDate */
+ * fraction. Data is in @c val.epochDate */
#define QCBOR_TYPE_DATE_EPOCH 12
/** A simple type that this CBOR implementation doesn't know about;
- Type is in @c val.uSimple. */
+ * Type is in @c val.uSimple. */
#define QCBOR_TYPE_UKNOWN_SIMPLE 13
/** A decimal fraction made of decimal exponent and integer mantissa.
- See @ref expAndMantissa and QCBOREncode_AddDecimalFraction(). */
+ * See @ref expAndMantissa and QCBOREncode_AddDecimalFraction(). */
#define QCBOR_TYPE_DECIMAL_FRACTION 14
/** A decimal fraction made of decimal exponent and positive big
- number mantissa. See @ref expAndMantissa and
- QCBOREncode_AddDecimalFractionBigNum(). */
+ * number mantissa. See @ref expAndMantissa and
+ * QCBOREncode_AddDecimalFractionBigNum(). */
#define QCBOR_TYPE_DECIMAL_FRACTION_POS_BIGNUM 15
/** A decimal fraction made of decimal exponent and negative big
- number mantissa. See @ref expAndMantissa and
- QCBOREncode_AddDecimalFractionBigNum(). */
+ * number mantissa. See @ref expAndMantissa and
+ * QCBOREncode_AddDecimalFractionBigNum(). */
#define QCBOR_TYPE_DECIMAL_FRACTION_NEG_BIGNUM 16
/** A floating-point number made of base-2 exponent and integer
- mantissa. See @ref expAndMantissa and
- QCBOREncode_AddBigFloat(). */
+ * mantissa. See @ref expAndMantissa and
+ * QCBOREncode_AddBigFloat(). */
#define QCBOR_TYPE_BIGFLOAT 17
/** A floating-point number made of base-2 exponent and positive big
- number mantissa. See @ref expAndMantissa and
- QCBOREncode_AddBigFloatBigNum(). */
+ * number mantissa. See @ref expAndMantissa and
+ * QCBOREncode_AddBigFloatBigNum(). */
#define QCBOR_TYPE_BIGFLOAT_POS_BIGNUM 18
/** A floating-point number made of base-2 exponent and negative big
- number mantissa. See @ref expAndMantissa and
- QCBOREncode_AddBigFloatBigNum(). */
+ * number mantissa. See @ref expAndMantissa and
+ * QCBOREncode_AddBigFloatBigNum(). */
#define QCBOR_TYPE_BIGFLOAT_NEG_BIGNUM 19
/** Type for the value false. */
@@ -294,51 +294,51 @@
#define QCBOR_TYPE_BREAK 31 /* Used internally; never returned */
/** For @ref QCBOR_DECODE_MODE_MAP_AS_ARRAY decode mode, a map that is
- being traversed as an array. See QCBORDecode_Init() */
+ * being traversed as an array. See QCBORDecode_Init() */
#define QCBOR_TYPE_MAP_AS_ARRAY 32
/** Encoded CBOR that is wrapped in a byte string. Often used when the
- CBOR is to be hashed for signing or HMAC. See also @ref
- QBCOR_TYPE_WRAPPED_CBOR_SEQUENCE. Data is in @c val.string. */
+ * CBOR is to be hashed for signing or HMAC. See also @ref
+ * QBCOR_TYPE_WRAPPED_CBOR_SEQUENCE. Data is in @c val.string. */
#define QBCOR_TYPE_WRAPPED_CBOR 36
/** A URI as defined in RFC 3986. Data is in @c val.string. */
#define QCBOR_TYPE_URI 44
/** Text is base64 URL encoded in RFC 4648. The base64 encoding is
- NOT removed. Data is in @c val.string. */
+ * NOT removed. Data is in @c val.string. */
#define QCBOR_TYPE_BASE64URL 45
/** Text is base64 encoded in RFC 4648. The base64 encoding is NOT
- removed. Data is in @c val.string. */
+ * removed. Data is in @c val.string. */
#define QCBOR_TYPE_BASE64 46
/** PERL-compatible regular expression. Data is in @c val.string. */
#define QCBOR_TYPE_REGEX 47
/** Non-binary MIME per RFC 2045. See also @ref
- QCBOR_TYPE_BINARY_MIME. Data is in @c val.string. */
+ * QCBOR_TYPE_BINARY_MIME. Data is in @c val.string. */
#define QCBOR_TYPE_MIME 48
/** Binary UUID per RFC 4122. Data is in @c val.string. */
#define QCBOR_TYPE_UUID 49
/** A CBOR sequence per RFC 8742. See also @ ref
- QBCOR_TYPE_WRAPPED_CBOR. Data is in @c val.string. */
+ * QBCOR_TYPE_WRAPPED_CBOR. Data is in @c val.string. */
#define QBCOR_TYPE_WRAPPED_CBOR_SEQUENCE 75
/** Binary MIME per RFC 2045. See also @ref QCBOR_TYPE_MIME. Data is
- in @c val.string. */
+ * in @c val.string. */
#define QCBOR_TYPE_BINARY_MIME 76
/** Type for [RFC 8943](https://tools.ietf.org/html/rfc8943) date
- string, a date with no time or time zone info. Data is in
- @c val.string */
+ * string, a date with no time or time zone info. Data is in
+ * @c val.string */
#define QCBOR_TYPE_DAYS_STRING 77
/** Type for integer days since Jan 1 1970 described in
- [RFC 8943](https://tools.ietf.org/html/rfc8943). Data is in
- @c val.epochDays */
+ * [RFC 8943](https://tools.ietf.org/html/rfc8943). Data is in
+ * @c val.epochDays */
#define QCBOR_TYPE_DAYS_EPOCH 78
#define QCBOR_TYPE_TAG 254 /* Used internally; never returned */
@@ -590,7 +590,9 @@
* strings will have to free them. How they free them, depends on the
* design of the string allocator.
*/
-typedef UsefulBuf (* QCBORStringAllocate)(void *pAllocateCxt, void *pOldMem, size_t uNewSize);
+typedef UsefulBuf (* QCBORStringAllocate)(void *pAllocateCxt,
+ void *pOldMem,
+ size_t uNewSize);
/**
@@ -654,7 +656,8 @@
* that are not integers or text strings, but the caller must manage
* much of the map decoding.
*/
-void QCBORDecode_Init(QCBORDecodeContext *pCtx, UsefulBufC EncodedCBOR, QCBORDecodeMode nMode);
+void
+QCBORDecode_Init(QCBORDecodeContext *pCtx, UsefulBufC EncodedCBOR, QCBORDecodeMode nMode);
/**
@@ -703,7 +706,10 @@
* See also QCBORDecode_SetUpAllocator() to set up a custom allocator
* if this one isn't sufficient.
*/
-QCBORError QCBORDecode_SetMemPool(QCBORDecodeContext *pCtx, UsefulBuf MemPool, bool bAllStrings);
+QCBORError
+QCBORDecode_SetMemPool(QCBORDecodeContext *pCtx,
+ UsefulBuf MemPool,
+ bool bAllStrings);
/**
@@ -739,10 +745,11 @@
* @c uLabelAlloc @c == @c 1 in @ref QCBORItem. Note this is in a
* separate GitHub repository.
*/
-void QCBORDecode_SetUpAllocator(QCBORDecodeContext *pCtx,
- QCBORStringAllocate pfAllocateFunction,
- void *pAllocateContext,
- bool bAllStrings);
+void
+QCBORDecode_SetUpAllocator(QCBORDecodeContext *pCtx,
+ QCBORStringAllocate pfAllocateFunction,
+ void *pAllocateContext,
+ bool bAllStrings);
/**
@@ -905,7 +912,7 @@
* | __Invalid CBOR__ ||
* | @ref QCBOR_ERR_NO_MORE_ITEMS | Need more input data items to decode |
* | @ref QCBOR_ERR_BAD_EXP_AND_MANTISSA | The structure of a big float or big number is invalid |
- * | @ref QCBOR_ERR_BAD_TAG_CONTENT | The content of a tag is of the wrong type |
+ * | @ref QCBOR_ERR_UNRECOVERABLE_TAG_CONTENT | The content of a tag is of the wrong type |
* | __Implementation Limits__ ||
* | @ref QCBOR_ERR_INT_OVERFLOW | Input integer smaller than INT64_MIN |
* | @ref QCBOR_ERR_ARRAY_DECODE_TOO_LONG | Array or map has more elements than can be handled |
@@ -916,14 +923,15 @@
* | __Configuration errors__ ||
* | @ref QCBOR_ERR_NO_STRING_ALLOCATOR | Encountered indefinite-length string with no allocator configured |
* | @ref QCBOR_ERR_MAP_LABEL_TYPE | A map label that is not a string on an integer |
- * | @ref QCBOR_ERR_HALF_PRECISION_DISABLED | Library compiled with half-precision disabled and half-precision input encountered |
- * | @ref QCBOR_ERR_INDEF_LEN_ARRAYS_DISABLED | Library compiled with indefinite maps and arrays disabled and indefinite map or array encountered |
- * | @ref QCBOR_ERR_INDEF_LEN_STRINGS_DISABLED | Library compiled with indefinite strings disabled and indefinite string encountered |
+ * | @ref QCBOR_ERR_HALF_PRECISION_DISABLED | Half-precision input, but disabled in QCBOR library |
+ * | @ref QCBOR_ERR_INDEF_LEN_ARRAYS_DISABLED | Indefinite-length input, but disabled in QCBOR library |
+ * | @ref QCBOR_ERR_INDEF_LEN_STRINGS_DISABLED | Indefinite-length input, but disabled in QCBOR library |
* | @ref QCBOR_ERR_ALL_FLOAT_DISABLED | Library compiled with floating-point support turned off. |
* | __Resource exhaustion errors__ ||
* | @ref QCBOR_ERR_STRING_ALLOCATE | The string allocator is unable to allocate more memory |
*/
-void QCBORDecode_VGetNext(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
+void
+QCBORDecode_VGetNext(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
/**
@@ -939,7 +947,8 @@
* doesn't set the internal decoding error and will attempt to decode
* even if the decoder is in the error state.
*/
-QCBORError QCBORDecode_GetNext(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
+QCBORError
+QCBORDecode_GetNext(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
/**
@@ -955,7 +964,8 @@
* consumed by this, the decoder must be rewound using
* QCBORDecode_Rewind().
*/
-void QCBORDecode_VGetNextConsume(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
+void
+QCBORDecode_VGetNextConsume(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
/**
@@ -1033,7 +1043,8 @@
* getting the item. This is also returned if there are no tags on the
* item or no tag at @c uIndex.
*/
-uint64_t QCBORDecode_GetNthTag(QCBORDecodeContext *pCtx, const QCBORItem *pItem, uint32_t uIndex);
+uint64_t
+QCBORDecode_GetNthTag(QCBORDecodeContext *pCtx, const QCBORItem *pItem, uint32_t uIndex);
/**
@@ -1051,7 +1062,8 @@
*
* If a decoding error set then this returns CBOR_TAG_INVALID64.
*/
-uint64_t QCBORDecode_GetNthTagOfLast(const QCBORDecodeContext *pCtx, uint32_t uIndex);
+uint64_t
+QCBORDecode_GetNthTagOfLast(const QCBORDecodeContext *pCtx, uint32_t uIndex);
/**
@@ -1092,7 +1104,8 @@
* QCBOR_ERR_EXTRA_BYTES will be returned. This can be considered a
* successful decode. See also QCBORDecode_PartialFinish().
*/
-QCBORError QCBORDecode_Finish(QCBORDecodeContext *pCtx);
+QCBORError
+QCBORDecode_Finish(QCBORDecodeContext *pCtx);
/**
@@ -1151,7 +1164,8 @@
* QCBORDecode_GetAndResetError() may be called after these data items
* are fetched.
*/
-static QCBORError QCBORDecode_GetError(QCBORDecodeContext *pCtx);
+static QCBORError
+QCBORDecode_GetError(QCBORDecodeContext *pCtx);
/**
@@ -1163,7 +1177,8 @@
* This returns the same as QCBORDecode_GetError() and also resets the
* error state to @ref QCBOR_SUCCESS.
*/
-static QCBORError QCBORDecode_GetAndResetError(QCBORDecodeContext *pCtx);
+static QCBORError
+QCBORDecode_GetAndResetError(QCBORDecodeContext *pCtx);
/**
@@ -1172,7 +1187,8 @@
* @param[in] uErr The decoder context.
* @return @c true if the error code indicates non-well-formed CBOR.
*/
-static bool QCBORDecode_IsNotWellFormedError(QCBORError uErr);
+static bool
+QCBORDecode_IsNotWellFormedError(QCBORError uErr);
/**
@@ -1194,55 +1210,57 @@
* The unrecoverable errors are a range of the errors in
* @ref QCBORError.
*/
-static bool QCBORDecode_IsUnrecoverableError(QCBORError uErr);
+static bool
+QCBORDecode_IsUnrecoverableError(QCBORError uErr);
/**
- @brief Convert int64_t to smaller integers safely.
-
- @param [in] src An @c int64_t.
- @param [out] dest A smaller sized integer to convert to.
-
- @return 0 on success -1 if not
-
- When decoding an integer, the CBOR decoder will return the value as
- an int64_t unless the integer is in the range of @c INT64_MAX and @c
- UINT64_MAX. That is, unless the value is so large that it can only be
- represented as a @c uint64_t, it will be an @c int64_t.
-
- CBOR itself doesn't size the individual integers it carries at
- all. The only limits it puts on the major integer types is that they
- are 8 bytes or less in length. Then encoders like this one use the
- smallest number of 1, 2, 4 or 8 bytes to represent the integer based
- on its value. There is thus no notion that one data item in CBOR is
- a 1-byte integer and another is a 4-byte integer.
-
- The interface to this CBOR encoder only uses 64-bit integers. Some
- CBOR protocols or implementations of CBOR protocols may not want to
- work with something smaller than a 64-bit integer. Perhaps an array
- of 1000 integers needs to be sent and none has a value larger than
- 50,000 and are represented as @c uint16_t.
-
- The sending / encoding side is easy. Integers are temporarily widened
- to 64-bits as a parameter passing through QCBOREncode_AddInt64() and
- encoded in the smallest way possible for their value, possibly in
- less than an @c uint16_t.
-
- On the decoding side the integers will be returned at @c int64_t even if
- they are small and were represented by only 1 or 2 bytes in the
- encoded CBOR. The functions here will convert integers to a small
- representation with an overflow check.
-
- (The decoder could have support 8 different integer types and
- represented the integer with the smallest type automatically, but
- this would have made the decoder more complex and code calling the
- decoder more complex in most use cases. In most use cases on 64-bit
- machines it is no burden to carry around even small integers as
- 64-bit values).
+ * @brief Convert int64_t to smaller integers safely.
+ *
+ * @param [in] src An @c int64_t.
+ * @param [out] dest A smaller sized integer to convert to.
+ *
+ * @return 0 on success -1 if not
+ *
+ * When decoding an integer, the CBOR decoder will return the value as
+ * an int64_t unless the integer is in the range of @c INT64_MAX and @c
+ * UINT64_MAX. That is, unless the value is so large that it can only be
+ * represented as a @c uint64_t, it will be an @c int64_t.
+ *
+ * CBOR itself doesn't size the individual integers it carries at
+ * all. The only limits it puts on the major integer types is that they
+ * are 8 bytes or less in length. Then encoders like this one use the
+ * smallest number of 1, 2, 4 or 8 bytes to represent the integer based
+ * on its value. There is thus no notion that one data item in CBOR is
+ * a 1-byte integer and another is a 4-byte integer.
+ *
+ * The interface to this CBOR encoder only uses 64-bit integers. Some
+ * CBOR protocols or implementations of CBOR protocols may not want to
+ * work with something smaller than a 64-bit integer. Perhaps an array
+ * of 1,000 integers needs to be sent and none has a value larger than
+ * 50,000 and are represented as @c uint16_t.
+ *
+ * The sending / encoding side is easy. Integers are temporarily widened
+ * to 64-bits as a parameter passing through QCBOREncode_AddInt64() and
+ * encoded in the smallest way possible for their value, possibly in
+ * less than an @c uint16_t.
+ *
+ * On the decoding side the integers will be returned at @c int64_t even if
+ * they are small and were represented by only 1 or 2 bytes in the
+ * encoded CBOR. The functions here will convert integers to a small
+ * representation with an overflow check.
+ *
+ * (The decoder could have support 8 different integer types and
+ * represented the integer with the smallest type automatically, but
+ * this would have made the decoder more complex and code calling the
+ * decoder more complex in most use cases. In most use cases on 64-bit
+ * machines it is no burden to carry around even small integers as
+ * 64-bit values).
*/
-static inline int QCBOR_Int64ToInt32(int64_t src, int32_t *dest)
+static inline int
+QCBOR_Int64ToInt32(int64_t src, int32_t *dest)
{
if(src > INT32_MAX || src < INT32_MIN) {
return -1;
@@ -1252,7 +1270,8 @@
return 0;
}
-static inline int QCBOR_Int64ToInt16(int64_t src, int16_t *dest)
+static inline int
+QCBOR_Int64ToInt16(int64_t src, int16_t *dest)
{
if(src > INT16_MAX || src < INT16_MIN) {
return -1;
@@ -1262,7 +1281,8 @@
return 0;
}
-static inline int QCBOR_Int64ToInt8(int64_t src, int8_t *dest)
+static inline int
+QCBOR_Int64ToInt8(int64_t src, int8_t *dest)
{
if(src > INT8_MAX || src < INT8_MIN) {
return -1;
@@ -1272,7 +1292,8 @@
return 0;
}
-static inline int QCBOR_Int64ToUInt32(int64_t src, uint32_t *dest)
+static inline int
+QCBOR_Int64ToUInt32(int64_t src, uint32_t *dest)
{
if(src > UINT32_MAX || src < 0) {
return -1;
@@ -1282,7 +1303,8 @@
return 0;
}
-static inline int QCBOR_Int64UToInt16(int64_t src, uint16_t *dest)
+static inline int
+QCBOR_Int64UToInt16(int64_t src, uint16_t *dest)
{
if(src > UINT16_MAX || src < 0) {
return -1;
@@ -1292,7 +1314,8 @@
return 0;
}
-static inline int QCBOR_Int64ToUInt8(int64_t src, uint8_t *dest)
+static inline int
+QCBOR_Int64ToUInt8(int64_t src, uint8_t *dest)
{
if(src > UINT8_MAX || src < 0) {
return -1;
@@ -1302,7 +1325,8 @@
return 0;
}
-static inline int QCBOR_Int64ToUInt64(int64_t src, uint64_t *dest)
+static inline int
+QCBOR_Int64ToUInt64(int64_t src, uint64_t *dest)
{
if(src < 0) {
return -1;
@@ -1360,7 +1384,9 @@
* Tag handling has been revised and it is no longer ncessary to use
* this. See QCBORDecode_GetNthTag().
*/
-void QCBORDecode_SetCallerConfiguredTagList(QCBORDecodeContext *pCtx, const QCBORTagListIn *pTagList);
+void
+QCBORDecode_SetCallerConfiguredTagList(QCBORDecodeContext *pCtx,
+ const QCBORTagListIn *pTagList);
/**
@@ -1388,7 +1414,10 @@
* add new tags to the internal list so they can be checked for with
* this function.
*/
-bool QCBORDecode_IsTagged(QCBORDecodeContext *pCtx, const QCBORItem *pItem, uint64_t uTag);
+bool
+QCBORDecode_IsTagged(QCBORDecodeContext *pCtx,
+ const QCBORItem *pItem,
+ uint64_t uTag);
/**
@@ -1425,7 +1454,10 @@
* QCBOR_ERR_TOO_MANY_TAGS if the array in @c pTagList is too small to
* hold all the tags for the item.
*/
-QCBORError QCBORDecode_GetNextWithTags(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem, QCBORTagListOut *pTagList);
+QCBORError
+QCBORDecode_GetNextWithTags(QCBORDecodeContext *pCtx,
+ QCBORItem *pDecodedItem,
+ QCBORTagListOut *pTagList);
@@ -1434,19 +1466,22 @@
* Inline implementations of public functions defined above.
* ---- */
-static inline QCBORError QCBORDecode_GetError(QCBORDecodeContext *pMe)
+static inline QCBORError
+QCBORDecode_GetError(QCBORDecodeContext *pMe)
{
return (QCBORError)pMe->uLastError;
}
-static inline QCBORError QCBORDecode_GetAndResetError(QCBORDecodeContext *pMe)
+static inline QCBORError
+QCBORDecode_GetAndResetError(QCBORDecodeContext *pMe)
{
const QCBORError uReturn = (QCBORError)pMe->uLastError;
pMe->uLastError = QCBOR_SUCCESS;
return uReturn;
}
-static inline bool QCBORDecode_IsNotWellFormedError(QCBORError uErr)
+static inline bool
+QCBORDecode_IsNotWellFormedError(QCBORError uErr)
{
if(uErr >= QCBOR_START_OF_NOT_WELL_FORMED_ERRORS &&
uErr <= QCBOR_END_OF_NOT_WELL_FORMED_ERRORS) {
@@ -1456,7 +1491,8 @@
}
}
-static inline bool QCBORDecode_IsUnrecoverableError(QCBORError uErr)
+static inline bool
+QCBORDecode_IsUnrecoverableError(QCBORError uErr)
{
if(uErr >= QCBOR_START_OF_UNRECOVERABLE_DECODE_ERRORS &&
uErr <= QCBOR_END_OF_UNRECOVERABLE_DECODE_ERRORS) {
diff --git a/inc/qcbor/qcbor_encode.h b/inc/qcbor/qcbor_encode.h
index a5aba47..38bfcc1 100644
--- a/inc/qcbor/qcbor_encode.h
+++ b/inc/qcbor/qcbor_encode.h
@@ -1,35 +1,35 @@
-/*==============================================================================
- Copyright (c) 2016-2018, The Linux Foundation.
- Copyright (c) 2018-2023, Laurence Lundblade.
- Copyright (c) 2021, Arm Limited.
- All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above
- copyright notice, this list of conditions and the following
- disclaimer in the documentation and/or other materials provided
- with the distribution.
- * Neither the name of The Linux Foundation nor the names of its
- contributors, nor the name "Laurence Lundblade" may be used to
- endorse or promote products derived from this software without
- specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
-WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
-ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
-BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
-BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
-WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
-IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- =============================================================================*/
+/* ===========================================================================
+ * Copyright (c) 2016-2018, The Linux Foundation.
+ * Copyright (c) 2018-2023, Laurence Lundblade.
+ * Copyright (c) 2021, Arm Limited.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ * * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following
+ * disclaimer in the documentation and/or other materials provided
+ * with the distribution.
+ * * Neither the name of The Linux Foundation nor the names of its
+ * contributors, nor the name "Laurence Lundblade" may be used to
+ * endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+ * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+ * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+ * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
+ * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ * ========================================================================= */
#ifndef qcbor_encode_h
@@ -50,1514 +50,1663 @@
/**
- @file qcbor_encode.h
-
- @anchor Overview
-
- # QCBOR Overview
-
- This implements CBOR -- Concise Binary Object Representation as
- defined in [RFC 8949] (https://tools.ietf.org/html/rfc8949). More
- information is at http://cbor.io. This is a near-complete implementation of
- the specification. [RFC 8742] (https://tools.ietf.org/html/rfc8742) CBOR
- Sequences is also supported. Limitations are listed further down.
-
- See @ref Encoding for general discussion on encoding,
- @ref BasicDecode for general discussion on the basic decode features
- and @ref SpiffyDecode for general discussion on the easier-to-use
- decoder functions.
-
- CBOR is intentionally designed to be translatable to JSON, but not
- all CBOR can convert to JSON. See RFC 8949 for more info on how to
- construct CBOR that is the most JSON friendly.
-
- The memory model for encoding and decoding is that encoded CBOR must
- be in a contiguous buffer in memory. During encoding the caller must
- supply an output buffer and if the encoding would go off the end of
- the buffer an error is returned. During decoding the caller supplies
- the encoded CBOR in a contiguous buffer and the decoder returns
- pointers and lengths into that buffer for strings.
-
- This implementation does not require malloc. All data structures
- passed in/out of the APIs can fit on the stack.
-
- Decoding of indefinite-length strings is a special case that requires
- a "string allocator" to allocate memory into which the segments of
- the string are coalesced. Without this, decoding will error out if an
- indefinite-length string is encountered (indefinite-length maps and
- arrays do not require the string allocator). A simple string
- allocator called MemPool is built-in and will work if supplied with a
- block of memory to allocate. The string allocator can optionally use
- malloc() or some other custom scheme.
-
- Here are some terms and definitions:
-
- - "Item", "Data Item": An integer or string or such. The basic "thing" that
- CBOR is about. An array is an item itself that contains some items.
-
- - "Array": An ordered sequence of items, the same as JSON.
-
- - "Map": A collection of label/value pairs. Each pair is a data
- item. A JSON "object" is the same as a CBOR "map".
-
- - "Label": The data item in a pair in a map that names or identifies
- the pair, not the value. This implementation refers to it as a
- "label". JSON refers to it as the "name". The CBOR RFC refers to it
- this as a "key". This implementation chooses label instead because
- key is too easily confused with a cryptographic key. The COSE
- standard, which uses CBOR, has also chosen to use the term "label"
- rather than "key" for this same reason.
-
- - "Key": See "Label" above.
-
- - "Tag": A data item that is an explicitly labeled new data
- type made up of the tagging integer and the tag content.
- See @ref Tags-Overview and @ref Tag-Usage.
-
- - "Initial Byte": The first byte of an encoded item. Encoding and
- decoding of this byte is taken care of by the implementation.
-
- - "Additional Info": In addition to the major type, all data items
- have some other info. This is usually the length of the data but can
- be several other things. Encoding and decoding of this is taken care
- of by the implementation.
-
- CBOR has two mechanisms for tagging and labeling the data values like
- integers and strings. For example, an integer that represents
- someone's birthday in epoch seconds since Jan 1, 1970 could be
- encoded like this:
-
- - First it is CBOR_MAJOR_TYPE_POSITIVE_INT (@ref QCBOR_TYPE_INT64),
- the primitive positive integer.
-
- - Next it has a "tag" @ref CBOR_TAG_DATE_EPOCH indicating the integer
- represents a date in the form of the number of seconds since Jan 1,
- 1970.
-
- - Last it has a string "label" like "BirthDate" indicating the
- meaning of the data.
-
- The encoded binary looks like this:
-
- a1 # Map of 1 item
- 69 # Indicates text string of 9 bytes
- 426972746844617465 # The text "BirthDate"
- c1 # Tags next integer as epoch date
- 1a # Indicates a 4-byte integer
- 580d4172 # unsigned integer date 1477263730
-
- Implementors using this API will primarily work with
- labels. Generally, tags are only needed for making up new data
- types. This implementation covers most of the data types defined in
- the RFC using tags. It also, allows for the use of custom tags if
- necessary.
-
- This implementation explicitly supports labels that are text strings
- and integers. Text strings translate nicely into JSON objects and are
- very readable. Integer labels are much less readable but can be very
- compact. If they are in the range of 0 to 23, they take up only one
- byte.
-
- CBOR allows a label to be any type of data including an array or a
- map. It is possible to use this API to construct and parse such
- labels, but it is not explicitly supported.
-
- @anchor Encoding
-
- ## Encoding
-
- A common encoding usage mode is to invoke the encoding twice. First
- with the output buffer as @ref SizeCalculateUsefulBuf to compute the
- length of the needed output buffer. The correct sized output buffer
- is allocated. The encoder is invoked a second time with the allocated
- output buffer.
-
- The double invocation is not required if the maximum output buffer
- size can be predicted. This is usually possible for simple CBOR
- structures.
-
- If a buffer too small to hold the encoded output is given, the error
- @ref QCBOR_ERR_BUFFER_TOO_SMALL will be returned. Data will never be
- written off the end of the output buffer no matter which functions
- here are called or what parameters are passed to them.
-
- The encoding error handling is simple. The only possible errors are
- trying to encode structures that are too large or too complex. There
- are no internal malloc calls so there will be no failures for out of
- memory. The error state is tracked internally, so there is no need
- to check for errors when encoding. Only the return code from
- QCBOREncode_Finish() need be checked as once an error happens, the
- encoder goes into an error state and calls to it to add more data
- will do nothing. An error check is not needed after every data item
- is added.
-
- Encoding generally proceeds by calling QCBOREncode_Init(), calling
- lots of @c QCBOREncode_AddXxx() functions and calling
- QCBOREncode_Finish(). There are many @c QCBOREncode_AddXxx()
- functions for various data types. The input buffers need only to be
- valid during the @c QCBOREncode_AddXxx() calls as the data is copied
- into the output buffer.
-
- There are three `Add` functions for each data type. The first / main
- one for the type is for adding the data item to an array. The second
- one's name ends in `ToMap`, is used for adding data items to maps and
- takes a string argument that is its label in the map. The third one
- ends in `ToMapN`, is also used for adding data items to maps, and
- takes an integer argument that is its label in the map.
-
- The simplest aggregate type is an array, which is a simple ordered
- set of items without labels the same as JSON arrays. Call
- QCBOREncode_OpenArray() to open a new array, then various @c
- QCBOREncode_AddXxx() functions to put items in the array and then
- QCBOREncode_CloseArray(). Nesting to the limit @ref
- QCBOR_MAX_ARRAY_NESTING is allowed. All opens must be matched by
- closes or an encoding error will be returned.
-
- The other aggregate type is a map which does use labels. The `Add`
- functions that end in `ToMap` and `ToMapN` are convenient ways to add
- labeled data items to a map. You can also call any type of `Add`
- function once to add a label of any time and then call any type of
- `Add` again to add its value.
-
- Note that when you nest arrays or maps in a map, the nested array or
- map has a label.
-
- Many CBOR-based protocols start with an array or map. This makes them
- self-delimiting. No external length or end marker is needed to know
- the end. It is also possible not start this way, in which case this
- it is usually called a CBOR sequence which is described in
- [RFC 8742] (https://tools.ietf.org/html/rfc8742). This encoder supports
- either just by whether the first item added is an array, map or other.
-
- If QCBOR is compiled with QCBOR_DISABLE_ENCODE_USAGE_GUARDS defined,
- the errors QCBOR_ERR_CLOSE_MISMATCH, QCBOR_ERR_ARRAY_TOO_LONG,
- QCBOR_ERR_TOO_MANY_CLOSES, QCBOR_ERR_ARRAY_OR_MAP_STILL_OPEN, and
- QCBOR_ERR_ENCODE_UNSUPPORTED will never be returned. It is up to the
- caller to make sure that opened maps, arrays and byte-string wrapping
- is closed correctly and that QCBOREncode_AddType7() is called
- correctly. With this defined, it is easier to make a mistake when
- authoring the encoding of a protocol that will output not well formed
- CBOR, but as long as the calling code is correct, it is safe to
- disable these checks. Bounds checking that prevents security issues
- in the code is still enforced. This define reduces the size of
- encoding object code by about 150 bytes.
-
- @anchor Tags-Overview
-
- ## Tags Overview
-
- Any CBOR data item can be made into a tag to add semantics, define a
- new data type or such. Some tags are fully standardized and some are
- just registered. Others are not registered and used in a proprietary
- way.
-
- Encoding and decoding of many of the registered tags is fully
- implemented by QCBOR. It is also possible to encode and decode tags
- that are not directly supported. For many use cases the built-in tag
- support should be adequate.
-
- For example, the registered epoch date tag is supported in encoding
- by QCBOREncode_AddDateEpoch() and in decoding by @ref
- QCBOR_TYPE_DATE_EPOCH and the @c epochDate member of @ref
- QCBORItem. This is typical of the built-in tag support. There is an
- API to encode data for it and a @c QCBOR_TYPE_XXX when it is decoded.
-
- Tags are registered in the [IANA CBOR Tags Registry]
- (https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml). There
- are roughly three options to create a new tag. First, a public
- specification can be created and the new tag registered with IANA.
- This is the most formal. Second, the new tag can be registered with
- IANA with just a short description rather than a full specification.
- These tags must be greater than 256. Third, a tag can be used without
- any IANA registration, though the registry should be checked to see
- that the new value doesn't collide with one that is registered. The
- value of these tags must be 256 or larger.
-
- See also @ref CBORTags and @ref Tag-Usage
-
- The encoding side of tags not built-in is handled by
- QCBOREncode_AddTag() and is relatively simple. Tag decoding is more
- complex and mainly handled by QCBORDecode_GetNext(). Decoding of the
- structure of tagged data not built-in (if there is any) has to be
- implemented by the caller.
-
- @anchor Floating-Point
-
- ## Floating-Point
-
- By default QCBOR fully supports IEEE 754 floating-point:
- - Encode/decode of double, single and half-precision
- - CBOR preferred serialization of floating-point
- - Floating-point epoch dates
-
- For the most part, the type double is used in the interface for
- floating-point values. In the default configuration, all decoded
- floating-point values are returned as a double.
-
- With CBOR preferred serialization, the encoder outputs the smallest
- representation of the double or float that preserves precision. Zero,
- NaN and infinity are always output as a half-precision, each taking
- just 2 bytes. This reduces the number of bytes needed to encode
- double and single-precision, especially if zero, NaN and infinity are
- frequently used.
-
- To avoid use of preferred serialization in the standard configuration
- when encoding, use QCBOREncode_AddDoubleNoPreferred() or
- QCBOREncode_AddFloatNoPreferred().
-
- This implementation of preferred floating-point serialization and
- half-precision does not depend on the CPU having floating-point HW or
- the compiler bringing in a (sometimes large) library to compensate
- for lack of CPU support. This implementation uses shifts and masks
- rather than floating-point functions.
-
- To reduce overall object code by about 900 bytes, define
- QCBOR_DISABLE_PREFERRED_FLOAT. This will eliminate all support for
- preferred serialization and half-precision. An error will be returned
- when attempting to decode half-precision. A float will always be
- encoded and decoded as 32-bits and a double will always be encoded
- and decoded as 64 bits.
-
- Note that even if QCBOR_DISABLE_PREFERRED_FLOAT is not defined all
- the float-point encoding object code can be avoided by never calling
- any functions that encode double or float. Just not calling
- floating-point functions will reduce object code by about 500 bytes.
-
- On CPUs that have no floating-point hardware,
- QCBOR_DISABLE_FLOAT_HW_USE should be defined in most cases. If it is
- not, then the compiler will bring in possibly large software
- libraries to compensate. Defining QCBOR_DISABLE_FLOAT_HW_USE reduces
- object code size on CPUs with floating-point hardware by a tiny
- amount and eliminates the need for <math.h>
-
- When QCBOR_DISABLE_FLOAT_HW_USE is defined, trying to decoding
- floating-point dates will give error
- @ref QCBOR_ERR_FLOAT_DATE_DISABLED and decoded single-precision
- numbers will be returned as @ref QCBOR_TYPE_FLOAT instead of
- converting them to double as usual.
-
- If both QCBOR_DISABLE_FLOAT_HW_USE and QCBOR_DISABLE_PREFERRED_FLOAT
- are defined, then the only thing QCBOR can do is encode/decode a C
- float type as 32-bits and a C double type as 64-bits. Floating-point
- epoch dates will be unsupported.
-
- If USEFULBUF_DISABLE_ALL_FLOATis defined, then floating point support is
- completely disabled. Decoding functions return @ref QCBOR_ERR_ALL_FLOAT_DISABLED
- if a floating point value is encountered during decoding. Functions that are
- encoding floating point values are not available.
-
- ## Limitations
-
- Summary Limits of this implementation:
- - The entire encoded CBOR must fit into contiguous memory.
- - Max size of encoded / decoded CBOR data is a few bytes less than @c UINT32_MAX (4GB).
- - Max array / map nesting level when encoding / decoding is
- @ref QCBOR_MAX_ARRAY_NESTING (this is typically 15).
- - Max items in an array or map when encoding / decoding is
- @ref QCBOR_MAX_ITEMS_IN_ARRAY (typically 65,536).
- - Does not directly support labels in maps other than text strings & integers.
- - Does not directly support integer labels greater than @c INT64_MAX.
- - Epoch dates limited to @c INT64_MAX (+/- 292 billion years).
- - Exponents for bigfloats and decimal integers are limited to @c INT64_MAX.
- - Tags on labels are ignored during decoding.
- - The maximum tag nesting is @c QCBOR_MAX_TAGS_PER_ITEM (typically 4).
- - Works only on 32- and 64-bit CPUs (modifications could make it work
- on 16-bit CPUs).
-
- The public interface uses @c size_t for all lengths. Internally the
- implementation uses 32-bit lengths by design to use less memory and
- fit structures on the stack. This limits the encoded CBOR it can work
- with to size @c UINT32_MAX (4GB) which should be enough.
-
- This implementation assumes two's compliment integer machines. @c
- <stdint.h> also requires this. It is possible to modify this
- implementation for another integer representation, but all modern
- machines seem to be two's compliment.
+ * @file qcbor_encode.h
+ *
+ * @anchor Overview
+ *
+ * # QCBOR Overview
+ *
+ * This implements CBOR -- Concise Binary Object Representation as
+ * defined in [RFC 8949] (https://tools.ietf.org/html/rfc8949). More
+ * information is at http://cbor.io. This is a near-complete implementation of
+ * the specification. [RFC 8742] (https://tools.ietf.org/html/rfc8742) CBOR
+ * Sequences is also supported. Limitations are listed further down.
+ *
+ * See @ref Encoding for general discussion on encoding,
+ * @ref BasicDecode for general discussion on the basic decode features
+ * and @ref SpiffyDecode for general discussion on the easier-to-use
+ * decoder functions.
+ *
+ * CBOR is intentionally designed to be translatable to JSON, but not
+ * all CBOR can convert to JSON. See RFC 8949 for more info on how to
+ * construct CBOR that is the most JSON friendly.
+ *
+ * The memory model for encoding and decoding is that encoded CBOR must
+ * be in a contiguous buffer in memory. During encoding the caller must
+ * supply an output buffer and if the encoding would go off the end of
+ * the buffer an error is returned. During decoding the caller supplies
+ * the encoded CBOR in a contiguous buffer and the decoder returns
+ * pointers and lengths into that buffer for strings.
+ *
+ * This implementation does not require malloc. All data structures
+ * passed in/out of the APIs can fit on the stack.
+ *
+ * Decoding of indefinite-length strings is a special case that requires
+ * a "string allocator" to allocate memory into which the segments of
+ * the string are coalesced. Without this, decoding will error out if an
+ * indefinite-length string is encountered (indefinite-length maps and
+ * arrays do not require the string allocator). A simple string
+ * allocator called MemPool is built-in and will work if supplied with a
+ * block of memory to allocate. The string allocator can optionally use
+ * malloc() or some other custom scheme.
+ *
+ * Here are some terms and definitions:
+ *
+ * - "Item", "Data Item": An integer or string or such. The basic "thing" that
+ * CBOR is about. An array is an item itself that contains some items.
+ *
+ * - "Array": An ordered sequence of items, the same as JSON.
+ *
+ * - "Map": A collection of label/value pairs. Each pair is a data
+ * item. A JSON "object" is the same as a CBOR "map".
+ *
+ * - "Label": The data item in a pair in a map that names or identifies
+ * the pair, not the value. This implementation refers to it as a
+ * "label". JSON refers to it as the "name". The CBOR RFC refers to it
+ * this as a "key". This implementation chooses label instead because
+ * key is too easily confused with a cryptographic key. The COSE
+ * standard, which uses CBOR, has also chosen to use the term "label"
+ * rather than "key" for this same reason.
+ *
+ * - "Key": See "Label" above.
+ *
+ * - "Tag": A data item that is an explicitly labeled new data
+ * type made up of the tagging integer and the tag content.
+ * See @ref Tags-Overview and @ref Tag-Usage.
+ *
+ * - "Initial Byte": The first byte of an encoded item. Encoding and
+ * decoding of this byte is taken care of by the implementation.
+ *
+ * - "Additional Info": In addition to the major type, all data items
+ * have some other info. This is usually the length of the data but can
+ * be several other things. Encoding and decoding of this is taken care
+ * of by the implementation.
+ *
+ * CBOR has two mechanisms for tagging and labeling the data values like
+ * integers and strings. For example, an integer that represents
+ * someone's birthday in epoch seconds since Jan 1, 1970 could be
+ * encoded like this:
+ *
+ * - First it is CBOR_MAJOR_TYPE_POSITIVE_INT (@ref QCBOR_TYPE_INT64),
+ * the primitive positive integer.
+ *
+ * - Next it has a "tag" @ref CBOR_TAG_DATE_EPOCH indicating the integer
+ * represents a date in the form of the number of seconds since Jan 1,
+ * 1970.
+ *
+ * - Last it has a string "label" like "BirthDate" indicating the
+ * meaning of the data.
+ *
+ * The encoded binary looks like this:
+ *
+ * a1 # Map of 1 item
+ * 69 # Indicates text string of 9 bytes
+ * 426972746844617465 # The text "BirthDate"
+ * c1 # Tags next integer as epoch date
+ * 1a # Indicates a 4-byte integer
+ * 580d4172 # unsigned integer date 1477263730
+ *
+ * Implementors using this API will primarily work with
+ * labels. Generally, tags are only needed for making up new data
+ * types. This implementation covers most of the data types defined in
+ * the RFC using tags. It also, allows for the use of custom tags if
+ * necessary.
+ *
+ * This implementation explicitly supports labels that are text strings
+ * and integers. Text strings translate nicely into JSON objects and are
+ * very readable. Integer labels are much less readable but can be very
+ * compact. If they are in the range of 0 to 23, they take up only one
+ * byte.
+ *
+ * CBOR allows a label to be any type of data including an array or a
+ * map. It is possible to use this API to construct and parse such
+ * labels, but it is not explicitly supported.
+ *
+ * @anchor Encoding
+ *
+ * ## Encoding
+ *
+ * A common encoding usage mode is to invoke the encoding twice. First
+ * with the output buffer as @ref SizeCalculateUsefulBuf to compute the
+ * length of the needed output buffer. The correct sized output buffer
+ * is allocated. The encoder is invoked a second time with the allocated
+ * output buffer.
+ *
+ * The double invocation is not required if the maximum output buffer
+ * size can be predicted. This is usually possible for simple CBOR
+ * structures.
+ *
+ * If a buffer too small to hold the encoded output is given, the error
+ * @ref QCBOR_ERR_BUFFER_TOO_SMALL will be returned. Data will never be
+ * written off the end of the output buffer no matter which functions
+ * here are called or what parameters are passed to them.
+ *
+ * The encoding error handling is simple. The only possible errors are
+ * trying to encode structures that are too large or too complex. There
+ * are no internal malloc calls so there will be no failures for out of
+ * memory. The error state is tracked internally, so there is no need
+ * to check for errors when encoding. Only the return code from
+ * QCBOREncode_Finish() need be checked as once an error happens, the
+ * encoder goes into an error state and calls to it to add more data
+ * will do nothing. An error check is not needed after every data item
+ * is added.
+ *
+ * Encoding generally proceeds by calling QCBOREncode_Init(), calling
+ * lots of @c QCBOREncode_AddXxx() functions and calling
+ * QCBOREncode_Finish(). There are many @c QCBOREncode_AddXxx()
+ * functions for various data types. The input buffers need only to be
+ * valid during the @c QCBOREncode_AddXxx() calls as the data is copied
+ * into the output buffer.
+ *
+ * There are three `Add` functions for each data type. The first / main
+ * one for the type is for adding the data item to an array. The second
+ * one's name ends in `ToMap`, is used for adding data items to maps and
+ * takes a string argument that is its label in the map. The third one
+ * ends in `ToMapN`, is also used for adding data items to maps, and
+ * takes an integer argument that is its label in the map.
+ *
+ * The simplest aggregate type is an array, which is a simple ordered
+ * set of items without labels the same as JSON arrays. Call
+ * QCBOREncode_OpenArray() to open a new array, then various @c
+ * QCBOREncode_AddXxx() functions to put items in the array and then
+ * QCBOREncode_CloseArray(). Nesting to the limit @ref
+ * QCBOR_MAX_ARRAY_NESTING is allowed. All opens must be matched by
+ * closes or an encoding error will be returned.
+ *
+ * The other aggregate type is a map which does use labels. The `Add`
+ * functions that end in `ToMap` and `ToMapN` are convenient ways to add
+ * labeled data items to a map. You can also call any type of `Add`
+ * function once to add a label of any type and then call any type of
+ * `Add` again to add its value.
+ *
+ * Note that when you nest arrays or maps in a map, the nested array or
+ * map has a label.
+ *
+ * Many CBOR-based protocols start with an array or map. This makes them
+ * self-delimiting. No external length or end marker is needed to know
+ * the end. It is also possible not start this way, in which case this
+ * it is usually called a CBOR sequence which is described in
+ * [RFC 8742] (https://tools.ietf.org/html/rfc8742). This encoder supports
+ * either just by whether the first item added is an array, map or other.
+ *
+ * If QCBOR is compiled with QCBOR_DISABLE_ENCODE_USAGE_GUARDS defined,
+ * the errors QCBOR_ERR_CLOSE_MISMATCH, QCBOR_ERR_ARRAY_TOO_LONG,
+ * QCBOR_ERR_TOO_MANY_CLOSES, QCBOR_ERR_ARRAY_OR_MAP_STILL_OPEN, and
+ * QCBOR_ERR_ENCODE_UNSUPPORTED will never be returned. It is up to the
+ * caller to make sure that opened maps, arrays and byte-string wrapping
+ * is closed correctly and that QCBOREncode_AddType7() is called
+ * correctly. With this defined, it is easier to make a mistake when
+ * authoring the encoding of a protocol that will output not well formed
+ * CBOR, but as long as the calling code is correct, it is safe to
+ * disable these checks. Bounds checking that prevents security issues
+ * in the code is still enforced. This define reduces the size of
+ * encoding object code by about 150 bytes.
+ *
+ * @anchor Tags-Overview
+ *
+ * ## Tags Overview
+ *
+ * Any CBOR data item can be made into a tag to add semantics, define a
+ * new data type or such. Some tags are fully standardized and some are
+ * just registered. Others are not registered and used in a proprietary
+ * way.
+ *
+ * Encoding and decoding of many of the registered tags is fully
+ * implemented by QCBOR. It is also possible to encode and decode tags
+ * that are not directly supported. For many use cases the built-in tag
+ * support should be adequate.
+ *
+ * For example, the registered epoch date tag is supported in encoding
+ * by QCBOREncode_AddDateEpoch() and in decoding by @ref
+ * QCBOR_TYPE_DATE_EPOCH and the @c epochDate member of @ref
+ * QCBORItem. This is typical of the built-in tag support. There is an
+ * API to encode data for it and a @c QCBOR_TYPE_XXX when it is decoded.
+ *
+ * Tags are registered in the [IANA CBOR Tags Registry]
+ * (https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml). There
+ * are roughly three options to create a new tag. First, a public
+ * specification can be created and the new tag registered with IANA.
+ * This is the most formal. Second, the new tag can be registered with
+ * IANA with just a short description rather than a full specification.
+ * These tags must be greater than 256. Third, a tag can be used without
+ * any IANA registration, though the registry should be checked to see
+ * that the new value doesn't collide with one that is registered. The
+ * value of these tags must be 256 or larger.
+ *
+ * See also @ref CBORTags and @ref Tag-Usage
+ *
+ * The encoding side of tags not built-in is handled by
+ * QCBOREncode_AddTag() and is relatively simple. Tag decoding is more
+ * complex and mainly handled by QCBORDecode_GetNext(). Decoding of the
+ * structure of tagged data not built-in (if there is any) has to be
+ * implemented by the caller.
+ *
+ * @anchor Floating-Point
+ *
+ * ## Floating-Point
+ *
+ * By default QCBOR fully supports IEEE 754 floating-point:
+ * - Encode/decode of double, single and half-precision
+ * - CBOR preferred serialization of floating-point
+ * - Floating-point epoch dates
+ *
+ * For the most part, the type double is used in the interface for
+ * floating-point values. In the default configuration, all decoded
+ * floating-point values are returned as a double.
+ *
+ * With CBOR preferred serialization, the encoder outputs the smallest
+ * representation of the double or float that preserves precision. Zero,
+ * NaN and infinity are always output as a half-precision, each taking
+ * just 2 bytes. This reduces the number of bytes needed to encode
+ * double and single-precision, especially if zero, NaN and infinity are
+ * frequently used.
+ *
+ * To avoid use of preferred serialization in the standard configuration
+ * when encoding, use QCBOREncode_AddDoubleNoPreferred() or
+ * QCBOREncode_AddFloatNoPreferred().
+ *
+ * This implementation of preferred floating-point serialization and
+ * half-precision does not depend on the CPU having floating-point HW or
+ * the compiler bringing in a (sometimes large) library to compensate
+ * for lack of CPU support. This implementation uses shifts and masks
+ * rather than floating-point functions.
+ *
+ * To reduce overall object code by about 900 bytes, define
+ * QCBOR_DISABLE_PREFERRED_FLOAT. This will eliminate all support for
+ * preferred serialization and half-precision. An error will be returned
+ * when attempting to decode half-precision. A float will always be
+ * encoded and decoded as 32-bits and a double will always be encoded
+ * and decoded as 64 bits.
+ *
+ * Note that even if QCBOR_DISABLE_PREFERRED_FLOAT is not defined all
+ * the float-point encoding object code can be avoided by never calling
+ * any functions that encode double or float. Just not calling
+ * floating-point functions will reduce object code by about 500 bytes.
+ *
+ * On CPUs that have no floating-point hardware,
+ * QCBOR_DISABLE_FLOAT_HW_USE should be defined in most cases. If it is
+ * not, then the compiler will bring in possibly large software
+ * libraries to compensate. Defining QCBOR_DISABLE_FLOAT_HW_USE reduces
+ * object code size on CPUs with floating-point hardware by a tiny
+ * amount and eliminates the need for <math.h>
+ *
+ * When QCBOR_DISABLE_FLOAT_HW_USE is defined, trying to decoding
+ * floating-point dates will give error
+ * @ref QCBOR_ERR_FLOAT_DATE_DISABLED and decoded single-precision
+ * numbers will be returned as @ref QCBOR_TYPE_FLOAT instead of
+ * converting them to double as usual.
+ *
+ * If both QCBOR_DISABLE_FLOAT_HW_USE and QCBOR_DISABLE_PREFERRED_FLOAT
+ * are defined, then the only thing QCBOR can do is encode/decode a C
+ * float type as 32-bits and a C double type as 64-bits. Floating-point
+ * epoch dates will be unsupported.
+ *
+ * If USEFULBUF_DISABLE_ALL_FLOATis defined, then floating point
+ * support is completely disabled. Decoding functions return
+ * @ref QCBOR_ERR_ALL_FLOAT_DISABLED if a floating point value is
+ * encountered during decoding. Functions that are encoding floating
+ * point values are not available.
+ *
+ * ## Limitations
+ *
+ * Summary Limits of this implementation:
+ * - The entire encoded CBOR must fit into contiguous memory.
+ * - Max size of encoded / decoded CBOR data is a few bytes less than @c UINT32_MAX (4GB).
+ * - Max array / map nesting level when encoding / decoding is
+ * @ref QCBOR_MAX_ARRAY_NESTING (this is typically 15).
+ * - Max items in an array or map when encoding / decoding is
+ * @ref QCBOR_MAX_ITEMS_IN_ARRAY (typically 65,536).
+ * - Does not directly support labels in maps other than text strings & integers.
+ * - Does not directly support integer labels greater than @c INT64_MAX.
+ * - Epoch dates limited to @c INT64_MAX (+/- 292 billion years).
+ * - Exponents for bigfloats and decimal integers are limited to @c INT64_MAX.
+ * - Tags on labels are ignored during decoding.
+ * - The maximum tag nesting is @c QCBOR_MAX_TAGS_PER_ITEM (typically 4).
+ * - Works only on 32- and 64-bit CPUs (modifications could make it work
+ * on 16-bit CPUs).
+ *
+ * The public interface uses @c size_t for all lengths. Internally the
+ * implementation uses 32-bit lengths by design to use less memory and
+ * fit structures on the stack. This limits the encoded CBOR it can
+ * work with to size @c UINT32_MAX (4GB) which should be enough.
+ *
+ * This implementation assumes two's compliment integer machines.
+ * @c <stdint.h> also requires this. It is possible to modify this
+ * implementation for another integer representation, but all modern
+ * machines seem to be two's compliment.
*/
/**
- The size of the buffer to be passed to QCBOREncode_EncodeHead(). It is one
- byte larger than sizeof(uint64_t) + 1, the actual maximum size of the
- head of a CBOR data item because QCBOREncode_EncodeHead() needs
- one extra byte to work.
+ * The size of the buffer to be passed to QCBOREncode_EncodeHead(). It
+ * is one byte larger than sizeof(uint64_t) + 1, the actual maximum
+ * size of the head of a CBOR data item because
+ * QCBOREncode_EncodeHead() needs one extra byte to work.
*/
#define QCBOR_HEAD_BUFFER_SIZE (sizeof(uint64_t) + 2)
/**
- Output the full CBOR tag. See @ref CBORTags, @ref Tag-Usage and
- @ref Tags-Overview.
+ * Output the full CBOR tag. See @ref CBORTags, @ref Tag-Usage and
+ * @ref Tags-Overview.
*/
#define QCBOR_ENCODE_AS_TAG 0
/**
- Output only the 'borrowed' content format for the relevant tag.
- See @ref CBORTags, @ref Tag-Usage and @ref Tags-Overview.
+ * Output only the 'borrowed' content format for the relevant tag.
+ * See @ref CBORTags, @ref Tag-Usage and @ref Tags-Overview.
*/
#define QCBOR_ENCODE_AS_BORROWED 1
/**
- QCBOREncodeContext is the data type that holds context for all the
- encoding functions. It is less than 200 bytes, so it can go on the
- stack. The contents are opaque, and the caller should not access
- internal members. A context may be re used serially as long as it is
- re initialized.
+ * QCBOREncodeContext is the data type that holds context for all the
+ * encoding functions. It is less than 200 bytes, so it can go on the
+ * stack. The contents are opaque, and the caller should not access
+ * internal members. A context may be re used serially as long as it is
+ * re initialized.
*/
typedef struct _QCBOREncodeContext QCBOREncodeContext;
/**
- Initialize the encoder to prepare to encode some CBOR.
-
- @param[in,out] pCtx The encoder context to initialize.
- @param[in] Storage The buffer into which the encoded result
- will be written.
-
- Call this once at the start of an encoding of some CBOR. Then call
- the many functions like QCBOREncode_AddInt64() and
- QCBOREncode_AddText() to add the different data items. Finally, call
- QCBOREncode_Finish() to get the pointer and length of the encoded
- result.
-
- The primary purpose of this function is to give the pointer and
- length of the output buffer into which the encoded CBOR will be
- written. This is done with a @ref UsefulBuf structure, which is just
- a pointer and length (it is equivalent to two parameters, one a
- pointer and one a length, but a little prettier).
-
- The output buffer can be allocated any way (malloc, stack,
- static). It is just some memory that QCBOR writes to. The length must
- be the length of the allocated buffer. QCBOR will never write past
- that length, but might write up to that length. If the buffer is too
- small, encoding will go into an error state and not write anything
- further.
-
- If allocating on the stack the convenience macro
- UsefulBuf_MAKE_STACK_UB() can be used, but its use is not required.
-
- Since there is no reallocation or such, the output buffer must be
- correctly sized when passed in here. It is OK, but wasteful if it is
- too large. One way to pick the size is to figure out the maximum size
- that will ever be needed and hard code a buffer of that size.
-
- Another way to do it is to have QCBOR calculate it for you. To do
- this, pass @ref SizeCalculateUsefulBuf for @c Storage.
- Then call all the functions to add the CBOR exactly as if
- encoding for real. Finally, call QCBOREncode_FinishGetSize().
- Once the length is obtained, allocate a buffer of that
- size, call QCBOREncode_Init() again with the real buffer. Call all
- the add functions again and finally, QCBOREncode_Finish() to obtain
- the final result. This uses twice the CPU time, but that is
- usually not an issue.
-
- See QCBOREncode_Finish() for how the pointer and length for the
- encoded CBOR is returned.
-
- For practical purposes QCBOR can't output encoded CBOR larger than
- @c UINT32_MAX (4GB) even on 64-bit CPUs because the internal offsets
- used to track the start of an array/map are 32 bits to reduce the
- size of the encoding context.
-
- A @ref QCBOREncodeContext can be reused over and over as long as
- QCBOREncode_Init() is called before each use.
+ * Initialize the encoder to prepare to encode some CBOR.
+ *
+ * @param[in,out] pCtx The encoder context to initialize.
+ * @param[in] Storage The buffer into which the encoded result
+ * will be written.
+ *
+ * Call this once at the start of an encoding of some CBOR. Then call
+ * the many functions like QCBOREncode_AddInt64() and
+ * QCBOREncode_AddText() to add the different data items. Finally,
+ * call QCBOREncode_Finish() to get the pointer and length of the
+ * encoded result.
+ *
+ * The primary purpose of this function is to give the pointer and
+ * length of the output buffer into which the encoded CBOR will be
+ * written. This is done with a @ref UsefulBuf structure, which is
+ * just a pointer and length (it is equivalent to two parameters, one
+ * a pointer and one a length, but a little prettier).
+ *
+ * The output buffer can be allocated any way (malloc, stack,
+ * static). It is just some memory that QCBOR writes to. The length
+ * must be the length of the allocated buffer. QCBOR will never write
+ * past that length, but might write up to that length. If the buffer
+ * is too small, encoding will go into an error state and not write
+ * anything further.
+ *
+ * If allocating on the stack the convenience macro
+ * UsefulBuf_MAKE_STACK_UB() can be used, but its use is not required.
+ *
+ * Since there is no reallocation or such, the output buffer must be
+ * correctly sized when passed in here. It is OK, but wasteful if it
+ * is too large. One way to pick the size is to figure out the maximum
+ * size that will ever be needed and hard code a buffer of that size.
+ *
+ * Another way to do it is to have QCBOR calculate it for you. To do
+ * this, pass @ref SizeCalculateUsefulBuf for @c Storage. Then call
+ * all the functions to add the CBOR exactly as if encoding for
+ * real. Finally, call QCBOREncode_FinishGetSize(). Once the length
+ * is obtained, allocate a buffer of that size, call
+ * QCBOREncode_Init() again with the real buffer. Call all the add
+ * functions again and finally, QCBOREncode_Finish() to obtain the
+ * final result. This uses twice the CPU time, but that is usually not
+ * an issue.
+ *
+ * See QCBOREncode_Finish() for how the pointer and length for the
+ * encoded CBOR is returned.
+ *
+ * For practical purposes QCBOR can't output encoded CBOR larger than
+ * @c UINT32_MAX (4GB) even on 64-bit CPUs because the internal
+ * offsets used to track the start of an array/map are 32 bits to
+ * reduce the size of the encoding context.
+ *
+ * A @ref QCBOREncodeContext can be reused over and over as long as
+ * QCBOREncode_Init() is called before each use.
*/
-void QCBOREncode_Init(QCBOREncodeContext *pCtx, UsefulBuf Storage);
+void
+QCBOREncode_Init(QCBOREncodeContext *pCtx, UsefulBuf Storage);
/**
- @brief Add a signed 64-bit integer to the encoded output.
-
- @param[in] pCtx The encoding context to add the integer to.
- @param[in] nNum The integer to add.
-
- The integer will be encoded and added to the CBOR output.
-
- This function figures out the size and the sign and encodes in the
- correct minimal CBOR. Specifically, it will select CBOR major type 0
- or 1 based on sign and will encode to 1, 2, 4 or 8 bytes depending on
- the value of the integer. Values less than 24 effectively encode to
- one byte because they are encoded in with the CBOR major type. This
- is a neat and efficient characteristic of CBOR that can be taken
- advantage of when designing CBOR-based protocols. If integers like
- tags can be kept between -23 and 23 they will be encoded in one byte
- including the major type.
-
- If you pass a smaller int, say an @c int16_t or a small value, say
- 100, the encoding will still be CBOR's most compact that can
- represent the value. For example, CBOR always encodes the value 0 as
- one byte, 0x00. The representation as 0x00 includes identification of
- the type as an integer too as the major type for an integer is 0. See
- [RFC 8949] (https://tools.ietf.org/html/rfc8949) Appendix A for more
- examples of CBOR encoding. This compact encoding is also preferred
- serialization CBOR as per section 34.1 in RFC 8949.
-
- There are no functions to add @c int16_t or @c int32_t because they
- are not necessary because this always encodes to the smallest number
- of bytes based on the value (If this code is running on a 32-bit
- machine having a way to add 32-bit integers would reduce code size
- some).
-
- If the encoding context is in an error state, this will do
- nothing. If an error occurs when adding this integer, the internal
- error flag will be set, and the error will be returned when
- QCBOREncode_Finish() is called.
-
- See also QCBOREncode_AddUInt64().
+ * @brief Add a signed 64-bit integer to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the integer to.
+ * @param[in] nNum The integer to add.
+ *
+ * The integer will be encoded and added to the CBOR output.
+ *
+ * This function figures out the size and the sign and encodes in the
+ * correct minimal CBOR. Specifically, it will select CBOR major type
+ * 0 or 1 based on sign and will encode to 1, 2, 4 or 8 bytes
+ * depending on the value of the integer. Values less than 24
+ * effectively encode to one byte because they are encoded in with the
+ * CBOR major type. This is a neat and efficient characteristic of
+ * CBOR that can be taken advantage of when designing CBOR-based
+ * protocols. If integers like tags can be kept between -23 and 23
+ * they will be encoded in one byte including the major type.
+ *
+ * If you pass a smaller int, say an @c int16_t or a small value, say
+ * 100, the encoding will still be CBOR's most compact that can
+ * represent the value. For example, CBOR always encodes the value 0
+ * as one byte, 0x00. The representation as 0x00 includes
+ * identification of the type as an integer too as the major type for
+ * an integer is 0. See [RFC 8949]
+ * (https://tools.ietf.org/html/rfc8949) Appendix A for more examples
+ * of CBOR encoding. This compact encoding is also preferred
+ * serialization CBOR as per section 34.1 in RFC 8949.
+ *
+ * There are no functions to add @c int16_t or @c int32_t because they
+ * are not necessary because this always encodes to the smallest
+ * number of bytes based on the value (If this code is running on a
+ * 32-bit machine having a way to add 32-bit integers would reduce
+ * code size some).
+ *
+ * If the encoding context is in an error state, this will do
+ * nothing. If an error occurs when adding this integer, the internal
+ * error flag will be set, and the error will be returned when
+ * QCBOREncode_Finish() is called.
+ *
+ * See also QCBOREncode_AddUInt64().
*/
-void QCBOREncode_AddInt64(QCBOREncodeContext *pCtx, int64_t nNum);
+void
+QCBOREncode_AddInt64(QCBOREncodeContext *pCtx, int64_t nNum);
-static void QCBOREncode_AddInt64ToMap(QCBOREncodeContext *pCtx, const char *szLabel, int64_t uNum);
+static void
+QCBOREncode_AddInt64ToMap(QCBOREncodeContext *pCtx, const char *szLabel, int64_t uNum);
-static void QCBOREncode_AddInt64ToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, int64_t uNum);
+static void
+QCBOREncode_AddInt64ToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, int64_t uNum);
/**
- @brief Add an unsigned 64-bit integer to the encoded output.
-
- @param[in] pCtx The encoding context to add the integer to.
- @param[in] uNum The integer to add.
-
- The integer will be encoded and added to the CBOR output.
-
- The only reason so use this function is for integers larger than @c
- INT64_MAX and smaller than @c UINT64_MAX. Otherwise
- QCBOREncode_AddInt64() will work fine.
-
- Error handling is the same as for QCBOREncode_AddInt64().
+ * @brief Add an unsigned 64-bit integer to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the integer to.
+ * @param[in] uNum The integer to add.
+ *
+ * The integer will be encoded and added to the CBOR output.
+ *
+ * The only reason so use this function is for integers larger than
+ * @c INT64_MAX and smaller than @c UINT64_MAX. Otherwise
+ * QCBOREncode_AddInt64() will work fine.
+ *
+ * Error handling is the same as for QCBOREncode_AddInt64().
*/
-void QCBOREncode_AddUInt64(QCBOREncodeContext *pCtx, uint64_t uNum);
+void
+QCBOREncode_AddUInt64(QCBOREncodeContext *pCtx, uint64_t uNum);
-static void QCBOREncode_AddUInt64ToMap(QCBOREncodeContext *pCtx, const char *szLabel, uint64_t uNum);
+static void
+QCBOREncode_AddUInt64ToMap(QCBOREncodeContext *pCtx, const char *szLabel, uint64_t uNum);
-static void QCBOREncode_AddUInt64ToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, uint64_t uNum);
+static void
+QCBOREncode_AddUInt64ToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, uint64_t uNum);
/**
- @brief Add a UTF-8 text string to the encoded output.
-
- @param[in] pCtx The encoding context to add the text to.
- @param[in] Text Pointer and length of text to add.
-
- The text passed in must be unencoded UTF-8 according to [RFC 3629]
- (https://tools.ietf.org/html/rfc3629). There is no NULL
- termination. The text is added as CBOR major type 3.
-
- If called with @c nBytesLen equal to 0, an empty string will be
- added. When @c nBytesLen is 0, @c pBytes may be @c NULL.
-
- Note that the restriction of the buffer length to a @c uint32_t is
- entirely intentional as this encoder is not capable of encoding
- lengths greater. This limit to 4GB for a text string should not be a
- problem.
-
- Text lines in Internet protocols (on the wire) are delimited by
- either a CRLF or just an LF. Officially many protocols specify CRLF,
- but implementations often work with either. CBOR type 3 text can be
- either line ending, even a mixture of both.
-
- Operating systems usually have a line end convention. Windows uses
- CRLF. Linux and MacOS use LF. Some applications on a given OS may
- work with either and some may not.
-
- The majority of use cases and CBOR protocols using type 3 text will
- work with either line ending. However, some use cases or protocols
- may not work with either in which case translation to and/or from the
- local line end convention, typically that of the OS, is necessary.
-
- QCBOR does no line ending translation for type 3 text when encoding
- and decoding.
-
- Error handling is the same as QCBOREncode_AddInt64().
+ * @brief Add a UTF-8 text string to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the text to.
+ * @param[in] Text Pointer and length of text to add.
+ *
+ * The text passed in must be unencoded UTF-8 according to [RFC 3629]
+ * (https://tools.ietf.org/html/rfc3629). There is no NULL
+ * termination. The text is added as CBOR major type 3.
+ *
+ * If called with @c nBytesLen equal to 0, an empty string will be
+ * added. When @c nBytesLen is 0, @c pBytes may be @c NULL.
+ *
+ * Note that the restriction of the buffer length to a @c uint32_t is
+ * entirely intentional as this encoder is not capable of encoding
+ * lengths greater. This limit to 4GB for a text string should not be
+ * a problem.
+ *
+ * Text lines in Internet protocols (on the wire) are delimited by
+ * either a CRLF or just an LF. Officially many protocols specify
+ * CRLF, but implementations often work with either. CBOR type 3 text
+ * can be either line ending, even a mixture of both.
+ *
+ * Operating systems usually have a line end convention. Windows uses
+ * CRLF. Linux and MacOS use LF. Some applications on a given OS may
+ * work with either and some may not.
+ *
+ * The majority of use cases and CBOR protocols using type 3 text will
+ * work with either line ending. However, some use cases or protocols
+ * may not work with either in which case translation to and/or from
+ * the local line end convention, typically that of the OS, is
+ * necessary.
+ *
+ * QCBOR does no line ending translation for type 3 text when encoding
+ * and decoding.
+ *
+ * Error handling is the same as QCBOREncode_AddInt64().
*/
-static void QCBOREncode_AddText(QCBOREncodeContext *pCtx, UsefulBufC Text);
+static void
+QCBOREncode_AddText(QCBOREncodeContext *pCtx, UsefulBufC Text);
-static void QCBOREncode_AddTextToMap(QCBOREncodeContext *pCtx, const char *szLabel, UsefulBufC Text);
+static void
+QCBOREncode_AddTextToMap(QCBOREncodeContext *pCtx, const char *szLabel, UsefulBufC Text);
-static void QCBOREncode_AddTextToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, UsefulBufC Text);
+static void
+QCBOREncode_AddTextToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, UsefulBufC Text);
/**
- @brief Add a UTF-8 text string to the encoded output.
-
- @param[in] pCtx The encoding context to add the text to.
- @param[in] szString Null-terminated text to add.
-
- This works the same as QCBOREncode_AddText().
+ * @brief Add a UTF-8 text string to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the text to.
+ * @param[in] szString Null-terminated text to add.
+ *
+ * This works the same as QCBOREncode_AddText().
*/
-static void QCBOREncode_AddSZString(QCBOREncodeContext *pCtx, const char *szString);
+static void
+QCBOREncode_AddSZString(QCBOREncodeContext *pCtx, const char *szString);
-static void QCBOREncode_AddSZStringToMap(QCBOREncodeContext *pCtx, const char *szLabel, const char *szString);
+static void
+QCBOREncode_AddSZStringToMap(QCBOREncodeContext *pCtx, const char *szLabel, const char *szString);
-static void QCBOREncode_AddSZStringToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, const char *szString);
+static void
+QCBOREncode_AddSZStringToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, const char *szString);
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
/**
- @brief Add a double-precision floating-point number to the encoded output.
-
- @param[in] pCtx The encoding context to add the double to.
- @param[in] dNum The double-precision number to add.
-
- This encodes and outputs a floating-point number. CBOR major type 7
- is used.
-
- This implements preferred serialization, selectively encoding the
- double-precision floating-point number as either double-precision,
- single-precision or half-precision. Infinity, NaN and 0 are always
- encoded as half-precision. If no precision will be lost in the
- conversion to half-precision, then it will be converted and
- encoded. If not and no precision will be lost in conversion to
- single-precision, then it will be converted and encoded. If not, then
- no conversion is performed, and it encoded as a double-precision.
-
- Half-precision floating-point numbers take up 2 bytes, half that of
- single-precision, one quarter of double-precision
-
- This automatically reduces the size of encoded CBOR, maybe even by
- four if most of values are 0, infinity or NaN.
-
- When decoded, QCBOR will usually return these values as
- double-precision.
-
- It is possible to disable this preferred serialization when compiling
- QCBOR. In that case, this functions the same as
- QCBOREncode_AddDoubleNoPreferred().
-
- Error handling is the same as QCBOREncode_AddInt64().
-
- See also QCBOREncode_AddDoubleNoPreferred(), QCBOREncode_AddFloat()
- and QCBOREncode_AddFloatNoPreferred() and @ref Floating-Point.
+ * @brief Add a double-precision floating-point number to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the double to.
+ * @param[in] dNum The double-precision number to add.
+ *
+ * This encodes and outputs a floating-point number. CBOR major type 7
+ * is used.
+ *
+ * This implements preferred serialization, selectively encoding the
+ * double-precision floating-point number as either double-precision,
+ * single-precision or half-precision. Infinity, NaN and 0 are always
+ * encoded as half-precision. If no precision will be lost in the
+ * conversion to half-precision, then it will be converted and
+ * encoded. If not and no precision will be lost in conversion to
+ * single-precision, then it will be converted and encoded. If not,
+ * then no conversion is performed, and it encoded as a
+ * double-precision.
+ *
+ * Half-precision floating-point numbers take up 2 bytes, half that of
+ * single-precision, one quarter of double-precision
+ *
+ * This automatically reduces the size of encoded CBOR, maybe even by
+ * four if most of values are 0, infinity or NaN.
+ *
+ * When decoded, QCBOR will usually return these values as
+ * double-precision.
+ *
+ * It is possible to disable this preferred serialization when compiling
+ * QCBOR. In that case, this functions the same as
+ * QCBOREncode_AddDoubleNoPreferred().
+ *
+ * Error handling is the same as QCBOREncode_AddInt64().
+ *
+ * See also QCBOREncode_AddDoubleNoPreferred(), QCBOREncode_AddFloat()
+ * and QCBOREncode_AddFloatNoPreferred() and @ref Floating-Point.
*/
-void QCBOREncode_AddDouble(QCBOREncodeContext *pCtx, double dNum);
+void
+QCBOREncode_AddDouble(QCBOREncodeContext *pCtx, double dNum);
-static void QCBOREncode_AddDoubleToMap(QCBOREncodeContext *pCtx, const char *szLabel, double dNum);
+static void
+QCBOREncode_AddDoubleToMap(QCBOREncodeContext *pCtx, const char *szLabel, double dNum);
-static void QCBOREncode_AddDoubleToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, double dNum);
+static void
+QCBOREncode_AddDoubleToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, double dNum);
/**
- @brief Add a single-precision floating-point number to the encoded output.
+ * @brief Add a single-precision floating-point number to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the double to.
+ * @param[in] fNum The single-precision number to add.
+ *
+ * This is identical to QCBOREncode_AddDouble() except the input is
+ * single-precision.
+ *
+ * See also QCBOREncode_AddDouble(), QCBOREncode_AddDoubleNoPreferred(),
+ * and QCBOREncode_AddFloatNoPreferred() and @ref Floating-Point.
+ */
+void
+QCBOREncode_AddFloat(QCBOREncodeContext *pCtx, float fNum);
- @param[in] pCtx The encoding context to add the double to.
- @param[in] fNum The single-precision number to add.
+static void
+QCBOREncode_AddFloatToMap(QCBOREncodeContext *pCtx, const char *szLabel, float fNum);
- This is identical to QCBOREncode_AddDouble() except the input is
- single-precision.
-
- See also QCBOREncode_AddDouble(), QCBOREncode_AddDoubleNoPreferred(),
- and QCBOREncode_AddFloatNoPreferred() and @ref Floating-Point.
-*/
-void QCBOREncode_AddFloat(QCBOREncodeContext *pCtx, float fNum);
-
-static void QCBOREncode_AddFloatToMap(QCBOREncodeContext *pCtx, const char *szLabel, float fNum);
-
-static void QCBOREncode_AddFloatToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, float dNum);
+static void
+QCBOREncode_AddFloatToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, float dNum);
/**
- @brief Add a double-precision floating-point number without preferred encoding.
+ * @brief Add a double-precision floating-point number without preferred encoding.
+ *
+ * @param[in] pCtx The encoding context to add the double to.
+ * @param[in] dNum The double-precision number to add.
+ *
+ * This always outputs the number as a 64-bit double-precision.
+ * Preferred serialization is not used.
+ *
+ * Error handling is the same as QCBOREncode_AddInt64().
+ *
+ * See also QCBOREncode_AddDouble(), QCBOREncode_AddFloat(), and
+ * QCBOREncode_AddFloatNoPreferred() and @ref Floating-Point.
+ */
+void
+QCBOREncode_AddDoubleNoPreferred(QCBOREncodeContext *pCtx, double dNum);
- @param[in] pCtx The encoding context to add the double to.
- @param[in] dNum The double-precision number to add.
+static void
+QCBOREncode_AddDoubleNoPreferredToMap(QCBOREncodeContext *pCtx, const char *szLabel, double dNum);
- This always outputs the number as a 64-bit double-precision.
- Preferred serialization is not used.
-
- Error handling is the same as QCBOREncode_AddInt64().
-
- See also QCBOREncode_AddDouble(), QCBOREncode_AddFloat(), and
- QCBOREncode_AddFloatNoPreferred() and @ref Floating-Point.
-*/
-void QCBOREncode_AddDoubleNoPreferred(QCBOREncodeContext *pCtx, double dNum);
-
-static void QCBOREncode_AddDoubleNoPreferredToMap(QCBOREncodeContext *pCtx, const char *szLabel, double dNum);
-
-static void QCBOREncode_AddDoubleNoPreferredToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, double dNum);
+static void
+QCBOREncode_AddDoubleNoPreferredToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, double dNum);
/**
- @brief Add a single-precision floating-point number without preferred encoding.
+ * @brief Add a single-precision floating-point number without preferred encoding.
+ *
+ * @param[in] pCtx The encoding context to add the double to.
+ * @param[in] fNum The single-precision number to add.
+ *
+ * This always outputs the number as a 32-bit single-precision.
+ * Preferred serialization is not used.
+ *
+ * Error handling is the same as QCBOREncode_AddInt64().
+ *
+ * See also QCBOREncode_AddDouble(), QCBOREncode_AddFloat(), and
+ * QCBOREncode_AddDoubleNoPreferred() and @ref Floating-Point.
+ */
+void
+QCBOREncode_AddFloatNoPreferred(QCBOREncodeContext *pCtx, float fNum);
- @param[in] pCtx The encoding context to add the double to.
- @param[in] fNum The single-precision number to add.
+static void
+QCBOREncode_AddFloatNoPreferredToMap(QCBOREncodeContext *pCtx, const char *szLabel, float fNum);
- This always outputs the number as a 32-bit single-precision.
- Preferred serialization is not used.
-
- Error handling is the same as QCBOREncode_AddInt64().
-
- See also QCBOREncode_AddDouble(), QCBOREncode_AddFloat(), and
- QCBOREncode_AddDoubleNoPreferred() and @ref Floating-Point.
-*/
-void QCBOREncode_AddFloatNoPreferred(QCBOREncodeContext *pCtx, float fNum);
-
-static void QCBOREncode_AddFloatNoPreferredToMap(QCBOREncodeContext *pCtx, const char *szLabel, float fNum);
-
-static void QCBOREncode_AddFloatNoPreferredToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, float fNum);
+static void
+QCBOREncode_AddFloatNoPreferredToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, float fNum);
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
/**
- @brief Add an optional tag.
-
- @param[in] pCtx The encoding context to add the tag to.
- @param[in] uTag The tag to add
-
- This outputs a CBOR major type 6 item that tags the next data item
- that is output usually to indicate it is some new data type.
-
- For many of the common standard tags, a function to encode data using
- it is provided and this is not needed. For example,
- QCBOREncode_AddDateEpoch() already exists to output integers
- representing dates with the right tag.
-
- The tag is applied to the next data item added to the encoded
- output. That data item that is to be tagged can be of any major CBOR
- type. Any number of tags can be added to a data item by calling this
- multiple times before the data item is added.
-
- See @ref Tags-Overview for discussion of creating new non-standard
- tags. See QCBORDecode_GetNext() for discussion of decoding custom
- tags.
-*/
-void QCBOREncode_AddTag(QCBOREncodeContext *pCtx, uint64_t uTag);
-
-
-/**
- @brief Add an epoch-based date.
-
- @param[in] pCtx The encoding context to add the date to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] nDate Number of seconds since 1970-01-01T00:00Z in UTC time.
-
- As per RFC 8949 this is similar to UNIX/Linux/POSIX dates. This is
- the most compact way to specify a date and time in CBOR. Note that
- this is always UTC and does not include the time zone. Use
- QCBOREncode_AddDateString() if you want to include the time zone.
-
- The preferred integer encoding rules apply here so the date will be encoded in
- a minimal number of bytes. Until about the year 2106 these dates will
- encode in 6 bytes -- one byte for the tag, one byte for the type and
- 4 bytes for the integer. After that it will encode to 10 bytes.
-
- Negative values are supported for dates before 1970.
-
- If you care about leap-seconds and that level of accuracy, make sure
- the system you are running this code on does it correctly. This code
- just takes the value passed in.
-
- This implementation cannot encode fractional seconds using float or
- double even though that is allowed by CBOR, but you can encode them
- if you want to by calling QCBOREncode_AddTag() and QCBOREncode_AddDouble().
-
- Error handling is the same as QCBOREncode_AddInt64().
-
- See also QCBOREncode_AddTDaysEpoch().
+ * @brief Add an optional tag.
+ *
+ * @param[in] pCtx The encoding context to add the tag to.
+ * @param[in] uTag The tag to add
+ *
+ * This outputs a CBOR major type 6 item that tags the next data item
+ * that is output usually to indicate it is some new data type.
+ *
+ * For many of the common standard tags, a function to encode data
+ * using it is provided and this is not needed. For example,
+ * QCBOREncode_AddDateEpoch() already exists to output integers
+ * representing dates with the right tag.
+ *
+ * The tag is applied to the next data item added to the encoded
+ * output. That data item that is to be tagged can be of any major
+ * CBOR type. Any number of tags can be added to a data item by
+ * calling this multiple times before the data item is added.
+ *
+ * See @ref Tags-Overview for discussion of creating new non-standard
+ * tags. See QCBORDecode_GetNext() for discussion of decoding custom
+ * tags.
*/
-static void QCBOREncode_AddTDateEpoch(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
- int64_t nDate);
-
-static void QCBOREncode_AddTDateEpochToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- int64_t nDate);
-
-static void QCBOREncode_AddTDateEpochToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- int64_t nDate);
-
-
-static void QCBOREncode_AddDateEpoch(QCBOREncodeContext *pCtx,
- int64_t nDate);
-
-static void QCBOREncode_AddDateEpochToMap(QCBOREncodeContext *pCtx,
- const char *szLabel,
- int64_t nDate);
-
-static void QCBOREncode_AddDateEpochToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- int64_t nDate);
-
-
-
-/**
- @brief Add an epoch-based day-count date.
-
- @param[in] pCtx The encoding context to add the date to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
- @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] nDays Number of days before or after 1970-01-0.
-
- This date format is described in
- [RFC 8943] (https://tools.ietf.org/html/rfc8943).
-
- The integer encoding rules apply here so the date will be encoded in
- a minimal number of bytes. Until about the year 2149 these dates will
- encode in 4 bytes -- one byte for the tag, one byte for the type and
- 2 bytes for the integer.
-
- See also QCBOREncode_AddTDateEpoch().
-
-*/
-static void QCBOREncode_AddTDaysEpoch(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
- int64_t nDays);
-
-static void QCBOREncode_AddTDaysEpochToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- int64_t nDays);
-
-static void QCBOREncode_AddTDaysEpochToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- int64_t nDays);
-
-
+void
+QCBOREncode_AddTag(QCBOREncodeContext *pCtx, uint64_t uTag);
/**
- @brief Add a byte string to the encoded output.
-
- @param[in] pCtx The encoding context to add the bytes to.
- @param[in] Bytes Pointer and length of the input data.
-
- Simply adds the bytes to the encoded output as CBOR major type 2.
-
- If called with @c Bytes.len equal to 0, an empty string will be
- added. When @c Bytes.len is 0, @c Bytes.ptr may be @c NULL.
-
- Error handling is the same as QCBOREncode_AddInt64().
+ * @brief Add an epoch-based date.
+ *
+ * @param[in] pCtx The encoding context to add the date to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] nDate Number of seconds since 1970-01-01T00:00Z
+ * in UTC time.
+ *
+ * As per RFC 8949 this is similar to UNIX/Linux/POSIX dates. This is
+ * the most compact way to specify a date and time in CBOR. Note that
+ * this is always UTC and does not include the time zone. Use
+ * QCBOREncode_AddDateString() if you want to include the time zone.
+ *
+ * The preferred integer serialization rules apply here so the date will be
+ * encoded in a minimal number of bytes. Until about the year 2106
+ * these dates will encode in 6 bytes -- one byte for the tag, one
+ * byte for the type and 4 bytes for the integer. After that it will
+ * encode to 10 bytes.
+ *
+ * Negative values are supported for dates before 1970.
+ *
+ * If you care about leap-seconds and that level of accuracy, make sure
+ * the system you are running this code on does it correctly. This code
+ * just takes the value passed in.
+ *
+ * This implementation cannot encode fractional seconds using float or
+ * double even though that is allowed by CBOR, but you can encode them
+ * if you want to by calling QCBOREncode_AddTag() and QCBOREncode_AddDouble().
+ *
+ * Error handling is the same as QCBOREncode_AddInt64().
+ *
+ * See also QCBOREncode_AddTDaysEpoch().
*/
-static void QCBOREncode_AddBytes(QCBOREncodeContext *pCtx, UsefulBufC Bytes);
+static void
+QCBOREncode_AddTDateEpoch(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ int64_t nDate);
-static void QCBOREncode_AddBytesToMap(QCBOREncodeContext *pCtx, const char *szLabel, UsefulBufC Bytes);
+static void
+QCBOREncode_AddTDateEpochToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ int64_t nDate);
-static void QCBOREncode_AddBytesToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, UsefulBufC Bytes);
+static void
+QCBOREncode_AddTDateEpochToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ int64_t nDate);
+
+
+static void
+QCBOREncode_AddDateEpoch(QCBOREncodeContext *pCtx,
+ int64_t nDate);
+
+static void
+QCBOREncode_AddDateEpochToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ int64_t nDate);
+
+static void
+QCBOREncode_AddDateEpochToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ int64_t nDate);
+
/**
- @brief Set up to write a byte string value directly to encoded output.
+ * @brief Add an epoch-based day-count date.
+ *
+ * @param[in] pCtx The encoding context to add the date to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] nDays Number of days before or after 1970-01-0.
+ *
+ * This date format is described in
+ * [RFC 8943] (https://tools.ietf.org/html/rfc8943).
+ *
+ * The preferred integer serialization rules apply here so the date
+ * will be encoded in a minimal number of bytes. Until about the year
+ * 2149 these dates will encode in 4 bytes -- one byte for the tag,
+ * one byte for the type and 2 bytes for the integer.
+ *
+ * See also QCBOREncode_AddTDateEpoch().
+ */
+static void
+QCBOREncode_AddTDaysEpoch(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ int64_t nDays);
- @param[in] pCtx The encoding context to add the bytes to.
- @param[out] pPlace Pointer and length of place to write byte string value.
+static void
+QCBOREncode_AddTDaysEpochToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ int64_t nDays);
- QCBOREncode_AddBytes() is the normal way to encode a byte string.
- This is for special cases and by passes some of the pointer safety.
+static void
+QCBOREncode_AddTDaysEpochToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ int64_t nDays);
- The purpose of this is to output the bytes that make up a byte string
- value directly to the QCBOR output buffer so you don't need to have a
- copy of it in memory. This is particularly useful if the byte string
- is large, for example, the encrypted payload of a COSE_Encrypt
- message. The payload encryption algorithm can output directly to the
- encoded CBOR buffer, perhaps by making it the output buffer
- for some function (e.g. symmetric encryption) or by multiple writes.
- The pointer in \c pPlace is where to start writing. Writing is just
- copying bytes to the location by the pointer in \c pPlace. Writing
- past the length in \c pPlace will be writing off the end of the
- output buffer.
- If there is no room in the output buffer @ref NULLUsefulBuf will be
- returned and there is no need to call QCBOREncode_CloseBytes().
- The byte string must be closed by calling QCBOREncode_CloseBytes().
+/**
+ * @brief Add a byte string to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the bytes to.
+ * @param[in] Bytes Pointer and length of the input data.
+ *
+ * Simply adds the bytes to the encoded output as CBOR major type 2.
+ *
+ * If called with @c Bytes.len equal to 0, an empty string will be
+ * added. When @c Bytes.len is 0, @c Bytes.ptr may be @c NULL.
+ *
+ * Error handling is the same as QCBOREncode_AddInt64().
+ */
+static void
+QCBOREncode_AddBytes(QCBOREncodeContext *pCtx, UsefulBufC Bytes);
- Warning: this bypasses some of the usual checks provided by QCBOR
- against writing off the end of the encoded output buffer.
+static void
+QCBOREncode_AddBytesToMap(QCBOREncodeContext *pCtx, const char *szLabel, UsefulBufC Bytes);
+
+static void
+QCBOREncode_AddBytesToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, UsefulBufC Bytes);
+
+
+/**
+ * @brief Set up to write a byte string value directly to encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the bytes to.
+ * @param[out] pPlace Pointer and length of place to write byte string value.
+ *
+ * QCBOREncode_AddBytes() is the normal way to encode a byte string.
+ * This is for special cases and by passes some of the pointer safety.
+ *
+ * The purpose of this is to output the bytes that make up a byte
+ * string value directly to the QCBOR output buffer so you don't need
+ * to have a copy of it in memory. This is particularly useful if the
+ * byte string is large, for example, the encrypted payload of a
+ * COSE_Encrypt message. The payload encryption algorithm can output
+ * directly to the encoded CBOR buffer, perhaps by making it the
+ * output buffer for some function (e.g. symmetric encryption) or by
+ * multiple writes.
+ *
+ * The pointer in @c pPlace is where to start writing. Writing is just
+ * copying bytes to the location by the pointer in \c pPlace. Writing
+ * past the length in @c pPlace will be writing off the end of the
+ * output buffer.
+ *
+ * If there is no room in the output buffer @ref NULLUsefulBuf will be
+ * returned and there is no need to call QCBOREncode_CloseBytes().
+ *
+ * The byte string must be closed by calling QCBOREncode_CloseBytes().
+ *
+ * Warning: this bypasses some of the usual checks provided by QCBOR
+ * against writing off the end of the encoded output buffer.
*/
void
QCBOREncode_OpenBytes(QCBOREncodeContext *pCtx, UsefulBuf *pPlace);
static void
-QCBOREncode_OpenBytesInMapSZ(QCBOREncodeContext *pCtx, const char *szLabel, UsefulBuf *pPlace);
+QCBOREncode_OpenBytesInMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ UsefulBuf *pPlace);
static void
-QCBOREncode_OpenBytesInMapN(QCBOREncodeContext *pCtx, int64_t nLabel, UsefulBuf *pPlace);
+QCBOREncode_OpenBytesInMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ UsefulBuf *pPlace);
/**
- @brief Close out a byte string written directly to encoded output.
-
- @param[in] pCtx The encoding context to add the bytes to.
- @param[out] uAmount The number of bytes written, the length of the byte string.
-
- This closes out a call to QCBOREncode_OpenBytes(). This inserts a
- CBOR header at the front of the byte string value to make it a
- well-formed byte string.
-
- If there was no call to QCBOREncode_OpenBytes() then
- @ref QCBOR_ERR_TOO_MANY_CLOSES is set.
+ * @brief Close out a byte string written directly to encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the bytes to.
+ * @param[out] uAmount The number of bytes written, the length of the
+ * byte string.
+ *
+ * This closes out a call to QCBOREncode_OpenBytes(). This inserts a
+ * CBOR header at the front of the byte string value to make it a
+ * well-formed byte string.
+ *
+ * If there was no call to QCBOREncode_OpenBytes() then @ref
+ * QCBOR_ERR_TOO_MANY_CLOSES is set.
*/
-void QCBOREncode_CloseBytes(QCBOREncodeContext *pCtx, size_t uAmount);
+void
+QCBOREncode_CloseBytes(QCBOREncodeContext *pCtx, size_t uAmount);
/**
- @brief Add a binary UUID to the encoded output.
-
- @param[in] pCtx The encoding context to add the UUID to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] Bytes Pointer and length of the binary UUID.
-
- A binary UUID as defined in [RFC 4122]
- (https://tools.ietf.org/html/rfc4122) is added to the output.
-
- It is output as CBOR major type 2, a binary string, with tag @ref
- CBOR_TAG_BIN_UUID indicating the binary string is a UUID.
+ * @brief Add a binary UUID to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the UUID to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] Bytes Pointer and length of the binary UUID.
+ *
+ * A binary UUID as defined in [RFC 4122]
+ * (https://tools.ietf.org/html/rfc4122) is added to the output.
+ *
+ * It is output as CBOR major type 2, a binary string, with tag @ref
+ * CBOR_TAG_BIN_UUID indicating the binary string is a UUID.
*/
-static void QCBOREncode_AddTBinaryUUID(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddTBinaryUUID(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddTBinaryUUIDToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddTBinaryUUIDToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddTBinaryUUIDToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddTBinaryUUIDToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddBinaryUUID(QCBOREncodeContext *pCtx, UsefulBufC Bytes);
+static void
+QCBOREncode_AddBinaryUUID(QCBOREncodeContext *pCtx, UsefulBufC Bytes);
-static void QCBOREncode_AddBinaryUUIDToMap(QCBOREncodeContext *pCtx, const char *szLabel, UsefulBufC Bytes);
+static void
+QCBOREncode_AddBinaryUUIDToMap(QCBOREncodeContext *pCtx, const char *szLabel, UsefulBufC Bytes);
-static void QCBOREncode_AddBinaryUUIDToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, UsefulBufC Bytes);
+static void
+QCBOREncode_AddBinaryUUIDToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, UsefulBufC Bytes);
/**
- @brief Add a positive big number to the encoded output.
-
- @param[in] pCtx The encoding context to add the big number to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] Bytes Pointer and length of the big number.
-
- Big numbers are integers larger than 64-bits. Their format is
- described in [RFC 8949] (https://tools.ietf.org/html/rfc8949).
-
- It is output as CBOR major type 2, a binary string, with tag @ref
- CBOR_TAG_POS_BIGNUM indicating the binary string is a positive big
- number.
-
- Often big numbers are used to represent cryptographic keys, however,
- COSE which defines representations for keys chose not to use this
- particular type.
+ * @brief Add a positive big number to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the big number to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] Bytes Pointer and length of the big number.
+ *
+ * Big numbers are integers larger than 64-bits. Their format is
+ * described in [RFC 8949] (https://tools.ietf.org/html/rfc8949).
+ *
+ * It is output as CBOR major type 2, a binary string, with tag
+ * @ref CBOR_TAG_POS_BIGNUM indicating the binary string is a positive
+ * big number.
+ *
+ * Often big numbers are used to represent cryptographic keys,
+ * however, COSE which defines representations for keys chose not to
+ * use this particular type.
*/
-static void QCBOREncode_AddTPositiveBignum(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddTPositiveBignum(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddTPositiveBignumToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddTPositiveBignumToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddTPositiveBignumToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddTPositiveBignumToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddPositiveBignum(QCBOREncodeContext *pCtx,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddPositiveBignum(QCBOREncodeContext *pCtx,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddPositiveBignumToMap(QCBOREncodeContext *pCtx,
- const char *szLabel,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddPositiveBignumToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddPositiveBignumToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddPositiveBignumToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ UsefulBufC Bytes);
/**
- @brief Add a negative big number to the encoded output.
-
- @param[in] pCtx The encoding context to add the big number to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] Bytes Pointer and length of the big number.
-
- Big numbers are integers larger than 64-bits. Their format is
- described in [RFC 8949] (https://tools.ietf.org/html/rfc8949).
-
- It is output as CBOR major type 2, a binary string, with tag @ref
- CBOR_TAG_NEG_BIGNUM indicating the binary string is a negative big
- number.
-
- Often big numbers are used to represent cryptographic keys, however,
- COSE which defines representations for keys chose not to use this
- particular type.
+ * @brief Add a negative big number to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the big number to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] Bytes Pointer and length of the big number.
+ *
+ * Big numbers are integers larger than 64-bits. Their format is
+ * described in [RFC 8949] (https://tools.ietf.org/html/rfc8949).
+ *
+ * It is output as CBOR major type 2, a binary string, with tag
+ * @ref CBOR_TAG_NEG_BIGNUM indicating the binary string is a negative
+ * big number.
+ *
+ * Often big numbers are used to represent cryptographic keys,
+ * however, COSE which defines representations for keys chose not to
+ * use this particular type.
*/
-static void QCBOREncode_AddTNegativeBignum(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddTNegativeBignum(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddTNegativeBignumToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddTNegativeBignumToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddTNegativeBignumToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddTNegativeBignumToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddNegativeBignum(QCBOREncodeContext *pCtx,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddNegativeBignum(QCBOREncodeContext *pCtx,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddNegativeBignumToMap(QCBOREncodeContext *pCtx,
- const char *szLabel,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddNegativeBignumToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ UsefulBufC Bytes);
-static void QCBOREncode_AddNegativeBignumToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- UsefulBufC Bytes);
+static void
+QCBOREncode_AddNegativeBignumToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ UsefulBufC Bytes);
#ifndef QCBOR_DISABLE_EXP_AND_MANTISSA
/**
- @brief Add a decimal fraction to the encoded output.
-
- @param[in] pCtx The encoding context to add the decimal fraction to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] nMantissa The mantissa.
- @param[in] nBase10Exponent The exponent.
-
- The value is nMantissa * 10 ^ nBase10Exponent.
-
- A decimal fraction is good for exact representation of some values
- that can't be represented exactly with standard C (IEEE 754)
- floating-point numbers. Much larger and much smaller numbers can
- also be represented than floating-point because of the larger number
- of bits in the exponent.
-
- The decimal fraction is conveyed as two integers, a mantissa and a
- base-10 scaling factor.
-
- For example, 273.15 is represented by the two integers 27315 and -2.
-
- The exponent and mantissa have the range from @c INT64_MIN to
- @c INT64_MAX for both encoding and decoding (CBOR allows @c -UINT64_MAX
- to @c UINT64_MAX, but this implementation doesn't support this range to
- reduce code size and interface complexity a little).
-
- CBOR Preferred encoding of the integers is used, thus they will be encoded
- in the smallest number of bytes possible.
-
- See also QCBOREncode_AddDecimalFractionBigNum() for a decimal
- fraction with arbitrarily large precision and QCBOREncode_AddBigFloat().
-
- There is no representation of positive or negative infinity or NaN
- (Not a Number). Use QCBOREncode_AddDouble() to encode them.
-
- See @ref expAndMantissa for decoded representation.
+ * @brief Add a decimal fraction to the encoded output.
+ *
+ * @param[in] pCtx Encoding context to add the decimal fraction to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] nMantissa The mantissa.
+ * @param[in] nBase10Exponent The exponent.
+ *
+ * The value is nMantissa * 10 ^ nBase10Exponent.
+ *
+ * A decimal fraction is good for exact representation of some values
+ * that can't be represented exactly with standard C (IEEE 754)
+ * floating-point numbers. Much larger and much smaller numbers can
+ * also be represented than floating-point because of the larger
+ * number of bits in the exponent.
+ *
+ * The decimal fraction is conveyed as two integers, a mantissa and a
+ * base-10 scaling factor.
+ *
+ * For example, 273.15 is represented by the two integers 27315 and -2.
+ *
+ * The exponent and mantissa have the range from @c INT64_MIN to
+ * @c INT64_MAX for both encoding and decoding (CBOR allows
+ * @c -UINT64_MAX to @c UINT64_MAX, but this implementation doesn't
+ * support this range to reduce code size and interface complexity a
+ * little).
+ *
+ * CBOR Preferred serialization of the integers is used, thus they
+ * will be encoded in the smallest number of bytes possible.
+ *
+ * See also QCBOREncode_AddDecimalFractionBigNum() for a decimal
+ * fraction with arbitrarily large precision and
+ * QCBOREncode_AddBigFloat().
+ *
+ * There is no representation of positive or negative infinity or NaN
+ * (Not a Number). Use QCBOREncode_AddDouble() to encode them.
+ *
+ * See @ref expAndMantissa for decoded representation.
*/
-static void QCBOREncode_AddTDecimalFraction(QCBOREncodeContext *pCtx,
+static void
+QCBOREncode_AddTDecimalFraction(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ int64_t nMantissa,
+ int64_t nBase10Exponent);
+
+static void
+QCBOREncode_AddTDecimalFractionToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ int64_t nMantissa,
+ int64_t nBase10Exponent);
+
+static void
+QCBOREncode_AddTDecimalFractionToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ int64_t nMantissa,
+ int64_t nBase10Exponent);
+
+
+static void
+QCBOREncode_AddDecimalFraction(QCBOREncodeContext *pCtx,
+ int64_t nMantissa,
+ int64_t nBase10Exponent);
+
+static void
+QCBOREncode_AddDecimalFractionToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ int64_t nMantissa,
+ int64_t nBase10Exponent);
+
+static void
+QCBOREncode_AddDecimalFractionToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ int64_t nMantissa,
+ int64_t nBase10Exponent);
+
+
+/**
+ * @brief Add a decimal fraction with a big number mantissa to the encoded output.
+ *
+ * @param[in] pCtx Encoding context to add the decimal fraction to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] Mantissa The mantissa.
+ * @param[in] bIsNegative false if mantissa is positive, true if negative.
+ * @param[in] nBase10Exponent The exponent.
+ *
+ * This is the same as QCBOREncode_AddDecimalFraction() except the
+ * mantissa is a big number (See QCBOREncode_AddPositiveBignum())
+ * allowing for arbitrarily large precision.
+ *
+ * See @ref expAndMantissa for decoded representation.
+ */
+static void
+QCBOREncode_AddTDecimalFractionBigNum(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC Mantissa,
+ bool bIsNegative,
+ int64_t nBase10Exponent);
+
+static void
+QCBOREncode_AddTDecimalFractionBigNumToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Mantissa,
+ bool bIsNegative,
+ int64_t nBase10Exponent);
+
+static void
+QCBOREncode_AddTDecimalFractionBigNumToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
uint8_t uTagRequirement,
- int64_t nMantissa,
+ UsefulBufC Mantissa,
+ bool bIsNegative,
int64_t nBase10Exponent);
-static void QCBOREncode_AddTDecimalFractionToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- int64_t nMantissa,
- int64_t nBase10Exponent);
-static void QCBOREncode_AddTDecimalFractionToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- int64_t nMantissa,
- int64_t nBase10Exponent);
+static void
+QCBOREncode_AddDecimalFractionBigNum(QCBOREncodeContext *pCtx,
+ UsefulBufC Mantissa,
+ bool bIsNegative,
+ int64_t nBase10Exponent);
-
-static void QCBOREncode_AddDecimalFraction(QCBOREncodeContext *pCtx,
- int64_t nMantissa,
- int64_t nBase10Exponent);
-
-static void QCBOREncode_AddDecimalFractionToMap(QCBOREncodeContext *pCtx,
- const char *szLabel,
- int64_t nMantissa,
- int64_t nBase10Exponent);
-
-static void QCBOREncode_AddDecimalFractionToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- int64_t nMantissa,
- int64_t nBase10Exponent);
-/**
- @brief Add a decimal fraction with a big number mantissa to the encoded output.
-
- @param[in] pCtx The encoding context to add the decimal fraction to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] Mantissa The mantissa.
- @param[in] bIsNegative false if mantissa is positive, true if negative.
- @param[in] nBase10Exponent The exponent.
-
- This is the same as QCBOREncode_AddDecimalFraction() except the
- mantissa is a big number (See QCBOREncode_AddPositiveBignum())
- allowing for arbitrarily large precision.
-
- See @ref expAndMantissa for decoded representation.
- */
-static void QCBOREncode_AddTDecimalFractionBigNum(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC Mantissa,
- bool bIsNegative,
- int64_t nBase10Exponent);
-
-static void QCBOREncode_AddTDecimalFractionBigNumToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC Mantissa,
- bool bIsNegative,
- int64_t nBase10Exponent);
-
-static void QCBOREncode_AddTDecimalFractionBigNumToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC Mantissa,
- bool bIsNegative,
- int64_t nBase10Exponent);
-
-
-static void QCBOREncode_AddDecimalFractionBigNum(QCBOREncodeContext *pCtx,
- UsefulBufC Mantissa,
- bool bIsNegative,
- int64_t nBase10Exponent);
-
-static void QCBOREncode_AddDecimalFractionBigNumToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- UsefulBufC Mantissa,
- bool bIsNegative,
- int64_t nBase10Exponent);
-
-static void QCBOREncode_AddDecimalFractionBigNumToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- UsefulBufC Mantissa,
- bool bIsNegative,
- int64_t nBase10Exponent);
-
-/**
- @brief Add a big floating-point number to the encoded output.
-
- @param[in] pCtx The encoding context to add the bigfloat to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] nMantissa The mantissa.
- @param[in] nBase2Exponent The exponent.
-
- The value is nMantissa * 2 ^ nBase2Exponent.
-
- "Bigfloats", as CBOR terms them, are similar to IEEE floating-point
- numbers in having a mantissa and base-2 exponent, but they are not
- supported by hardware or encoded the same. They explicitly use two
- CBOR-encoded integers to convey the mantissa and exponent, each of which
- can be 8, 16, 32 or 64 bits. With both the mantissa and exponent
- 64 bits they can express more precision and a larger range than an
- IEEE double floating-point number. See
- QCBOREncode_AddBigFloatBigNum() for even more precision.
-
- For example, 1.5 would be represented by a mantissa of 3 and an
- exponent of -1.
-
- The exponent and mantissa have the range from @c INT64_MIN to
- @c INT64_MAX for both encoding and decoding (CBOR allows @c -UINT64_MAX
- to @c UINT64_MAX, but this implementation doesn't support this range to
- reduce code size and interface complexity a little).
-
- CBOR Preferred encoding of the integers is used, thus they will be encoded
- in the smallest number of bytes possible.
-
- This can also be used to represent floating-point numbers in
- environments that don't support IEEE 754.
-
- See @ref expAndMantissa for decoded representation.
- */
-static void QCBOREncode_AddTBigFloat(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
- int64_t nMantissa,
- int64_t nBase2Exponent);
-
-static void QCBOREncode_AddTBigFloatToMapSZ(QCBOREncodeContext *pCtx,
+static void
+QCBOREncode_AddDecimalFractionBigNumToMapSZ(QCBOREncodeContext *pCtx,
const char *szLabel,
- uint8_t uTagRequirement,
- int64_t nMantissa,
- int64_t nBase2Exponent);
+ UsefulBufC Mantissa,
+ bool bIsNegative,
+ int64_t nBase10Exponent);
-static void QCBOREncode_AddTBigFloatToMapN(QCBOREncodeContext *pCtx,
+static void
+QCBOREncode_AddDecimalFractionBigNumToMapN(QCBOREncodeContext *pCtx,
int64_t nLabel,
- uint8_t uTagRequirement,
- int64_t nMantissa,
- int64_t nBase2Exponent);
-
-
-static void QCBOREncode_AddBigFloat(QCBOREncodeContext *pCtx,
- int64_t nMantissa,
- int64_t nBase2Exponent);
-
-static void QCBOREncode_AddBigFloatToMap(QCBOREncodeContext *pCtx,
- const char *szLabel,
- int64_t nMantissa,
- int64_t nBase2Exponent);
-
-static void QCBOREncode_AddBigFloatToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- int64_t nMantissa,
- int64_t nBase2Exponent);
-
-/**
- @brief Add a big floating-point number with a big number mantissa to
- the encoded output.
-
- @param[in] pCtx The encoding context to add the bigfloat to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] Mantissa The mantissa.
- @param[in] bIsNegative false if mantissa is positive, true if negative.
- @param[in] nBase2Exponent The exponent.
-
- This is the same as QCBOREncode_AddBigFloat() except the mantissa is
- a big number (See QCBOREncode_AddPositiveBignum()) allowing for
- arbitrary precision.
-
- See @ref expAndMantissa for decoded representation.
- */
-static void QCBOREncode_AddTBigFloatBigNum(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
UsefulBufC Mantissa,
bool bIsNegative,
- int64_t nBase2Exponent);
+ int64_t nBase10Exponent);
-static void QCBOREncode_AddTBigFloatBigNumToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC Mantissa,
- bool bIsNegative,
- int64_t nBase2Exponent);
+/**
+ * @brief Add a big floating-point number to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the bigfloat to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] nMantissa The mantissa.
+ * @param[in] nBase2Exponent The exponent.
+ *
+ * The value is nMantissa * 2 ^ nBase2Exponent.
+ *
+ * "Bigfloats", as CBOR terms them, are similar to IEEE floating-point
+ * numbers in having a mantissa and base-2 exponent, but they are not
+ * supported by hardware or encoded the same. They explicitly use two
+ * CBOR-encoded integers to convey the mantissa and exponent, each of
+ * which can be 8, 16, 32 or 64 bits. With both the mantissa and
+ * exponent 64 bits they can express more precision and a larger range
+ * than an IEEE double floating-point number. See
+ * QCBOREncode_AddBigFloatBigNum() for even more precision.
+ *
+ * For example, 1.5 would be represented by a mantissa of 3 and an
+ * exponent of -1.
+ *
+ * The exponent and mantissa have the range from @c INT64_MIN to
+ * @c INT64_MAX for both encoding and decoding (CBOR allows @c
+ * -UINT64_MAX to @c UINT64_MAX, but this implementation doesn't
+ * support this range to reduce code size and interface complexity a
+ * little).
+ *
+ * CBOR preferred serialization of the integers is used, thus they will
+ * be encoded in the smallest number of bytes possible.
+ *
+ * This can also be used to represent floating-point numbers in
+ * environments that don't support IEEE 754.
+ *
+ * See @ref expAndMantissa for decoded representation.
+ */
+static void
+QCBOREncode_AddTBigFloat(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ int64_t nMantissa,
+ int64_t nBase2Exponent);
-static void QCBOREncode_AddTBigFloatBigNumToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC Mantissa,
- bool bIsNegative,
- int64_t nBase2Exponent);
+static void
+QCBOREncode_AddTBigFloatToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ int64_t nMantissa,
+ int64_t nBase2Exponent);
+
+static void
+QCBOREncode_AddTBigFloatToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ int64_t nMantissa,
+ int64_t nBase2Exponent);
-static void QCBOREncode_AddBigFloatBigNum(QCBOREncodeContext *pCtx,
- UsefulBufC Mantissa,
- bool bIsNegative,
- int64_t nBase2Exponent);
+static void
+QCBOREncode_AddBigFloat(QCBOREncodeContext *pCtx,
+ int64_t nMantissa,
+ int64_t nBase2Exponent);
-static void QCBOREncode_AddBigFloatBigNumToMap(QCBOREncodeContext *pCtx,
- const char *szLabel,
- UsefulBufC Mantissa,
- bool bIsNegative,
- int64_t nBase2Exponent);
+static void
+QCBOREncode_AddBigFloatToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ int64_t nMantissa,
+ int64_t nBase2Exponent);
-static void QCBOREncode_AddBigFloatBigNumToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- UsefulBufC Mantissa,
- bool bIsNegative,
- int64_t nBase2Exponent);
+static void
+QCBOREncode_AddBigFloatToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ int64_t nMantissa,
+ int64_t nBase2Exponent);
+
+/**
+ * @brief Add a big floating-point number with a big number mantissa to
+ * the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the bigfloat to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] Mantissa The mantissa.
+ * @param[in] bIsNegative false if mantissa is positive, true if negative.
+ * @param[in] nBase2Exponent The exponent.
+ *
+ * This is the same as QCBOREncode_AddBigFloat() except the mantissa
+ * is a big number (See QCBOREncode_AddPositiveBignum()) allowing for
+ * arbitrary precision.
+ *
+ * See @ref expAndMantissa for decoded representation.
+ */
+static void
+QCBOREncode_AddTBigFloatBigNum(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC Mantissa,
+ bool bIsNegative,
+ int64_t nBase2Exponent);
+
+static void
+QCBOREncode_AddTBigFloatBigNumToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Mantissa,
+ bool bIsNegative,
+ int64_t nBase2Exponent);
+
+static void
+QCBOREncode_AddTBigFloatBigNumToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Mantissa,
+ bool bIsNegative,
+ int64_t nBase2Exponent);
+
+
+static void
+QCBOREncode_AddBigFloatBigNum(QCBOREncodeContext *pCtx,
+ UsefulBufC Mantissa,
+ bool bIsNegative,
+ int64_t nBase2Exponent);
+
+static void
+QCBOREncode_AddBigFloatBigNumToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ UsefulBufC Mantissa,
+ bool bIsNegative,
+ int64_t nBase2Exponent);
+
+static void
+QCBOREncode_AddBigFloatBigNumToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ UsefulBufC Mantissa,
+ bool bIsNegative,
+ int64_t nBase2Exponent);
#endif /* QCBOR_DISABLE_EXP_AND_MANTISSA */
/**
- @brief Add a text URI to the encoded output.
-
- @param[in] pCtx The encoding context to add the URI to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] URI Pointer and length of the URI.
-
- The format of URI must be per [RFC 3986]
- (https://tools.ietf.org/html/rfc3986).
-
- It is output as CBOR major type 3, a text string, with tag @ref
- CBOR_TAG_URI indicating the text string is a URI.
-
- A URI in a NULL-terminated string, @c szURI, can be easily added with
- this code:
-
- QCBOREncode_AddURI(pCtx, UsefulBuf_FromSZ(szURI));
+ * @brief Add a text URI to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the URI to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] URI Pointer and length of the URI.
+ *
+ * The format of URI must be per [RFC 3986]
+ * (https://tools.ietf.org/html/rfc3986).
+ *
+ * It is output as CBOR major type 3, a text string, with tag @ref
+ * CBOR_TAG_URI indicating the text string is a URI.
+ *
+ * A URI in a NULL-terminated string, @c szURI, can be easily added with
+ * this code:
+ *
+ * QCBOREncode_AddURI(pCtx, UsefulBuf_FromSZ(szURI));
*/
-static void QCBOREncode_AddTURI(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC URI);
+static void
+QCBOREncode_AddTURI(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC URI);
-static void QCBOREncode_AddTURIToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC URI);
+static void
+QCBOREncode_AddTURIToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC URI);
-static void QCBOREncode_AddTURIToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC URI);
+static void
+QCBOREncode_AddTURIToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC URI);
-static void QCBOREncode_AddURI(QCBOREncodeContext *pCtx,
- UsefulBufC URI);
+static void
+QCBOREncode_AddURI(QCBOREncodeContext *pCtx,
+ UsefulBufC URI);
-static void QCBOREncode_AddURIToMap(QCBOREncodeContext *pCtx,
- const char *szLabel,
- UsefulBufC URI);
+static void
+QCBOREncode_AddURIToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ UsefulBufC URI);
-static void QCBOREncode_AddURIToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- UsefulBufC URI);
+static void
+QCBOREncode_AddURIToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ UsefulBufC URI);
/**
- @brief Add Base64-encoded text to encoded output.
-
- @param[in] pCtx The encoding context to add the base-64 text to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] B64Text Pointer and length of the base-64 encoded text.
-
- The text content is Base64 encoded data per [RFC 4648]
- (https://tools.ietf.org/html/rfc4648).
-
- It is output as CBOR major type 3, a text string, with tag @ref
- CBOR_TAG_B64 indicating the text string is Base64 encoded.
+ * @brief Add Base64-encoded text to encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the base-64 text to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] B64Text Pointer and length of the base-64 encoded text.
+ *
+ * The text content is Base64 encoded data per [RFC 4648]
+ * (https://tools.ietf.org/html/rfc4648).
+ *
+ * It is output as CBOR major type 3, a text string, with tag @ref
+ * CBOR_TAG_B64 indicating the text string is Base64 encoded.
*/
-static void QCBOREncode_AddTB64Text(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
+static void
+QCBOREncode_AddTB64Text(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
UsefulBufC B64Text);
-static void QCBOREncode_AddTB64TextToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC B64Text);
+static void
+QCBOREncode_AddTB64TextToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC B64Text);
-static void QCBOREncode_AddTB64TextToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC B64Text);
+static void
+QCBOREncode_AddTB64TextToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC B64Text);
-static void QCBOREncode_AddB64Text(QCBOREncodeContext *pCtx,
- UsefulBufC B64Text);
+static void
+QCBOREncode_AddB64Text(QCBOREncodeContext *pCtx,
+ UsefulBufC B64Text);
-static void QCBOREncode_AddB64TextToMap(QCBOREncodeContext *pCtx,
- const char *szLabel,
- UsefulBufC B64Text);
+static void
+QCBOREncode_AddB64TextToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ UsefulBufC B64Text);
-static void QCBOREncode_AddB64TextToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- UsefulBufC B64Text);
+static void
+QCBOREncode_AddB64TextToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ UsefulBufC B64Text);
/**
- @brief Add base64url encoded data to encoded output.
-
- @param[in] pCtx The encoding context to add the base64url to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] B64Text Pointer and length of the base64url encoded text.
-
- The text content is base64URL encoded text as per [RFC 4648]
- (https://tools.ietf.org/html/rfc4648).
-
- It is output as CBOR major type 3, a text string, with tag @ref
- CBOR_TAG_B64URL indicating the text string is a Base64url encoded.
+ * @brief Add base64url encoded data to encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the base64url to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] B64Text Pointer and length of the base64url encoded text.
+ *
+ * The text content is base64URL encoded text as per [RFC 4648]
+ * (https://tools.ietf.org/html/rfc4648).
+ *
+ * It is output as CBOR major type 3, a text string, with tag
+ * @ref CBOR_TAG_B64URL indicating the text string is a Base64url
+ * encoded.
*/
-static void QCBOREncode_AddTB64URLText(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC B64Text);
+static void
+QCBOREncode_AddTB64URLText(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC B64Text);
-static void QCBOREncode_AddTB64URLTextToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC B64Text);
+static void
+QCBOREncode_AddTB64URLTextToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC B64Text);
-static void QCBOREncode_AddTB64URLTextToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC B64Text);
+static void
+QCBOREncode_AddTB64URLTextToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC B64Text);
-static void QCBOREncode_AddB64URLText(QCBOREncodeContext *pCtx,
- UsefulBufC B64Text);
+static void
+QCBOREncode_AddB64URLText(QCBOREncodeContext *pCtx,
+ UsefulBufC B64Text);
-static void QCBOREncode_AddB64URLTextToMap(QCBOREncodeContext *pCtx,
- const char *szLabel,
- UsefulBufC B64Text);
+static void
+QCBOREncode_AddB64URLTextToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ UsefulBufC B64Text);
-static void QCBOREncode_AddB64URLTextToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- UsefulBufC B64Text);
+static void
+QCBOREncode_AddB64URLTextToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ UsefulBufC B64Text);
/**
- @brief Add Perl Compatible Regular Expression.
-
- @param[in] pCtx The encoding context to add the regular expression to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] Regex Pointer and length of the regular expression.
-
- The text content is Perl Compatible Regular
- Expressions (PCRE) / JavaScript syntax [ECMA262].
-
- It is output as CBOR major type 3, a text string, with tag @ref
- CBOR_TAG_REGEX indicating the text string is a regular expression.
+ * @brief Add Perl Compatible Regular Expression.
+ *
+ * @param[in] pCtx Encoding context to add the regular expression to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] Regex Pointer and length of the regular expression.
+ *
+ * The text content is Perl Compatible Regular
+ * Expressions (PCRE) / JavaScript syntax [ECMA262].
+ *
+ * It is output as CBOR major type 3, a text string, with tag @ref
+ * CBOR_TAG_REGEX indicating the text string is a regular expression.
*/
-static void QCBOREncode_AddTRegex(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC Regex);
+static void
+QCBOREncode_AddTRegex(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC Regex);
-static void QCBOREncode_AddTRegexToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC Regex);
+static void
+QCBOREncode_AddTRegexToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Regex);
-static void QCBOREncode_AddTRegexToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC Regex);
+static void
+QCBOREncode_AddTRegexToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Regex);
-static void QCBOREncode_AddRegex(QCBOREncodeContext *pCtx,
- UsefulBufC Regex);
+static void
+QCBOREncode_AddRegex(QCBOREncodeContext *pCtx,
+ UsefulBufC Regex);
-static void QCBOREncode_AddRegexToMap(QCBOREncodeContext *pCtx,
- const char *szLabel,
- UsefulBufC Regex);
+static void
+QCBOREncode_AddRegexToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ UsefulBufC Regex);
-static void QCBOREncode_AddRegexToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- UsefulBufC Regex);
+static void
+QCBOREncode_AddRegexToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ UsefulBufC Regex);
/**
- @brief MIME encoded data to the encoded output.
-
- @param[in] pCtx The encoding context to add the MIME data to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
- @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] MIMEData Pointer and length of the MIME data.
-
- The text content is in MIME format per [RFC 2045]
- (https://tools.ietf.org/html/rfc2045) including the headers.
-
- It is output as CBOR major type 2, a binary string, with tag @ref
- CBOR_TAG_BINARY_MIME indicating the string is MIME data. This
- outputs tag 257, not tag 36, as it can carry any type of MIME binary,
- 7-bit, 8-bit, quoted-printable and base64 where tag 36 cannot.
-
- Previous versions of QCBOR, those before spiffy decode, output tag
- 36. Decoding supports both tag 36 and 257. (if the old behavior with
- tag 36 is needed, copy the inline functions below and change the tag
- number).
-
- See also QCBORDecode_GetMIMEMessage() and
- @ref QCBOR_TYPE_BINARY_MIME.
-
- This does no translation of line endings. See QCBOREncode_AddText()
- for a discussion of line endings in CBOR.
+ * @brief MIME encoded data to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the MIME data to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] MIMEData Pointer and length of the MIME data.
+ *
+ * The text content is in MIME format per [RFC 2045]
+ * (https://tools.ietf.org/html/rfc2045) including the headers.
+ *
+ * It is output as CBOR major type 2, a binary string, with tag
+ * @ref CBOR_TAG_BINARY_MIME indicating the string is MIME data. This
+ * outputs tag 257, not tag 36, as it can carry any type of MIME
+ * binary, 7-bit, 8-bit, quoted-printable and base64 where tag 36
+ * cannot.
+ *
+ * Previous versions of QCBOR, those before spiffy decode, output tag
+ * 36. Decoding supports both tag 36 and 257. (if the old behavior
+ * with tag 36 is needed, copy the inline functions below and change
+ * the tag number).
+ *
+ * See also QCBORDecode_GetMIMEMessage() and
+ * @ref QCBOR_TYPE_BINARY_MIME.
+ *
+ * This does no translation of line endings. See QCBOREncode_AddText()
+ * for a discussion of line endings in CBOR.
*/
-static void QCBOREncode_AddTMIMEData(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC MIMEData);
+static void
+QCBOREncode_AddTMIMEData(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC MIMEData);
-static void QCBOREncode_AddTMIMEDataToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC MIMEData);
+static void
+QCBOREncode_AddTMIMEDataToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC MIMEData);
-static void QCBOREncode_AddTMIMEDataToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC MIMEData);
+static void
+QCBOREncode_AddTMIMEDataToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC MIMEData);
-static void QCBOREncode_AddMIMEData(QCBOREncodeContext *pCtx,
- UsefulBufC MIMEData);
+static void
+QCBOREncode_AddMIMEData(QCBOREncodeContext *pCtx,
+ UsefulBufC MIMEData);
-static void QCBOREncode_AddMIMEDataToMap(QCBOREncodeContext *pCtx,
- const char *szLabel,
- UsefulBufC MIMEData);
+static void
+QCBOREncode_AddMIMEDataToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ UsefulBufC MIMEData);
-static void QCBOREncode_AddMIMEDataToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- UsefulBufC MIMEData);
+static void
+QCBOREncode_AddMIMEDataToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ UsefulBufC MIMEData);
/**
- @brief Add an RFC 3339 date string
-
- @param[in] pCtx The encoding context to add the date to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] szDate Null-terminated string with date to add.
-
- The string szDate should be in the form of [RFC 3339]
- (https://tools.ietf.org/html/rfc3339) as defined by section 3.3 in
- [RFC 4287] (https://tools.ietf.org/html/rfc4287). This is as
- described in section 3.4.1 in [RFC 8949]
- (https://tools.ietf.org/html/rfc8949).
-
- Note that this function doesn't validate the format of the date string
- at all. If you add an incorrect format date string, the generated
- CBOR will be incorrect and the receiver may not be able to handle it.
-
- Error handling is the same as QCBOREncode_AddInt64().
-
- See also QCBOREncode_AddTDayString().
+ * @brief Add an RFC 3339 date string
+ *
+ * @param[in] pCtx The encoding context to add the date to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] szDate Null-terminated string with date to add.
+ *
+ * The string szDate should be in the form of [RFC 3339]
+ * (https://tools.ietf.org/html/rfc3339) as defined by section 3.3 in
+ * [RFC 4287] (https://tools.ietf.org/html/rfc4287). This is as
+ * described in section 3.4.1 in [RFC 8949]
+ * (https://tools.ietf.org/html/rfc8949).
+ *
+ * Note that this function doesn't validate the format of the date
+ * string at all. If you add an incorrect format date string, the
+ * generated CBOR will be incorrect and the receiver may not be able
+ * to handle it.
+ *
+ * Error handling is the same as QCBOREncode_AddInt64().
+ *
+ * See also QCBOREncode_AddTDayString().
*/
-static void QCBOREncode_AddTDateString(QCBOREncodeContext *pCtx,
- uint8_t uTagRequirement,
- const char *szDate);
+static void
+QCBOREncode_AddTDateString(QCBOREncodeContext *pCtx,
+ uint8_t uTagRequirement,
+ const char *szDate);
-static void QCBOREncode_AddTDateStringToMapSZ(QCBOREncodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- const char *szDate);
+static void
+QCBOREncode_AddTDateStringToMapSZ(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ const char *szDate);
-static void QCBOREncode_AddTDateStringToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- const char *szDate);
+static void
+QCBOREncode_AddTDateStringToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ const char *szDate);
-static void QCBOREncode_AddDateString(QCBOREncodeContext *pCtx,
- const char *szDate);
+static void
+QCBOREncode_AddDateString(QCBOREncodeContext *pCtx,
+ const char *szDate);
-static void QCBOREncode_AddDateStringToMap(QCBOREncodeContext *pCtx,
- const char *szLabel,
- const char *szDate);
+static void
+QCBOREncode_AddDateStringToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ const char *szDate);
-static void QCBOREncode_AddDateStringToMapN(QCBOREncodeContext *pCtx,
- int64_t nLabel,
- const char *szDate);
+static void
+QCBOREncode_AddDateStringToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ const char *szDate);
/**
- @brief Add a date-only string.
-
- @param[in] pCtx The encoding context to add the date to.
- @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
- @ref QCBOR_ENCODE_AS_BORROWED.
- @param[in] szDate Null-terminated string with date to add.
-
- This date format is described in
- [RFC 8943] (https://tools.ietf.org/html/rfc8943), but that mainly
- references RFC 3339. The string szDate must be in the forrm
- specified the ABNF for a full-date in
- [RFC 3339] (https://tools.ietf.org/html/rfc3339). Examples of this
- are "1985-04-12" and "1937-01-01". The time and the time zone are
- never included.
-
- Note that this function doesn't validate the format of the date
- string at all. If you add an incorrect format date string, the
- generated CBOR will be incorrect and the receiver may not be able to
- handle it.
-
- Error handling is the same as QCBOREncode_AddInt64().
-
- See also QCBOREncode_AddTDateString().
+ * @brief Add a date-only string.
+ *
+ * @param[in] pCtx The encoding context to add the date to.
+ * @param[in] uTagRequirement Either @ref QCBOR_ENCODE_AS_TAG or
+ * @ref QCBOR_ENCODE_AS_BORROWED.
+ * @param[in] szDate Null-terminated string with date to add.
+ *
+ * This date format is described in
+ * [RFC 8943] (https://tools.ietf.org/html/rfc8943), but that mainly
+ * references RFC 3339. The string szDate must be in the forrm
+ * specified the ABNF for a full-date in
+ * [RFC 3339] (https://tools.ietf.org/html/rfc3339). Examples of this
+ * are "1985-04-12" and "1937-01-01". The time and the time zone are
+ * never included.
+ *
+ * Note that this function doesn't validate the format of the date
+ * string at all. If you add an incorrect format date string, the
+ * generated CBOR will be incorrect and the receiver may not be able
+ * to handle it.
+ *
+ * Error handling is the same as QCBOREncode_AddInt64().
+ *
+ * See also QCBOREncode_AddTDateString().
*/
static void
QCBOREncode_AddTDaysString(QCBOREncodeContext *pCtx,
@@ -1578,185 +1727,205 @@
/**
- @brief Add a standard Boolean.
-
- @param[in] pCtx The encoding context to add the Boolean to.
- @param[in] b true or false from @c <stdbool.h>.
-
- Adds a Boolean value as CBOR major type 7.
-
- Error handling is the same as QCBOREncode_AddInt64().
+ * @brief Add a standard Boolean.
+ *
+ * @param[in] pCtx The encoding context to add the Boolean to.
+ * @param[in] b true or false from @c <stdbool.h>.
+ *
+ * Adds a Boolean value as CBOR major type 7.
+ *
+ * Error handling is the same as QCBOREncode_AddInt64().
*/
-static void QCBOREncode_AddBool(QCBOREncodeContext *pCtx, bool b);
+static void
+QCBOREncode_AddBool(QCBOREncodeContext *pCtx, bool b);
-static void QCBOREncode_AddBoolToMap(QCBOREncodeContext *pCtx, const char *szLabel, bool b);
+static void
+QCBOREncode_AddBoolToMap(QCBOREncodeContext *pCtx, const char *szLabel, bool b);
-static void QCBOREncode_AddBoolToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, bool b);
+static void
+QCBOREncode_AddBoolToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, bool b);
/**
- @brief Add a NULL to the encoded output.
-
- @param[in] pCtx The encoding context to add the NULL to.
-
- Adds the NULL value as CBOR major type 7.
-
- This NULL doesn't have any special meaning in CBOR such as a
- terminating value for a string or an empty value.
-
- Error handling is the same as QCBOREncode_AddInt64().
+ * @brief Add a NULL to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the NULL to.
+ *
+ * Adds the NULL value as CBOR major type 7.
+ *
+ * This NULL doesn't have any special meaning in CBOR such as a
+ * terminating value for a string or an empty value.
+ *
+ * Error handling is the same as QCBOREncode_AddInt64().
*/
-static void QCBOREncode_AddNULL(QCBOREncodeContext *pCtx);
+static void
+QCBOREncode_AddNULL(QCBOREncodeContext *pCtx);
-static void QCBOREncode_AddNULLToMap(QCBOREncodeContext *pCtx, const char *szLabel);
+static void
+QCBOREncode_AddNULLToMap(QCBOREncodeContext *pCtx, const char *szLabel);
-static void QCBOREncode_AddNULLToMapN(QCBOREncodeContext *pCtx, int64_t nLabel);
+static void
+QCBOREncode_AddNULLToMapN(QCBOREncodeContext *pCtx, int64_t nLabel);
/**
- @brief Add an "undef" to the encoded output.
-
- @param[in] pCtx The encoding context to add the "undef" to.
-
- Adds the undef value as CBOR major type 7.
-
- Note that this value will not translate to JSON.
-
- This Undef doesn't have any special meaning in CBOR such as a
- terminating value for a string or an empty value.
-
- Error handling is the same as QCBOREncode_AddInt64().
+ * @brief Add an "undef" to the encoded output.
+ *
+ * @param[in] pCtx The encoding context to add the "undef" to.
+ *
+ * Adds the undef value as CBOR major type 7.
+ *
+ * Note that this value will not translate to JSON.
+ *
+ * This Undef doesn't have any special meaning in CBOR such as a
+ * terminating value for a string or an empty value.
+ *
+ * Error handling is the same as QCBOREncode_AddInt64().
*/
-static void QCBOREncode_AddUndef(QCBOREncodeContext *pCtx);
+static void
+QCBOREncode_AddUndef(QCBOREncodeContext *pCtx);
-static void QCBOREncode_AddUndefToMap(QCBOREncodeContext *pCtx, const char *szLabel);
+static void
+QCBOREncode_AddUndefToMap(QCBOREncodeContext *pCtx, const char *szLabel);
-static void QCBOREncode_AddUndefToMapN(QCBOREncodeContext *pCtx, int64_t nLabel);
+static void
+QCBOREncode_AddUndefToMapN(QCBOREncodeContext *pCtx, int64_t nLabel);
/**
- @brief Indicates that the next items added are in an array.
-
- @param[in] pCtx The encoding context to open the array in.
-
- Arrays are the basic CBOR aggregate or structure type. Call this
- function to start or open an array. Then call the various @c
- QCBOREncode_AddXxx() functions to add the items that go into the
- array. Then call QCBOREncode_CloseArray() when all items have been
- added. The data items in the array can be of any type and can be of
- mixed types.
-
- Nesting of arrays and maps is allowed and supported just by calling
- QCBOREncode_OpenArray() again before calling
- QCBOREncode_CloseArray(). While CBOR has no limit on nesting, this
- implementation does in order to keep it smaller and simpler. The
- limit is @ref QCBOR_MAX_ARRAY_NESTING. This is the max number of
- times this can be called without calling
- QCBOREncode_CloseArray(). QCBOREncode_Finish() will return @ref
- QCBOR_ERR_ARRAY_NESTING_TOO_DEEP when it is called as this function
- just sets an error state and returns no value when this occurs.
-
- If you try to add more than @ref QCBOR_MAX_ITEMS_IN_ARRAY items to a
- single array or map, @ref QCBOR_ERR_ARRAY_TOO_LONG will be returned
- when QCBOREncode_Finish() is called.
-
- An array itself must have a label if it is being added to a map.
- Note that array elements do not have labels (but map elements do).
-
- An array itself may be tagged by calling QCBOREncode_AddTag() before this call.
+ * @brief Indicates that the next items added are in an array.
+ *
+ * @param[in] pCtx The encoding context to open the array in.
+ *
+ * Arrays are the basic CBOR aggregate or structure type. Call this
+ * function to start or open an array. Then call the various
+ * @c QCBOREncode_AddXxx() functions to add the items that go into the
+ * array. Then call QCBOREncode_CloseArray() when all items have been
+ * added. The data items in the array can be of any type and can be of
+ * mixed types.
+ *
+ * Nesting of arrays and maps is allowed and supported just by calling
+ * QCBOREncode_OpenArray() again before calling
+ * QCBOREncode_CloseArray(). While CBOR has no limit on nesting, this
+ * implementation does in order to keep it smaller and simpler. The
+ * limit is @ref QCBOR_MAX_ARRAY_NESTING. This is the max number of
+ * times this can be called without calling
+ * QCBOREncode_CloseArray(). QCBOREncode_Finish() will return
+ * @ref QCBOR_ERR_ARRAY_NESTING_TOO_DEEP when it is called as this
+ * function just sets an error state and returns no value when this
+ * occurs.
+ *
+ * If you try to add more than @ref QCBOR_MAX_ITEMS_IN_ARRAY items to
+ * a single array or map, @ref QCBOR_ERR_ARRAY_TOO_LONG will be
+ * returned when QCBOREncode_Finish() is called.
+ *
+ * An array itself must have a label if it is being added to a map.
+ * Note that array elements do not have labels (but map elements do).
+ *
+ * An array itself may be tagged by calling QCBOREncode_AddTag()
+ * before this call.
*/
-static void QCBOREncode_OpenArray(QCBOREncodeContext *pCtx);
+static void
+QCBOREncode_OpenArray(QCBOREncodeContext *pCtx);
-static void QCBOREncode_OpenArrayInMap(QCBOREncodeContext *pCtx, const char *szLabel);
+static void
+QCBOREncode_OpenArrayInMap(QCBOREncodeContext *pCtx, const char *szLabel);
-static void QCBOREncode_OpenArrayInMapN(QCBOREncodeContext *pCtx, int64_t nLabel);
+static void
+QCBOREncode_OpenArrayInMapN(QCBOREncodeContext *pCtx, int64_t nLabel);
/**
- @brief Close an open array.
-
- @param[in] pCtx The encoding context to close the array in.
-
- The closes an array opened by QCBOREncode_OpenArray(). It reduces
- nesting level by one. All arrays (and maps) must be closed before
- calling QCBOREncode_Finish().
-
- When an error occurs as a result of this call, the encoder records
- the error and enters the error state. The error will be returned when
- QCBOREncode_Finish() is called.
-
- If this has been called more times than QCBOREncode_OpenArray(), then
- @ref QCBOR_ERR_TOO_MANY_CLOSES will be returned when QCBOREncode_Finish()
- is called.
-
- If this is called and it is not an array that is currently open, @ref
- QCBOR_ERR_CLOSE_MISMATCH will be returned when QCBOREncode_Finish()
- is called.
+ * @brief Close an open array.
+ *
+ * @param[in] pCtx The encoding context to close the array in.
+ *
+ * The closes an array opened by QCBOREncode_OpenArray(). It reduces
+ * nesting level by one. All arrays (and maps) must be closed before
+ * calling QCBOREncode_Finish().
+ *
+ * When an error occurs as a result of this call, the encoder records
+ * the error and enters the error state. The error will be returned
+ * when QCBOREncode_Finish() is called.
+ *
+ * If this has been called more times than QCBOREncode_OpenArray(), then
+ * @ref QCBOR_ERR_TOO_MANY_CLOSES will be returned when QCBOREncode_Finish()
+ * is called.
+ *
+ * If this is called and it is not an array that is currently open,
+ * @ref QCBOR_ERR_CLOSE_MISMATCH will be returned when
+ * QCBOREncode_Finish() is called.
*/
-static void QCBOREncode_CloseArray(QCBOREncodeContext *pCtx);
+static void
+QCBOREncode_CloseArray(QCBOREncodeContext *pCtx);
/**
- @brief Indicates that the next items added are in a map.
-
- @param[in] pCtx The encoding context to open the map in.
-
- See QCBOREncode_OpenArray() for more information, particularly error
- handling.
-
- CBOR maps are an aggregate type where each item in the map consists
- of a label and a value. They are similar to JSON objects.
-
- The value can be any CBOR type including another map.
-
- The label can also be any CBOR type, but in practice they are
- typically, integers as this gives the most compact output. They might
- also be text strings which gives readability and translation to JSON.
-
- Every @c QCBOREncode_AddXxx() call has one version that ends with @c
- InMap for adding items to maps with string labels and one that ends
- with @c InMapN that is for adding with integer labels.
-
- RFC 8949 uses the term "key" instead of "label".
-
- If you wish to use map labels that are neither integer labels nor
- text strings, then just call the QCBOREncode_AddXxx() function
- explicitly to add the label. Then call it again to add the value.
-
- See the [RFC 8949] (https://tools.ietf.org/html/rfc8949) for a lot
- more information on creating maps.
+ * @brief Indicates that the next items added are in a map.
+ *
+ * @param[in] pCtx The encoding context to open the map in.
+ *
+ * See QCBOREncode_OpenArray() for more information, particularly
+ * error handling.
+ *
+ * CBOR maps are an aggregate type where each item in the map consists
+ * of a label and a value. They are similar to JSON objects.
+ *
+ * The value can be any CBOR type including another map.
+ *
+ * The label can also be any CBOR type, but in practice they are
+ * typically, integers as this gives the most compact output. They
+ * might also be text strings which gives readability and translation
+ * to JSON.
+ *
+ * Every @c QCBOREncode_AddXxx() call has one version that ends with
+ * @c InMap for adding items to maps with string labels and one that
+ * ends with @c InMapN that is for adding with integer labels.
+ *
+ * RFC 8949 uses the term "key" instead of "label".
+ *
+ * If you wish to use map labels that are neither integer labels nor
+ * text strings, then just call the QCBOREncode_AddXxx() function
+ * explicitly to add the label. Then call it again to add the value.
+ *
+ * See the [RFC 8949] (https://tools.ietf.org/html/rfc8949) for a lot
+ * more information on creating maps.
*/
-static void QCBOREncode_OpenMap(QCBOREncodeContext *pCtx);
+static void
+QCBOREncode_OpenMap(QCBOREncodeContext *pCtx);
-static void QCBOREncode_OpenMapInMap(QCBOREncodeContext *pCtx, const char *szLabel);
+static void
+QCBOREncode_OpenMapInMap(QCBOREncodeContext *pCtx, const char *szLabel);
-static void QCBOREncode_OpenMapInMapN(QCBOREncodeContext *pCtx, int64_t nLabel);
+static void
+QCBOREncode_OpenMapInMapN(QCBOREncodeContext *pCtx, int64_t nLabel);
/**
- @brief Close an open map.
-
- @param[in] pCtx The encoding context to close the map in .
-
- This closes a map opened by QCBOREncode_OpenMap(). It reduces nesting
- level by one.
-
- When an error occurs as a result of this call, the encoder records
- the error and enters the error state. The error will be returned when
- QCBOREncode_Finish() is called.
-
- If this has been called more times than QCBOREncode_OpenMap(),
- then @ref QCBOR_ERR_TOO_MANY_CLOSES will be returned when
- QCBOREncode_Finish() is called.
-
- If this is called and it is not a map that is currently open, @ref
- QCBOR_ERR_CLOSE_MISMATCH will be returned when QCBOREncode_Finish()
- is called.
+ * @brief Close an open map.
+ *
+ * @param[in] pCtx The encoding context to close the map in.
+ *
+ * This closes a map opened by QCBOREncode_OpenMap(). It reduces
+ * nesting level by one.
+ *
+ * When an error occurs as a result of this call, the encoder records
+ * the error and enters the error state. The error will be returned
+ * when QCBOREncode_Finish() is called.
+ *
+ * If this has been called more times than QCBOREncode_OpenMap(), then
+ * @ref QCBOR_ERR_TOO_MANY_CLOSES will be returned when
+ * QCBOREncode_Finish() is called.
+ *
+ * If this is called and it is not a map that is currently open,
+ * @ref QCBOR_ERR_CLOSE_MISMATCH will be returned when
+ * QCBOREncode_Finish() is called.
*/
-static void QCBOREncode_CloseMap(QCBOREncodeContext *pCtx);
+static void
+QCBOREncode_CloseMap(QCBOREncodeContext *pCtx);
/**
@@ -1769,10 +1938,12 @@
*
* This must be closed with QCBOREncode_CloseArrayIndefiniteLength().
*/
-static void QCBOREncode_OpenArrayIndefiniteLength(QCBOREncodeContext *pCtx);
+static void
+QCBOREncode_OpenArrayIndefiniteLength(QCBOREncodeContext *pCtx);
-static void QCBOREncode_OpenArrayIndefiniteLengthInMap(QCBOREncodeContext *pCtx,
- const char *szLabel);
+static void
+QCBOREncode_OpenArrayIndefiniteLengthInMap(QCBOREncodeContext *pCtx,
+ const char *szLabel);
static void
QCBOREncode_OpenArrayIndefiniteLengthInMapN(QCBOREncodeContext *pCtx,
@@ -1801,10 +1972,12 @@
*
* This must be closed with QCBOREncode_CloseMapIndefiniteLength().
*/
-static void QCBOREncode_OpenMapIndefiniteLength(QCBOREncodeContext *pCtx);
+static void
+QCBOREncode_OpenMapIndefiniteLength(QCBOREncodeContext *pCtx);
-static void QCBOREncode_OpenMapIndefiniteLengthInMap(QCBOREncodeContext *pCtx,
- const char *szLabel);
+static void
+QCBOREncode_OpenMapIndefiniteLengthInMap(QCBOREncodeContext *pCtx,
+ const char *szLabel);
static void
QCBOREncode_OpenMapIndefiniteLengthInMapN(QCBOREncodeContext *pCtx,
@@ -1826,82 +1999,86 @@
/**
- @brief Indicate start of encoded CBOR to be wrapped in a bstr.
-
- @param[in] pCtx The encoding context to open the bstr-wrapped CBOR in.
-
- All added encoded items between this call and a call to
- QCBOREncode_CloseBstrWrap2() will be wrapped in a bstr. They will
- appear in the final output as a byte string. That byte string will
- contain encoded CBOR. This increases nesting level by one.
-
- The typical use case is for encoded CBOR that is to be
- cryptographically hashed, as part of a [RFC 8152, COSE]
- (https://tools.ietf.org/html/rfc8152) implementation. The
- wrapping byte string is taken as input by the hash function
- (which is why it is returned by QCBOREncode_CloseBstrWrap2()).
- It is also easy to recover on decoding with standard CBOR
- decoders.
-
- Using QCBOREncode_BstrWrap() and QCBOREncode_CloseBstrWrap2() avoids
- having to encode the items first in one buffer (e.g., the COSE
- payload) and then add that buffer as a bstr to another encoding
- (e.g. the COSE to-be-signed bytes, the @c Sig_structure) potentially
- halving the memory needed.
-
- CBOR by nature must be decoded item by item in order from the start.
- By wrapping some CBOR in a byte string, the decoding of that wrapped
- CBOR can be skipped. This is another use of wrapping, perhaps
- because the CBOR is large and deeply nested. Perhaps APIs for
- handling one defined CBOR message that is being embedded in another
- only take input as a byte string. Perhaps the desire is to be able
- to decode the out layer even in the wrapped has errors.
+ * @brief Indicate start of encoded CBOR to be wrapped in a bstr.
+ *
+ * @param[in] pCtx The encoding context to open the bstr-wrapped CBOR in.
+ *
+ * All added encoded items between this call and a call to
+ * QCBOREncode_CloseBstrWrap2() will be wrapped in a bstr. They will
+ * appear in the final output as a byte string. That byte string will
+ * contain encoded CBOR. This increases nesting level by one.
+ *
+ * The typical use case is for encoded CBOR that is to be
+ * cryptographically hashed, as part of a [RFC 8152, COSE]
+ * (https://tools.ietf.org/html/rfc8152) implementation. The wrapping
+ * byte string is taken as input by the hash function (which is why it
+ * is returned by QCBOREncode_CloseBstrWrap2()). It is also easy to
+ * recover on decoding with standard CBOR decoders.
+ *
+ * Using QCBOREncode_BstrWrap() and QCBOREncode_CloseBstrWrap2()
+ * avoids having to encode the items first in one buffer (e.g., the
+ * COSE payload) and then add that buffer as a bstr to another
+ * encoding (e.g. the COSE to-be-signed bytes, the @c Sig_structure)
+ * potentially halving the memory needed.
+ *
+ * CBOR by nature must be decoded item by item in order from the
+ * start. By wrapping some CBOR in a byte string, the decoding of
+ * that wrapped CBOR can be skipped. This is another use of wrapping,
+ * perhaps because the CBOR is large and deeply nested. Perhaps APIs
+ * for handling one defined CBOR message that is being embedded in
+ * another only take input as a byte string. Perhaps the desire is to
+ * be able to decode the out layer even in the wrapped has errors.
*/
-static void QCBOREncode_BstrWrap(QCBOREncodeContext *pCtx);
+static void
+QCBOREncode_BstrWrap(QCBOREncodeContext *pCtx);
-static void QCBOREncode_BstrWrapInMap(QCBOREncodeContext *pCtx, const char *szLabel);
+static void
+QCBOREncode_BstrWrapInMap(QCBOREncodeContext *pCtx, const char *szLabel);
-static void QCBOREncode_BstrWrapInMapN(QCBOREncodeContext *pCtx, int64_t nLabel);
+static void
+QCBOREncode_BstrWrapInMapN(QCBOREncodeContext *pCtx, int64_t nLabel);
/**
- @brief Close a wrapping bstr.
-
- @param[in] pCtx The encoding context to close of bstr wrapping in.
- @param[in] bIncludeCBORHead Include the encoded CBOR head of the bstr
- as well as the bytes in @c pWrappedCBOR.
- @param[out] pWrappedCBOR A @ref UsefulBufC containing wrapped bytes.
-
- The closes a wrapping bstr opened by QCBOREncode_BstrWrap(). It reduces
- nesting level by one.
-
- A pointer and length of the enclosed encoded CBOR is returned in @c
- *pWrappedCBOR if it is not @c NULL. The main purpose of this is so
- this data can be hashed (e.g., with SHA-256) as part of a [RFC 8152,
- COSE] (https://tools.ietf.org/html/rfc8152)
- implementation. **WARNING**, this pointer and length should be used
- right away before any other calls to @c QCBOREncode_CloseXxx() as
- they will move data around and the pointer and length will no longer
- be to the correct encoded CBOR.
-
- When an error occurs as a result of this call, the encoder records
- the error and enters the error state. The error will be returned when
- QCBOREncode_Finish() is called.
-
- If this has been called more times than QCBOREncode_BstrWrap(), then
- @ref QCBOR_ERR_TOO_MANY_CLOSES will be returned when
- QCBOREncode_Finish() is called.
-
- If this is called and it is not a wrapping bstr that is currently
- open, @ref QCBOR_ERR_CLOSE_MISMATCH will be returned when
- QCBOREncode_Finish() is called.
-
- QCBOREncode_CloseBstrWrap() is a deprecated version of this function
- that is equivalent to the call with @c bIncludeCBORHead @c true.
+ * @brief Close a wrapping bstr.
+ *
+ * @param[in] pCtx The encoding context to close of bstr wrapping in.
+ * @param[in] bIncludeCBORHead Include the encoded CBOR head of the bstr
+ * as well as the bytes in @c pWrappedCBOR.
+ * @param[out] pWrappedCBOR A @ref UsefulBufC containing wrapped bytes.
+ *
+ * The closes a wrapping bstr opened by QCBOREncode_BstrWrap(). It reduces
+ * nesting level by one.
+ *
+ * A pointer and length of the enclosed encoded CBOR is returned in @c
+ * *pWrappedCBOR if it is not @c NULL. The main purpose of this is so
+ * this data can be hashed (e.g., with SHA-256) as part of a [RFC
+ * 8152, COSE] (https://tools.ietf.org/html/rfc8152)
+ * implementation. **WARNING**, this pointer and length should be used
+ * right away before any other calls to @c QCBOREncode_CloseXxx() as
+ * they will move data around and the pointer and length will no
+ * longer be to the correct encoded CBOR.
+ *
+ * When an error occurs as a result of this call, the encoder records
+ * the error and enters the error state. The error will be returned
+ * when QCBOREncode_Finish() is called.
+ *
+ * If this has been called more times than QCBOREncode_BstrWrap(),
+ * then @ref QCBOR_ERR_TOO_MANY_CLOSES will be returned when
+ * QCBOREncode_Finish() is called.
+ *
+ * If this is called and it is not a wrapping bstr that is currently
+ * open, @ref QCBOR_ERR_CLOSE_MISMATCH will be returned when
+ * QCBOREncode_Finish() is called.
+ *
+ * QCBOREncode_CloseBstrWrap() is a deprecated version of this function
+ * that is equivalent to the call with @c bIncludeCBORHead @c true.
*/
-void QCBOREncode_CloseBstrWrap2(QCBOREncodeContext *pCtx, bool bIncludeCBORHead, UsefulBufC *pWrappedCBOR);
+void
+QCBOREncode_CloseBstrWrap2(QCBOREncodeContext *pCtx, bool bIncludeCBORHead, UsefulBufC *pWrappedCBOR);
-static void QCBOREncode_CloseBstrWrap(QCBOREncodeContext *pCtx, UsefulBufC *pWrappedCBOR);
+static void
+QCBOREncode_CloseBstrWrap(QCBOREncodeContext *pCtx, UsefulBufC *pWrappedCBOR);
/**
@@ -1920,191 +2097,202 @@
* string. If something has been added, this sets the error
* @ref QCBOR_ERR_CANNOT_CANCEL.
*/
-void QCBOREncode_CancelBstrWrap(QCBOREncodeContext *pCtx);
+void
+QCBOREncode_CancelBstrWrap(QCBOREncodeContext *pCtx);
/**
- @brief Add some already-encoded CBOR bytes.
-
- @param[in] pCtx The encoding context to add the already-encode CBOR to.
- @param[in] Encoded The already-encoded CBOR to add to the context.
-
- The encoded CBOR being added must be fully conforming CBOR. It must
- be complete with no arrays or maps that are incomplete. While this
- encoder doesn't ever produce indefinite lengths, it is OK for the
- raw CBOR added here to have indefinite lengths.
-
- The raw CBOR added here is not checked in anyway. If it is not
- conforming or has open arrays or such, the final encoded CBOR
- will probably be wrong or not what was intended.
-
- If the encoded CBOR being added here contains multiple items, they
- must be enclosed in a map or array. At the top level the raw
- CBOR must be a single data item.
+ * @brief Add some already-encoded CBOR bytes.
+ *
+ * @param[in] pCtx The encoding context to add the already-encode CBOR to.
+ * @param[in] Encoded The already-encoded CBOR to add to the context.
+ *
+ * The encoded CBOR being added must be fully conforming CBOR. It must
+ * be complete with no arrays or maps that are incomplete. While this
+ * encoder doesn't ever produce indefinite lengths, it is OK for the
+ * raw CBOR added here to have indefinite lengths.
+ *
+ * The raw CBOR added here is not checked in anyway. If it is not
+ * conforming or has open arrays or such, the final encoded CBOR
+ * will probably be wrong or not what was intended.
+ *
+ * If the encoded CBOR being added here contains multiple items, they
+ * must be enclosed in a map or array. At the top level the raw
+ * CBOR must be a single data item.
*/
-static void QCBOREncode_AddEncoded(QCBOREncodeContext *pCtx, UsefulBufC Encoded);
+static void
+QCBOREncode_AddEncoded(QCBOREncodeContext *pCtx, UsefulBufC Encoded);
-static void QCBOREncode_AddEncodedToMap(QCBOREncodeContext *pCtx, const char *szLabel, UsefulBufC Encoded);
+static void
+QCBOREncode_AddEncodedToMap(QCBOREncodeContext *pCtx, const char *szLabel, UsefulBufC Encoded);
-static void QCBOREncode_AddEncodedToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, UsefulBufC Encoded);
+static void
+QCBOREncode_AddEncodedToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, UsefulBufC Encoded);
/**
- @brief Get the encoded result.
-
- @param[in] pCtx The context to finish encoding with.
- @param[out] pEncodedCBOR Structure in which the pointer and length of the encoded
- CBOR is returned.
-
- @retval QCBOR_SUCCESS Encoded CBOR is returned.
-
- @retval QCBOR_ERR_TOO_MANY_CLOSES Nesting error
-
- @retval QCBOR_ERR_CLOSE_MISMATCH Nesting error
-
- @retval QCBOR_ERR_ARRAY_OR_MAP_STILL_OPEN Nesting error
-
- @retval QCBOR_ERR_BUFFER_TOO_LARGE Encoded output buffer size
-
- @retval QCBOR_ERR_BUFFER_TOO_SMALL Encoded output buffer size
-
- @retval QCBOR_ERR_ARRAY_NESTING_TOO_DEEP Implementation limit
-
- @retval QCBOR_ERR_ARRAY_TOO_LONG Implementation limit
-
- On success, the pointer and length of the encoded CBOR are returned
- in @c *pEncodedCBOR. The pointer is the same pointer that was passed
- in to QCBOREncode_Init(). Note that it is not const when passed to
- QCBOREncode_Init(), but it is const when returned here. The length
- will be smaller than or equal to the length passed in when
- QCBOREncode_Init() as this is the length of the actual result, not
- the size of the buffer it was written to.
-
- If a @c NULL was passed for @c Storage.ptr when QCBOREncode_Init()
- was called, @c NULL will be returned here, but the length will be
- that of the CBOR that would have been encoded.
-
- Encoding errors primarily manifest here as most other encoding function
- do no return an error. They just set the error state in the encode
- context after which no encoding function does anything.
-
- Three types of errors manifest here. The first type are nesting
- errors where the number of @c QCBOREncode_OpenXxx() calls do not
- match the number @c QCBOREncode_CloseXxx() calls. The solution is to
- fix the calling code.
-
- The second type of error is because the buffer given is either too
- small or too large. The remedy is to give a correctly sized buffer.
-
- The third type are due to limits in this implementation. @ref
- QCBOR_ERR_ARRAY_NESTING_TOO_DEEP can be worked around by encoding the
- CBOR in two (or more) phases and adding the CBOR from the first phase
- to the second with @c QCBOREncode_AddEncoded().
-
- If an error is returned, the buffer may have partially encoded
- incorrect CBOR in it and it should not be used. Likewise, the length
- may be incorrect and should not be used.
-
- Note that the error could have occurred in one of the many @c
- QCBOREncode_AddXxx() calls long before QCBOREncode_Finish() was
- called. This error handling reduces the CBOR implementation size but
- makes debugging harder.
-
- This may be called multiple times. It will always return the same. It
- can also be interleaved with calls to QCBOREncode_FinishGetSize().
-
- QCBOREncode_GetErrorState() can be called to get the current
- error state in order to abort encoding early as an optimization, but
- calling it is is never required.
+ * @brief Get the encoded result.
+ *
+ * @param[in] pCtx The context to finish encoding with.
+ * @param[out] pEncodedCBOR Structure in which the pointer and length of
+ * the encoded CBOR is returned.
+ *
+ * @retval QCBOR_SUCCESS Encoded CBOR is returned.
+ *
+ * @retval QCBOR_ERR_TOO_MANY_CLOSES Nesting error
+ *
+ * @retval QCBOR_ERR_CLOSE_MISMATCH Nesting error
+ *
+ * @retval QCBOR_ERR_ARRAY_OR_MAP_STILL_OPEN Nesting error
+ *
+ * @retval QCBOR_ERR_BUFFER_TOO_LARGE Encoded output buffer size
+ *
+ * @retval QCBOR_ERR_BUFFER_TOO_SMALL Encoded output buffer size
+ *
+ * @retval QCBOR_ERR_ARRAY_NESTING_TOO_DEEP Implementation limit
+ *
+ * @retval QCBOR_ERR_ARRAY_TOO_LONG Implementation limit
+ *
+ * On success, the pointer and length of the encoded CBOR are returned
+ * in @c *pEncodedCBOR. The pointer is the same pointer that was passed
+ * in to QCBOREncode_Init(). Note that it is not const when passed to
+ * QCBOREncode_Init(), but it is const when returned here. The length
+ * will be smaller than or equal to the length passed in when
+ * QCBOREncode_Init() as this is the length of the actual result, not
+ * the size of the buffer it was written to.
+ *
+ * If a @c NULL was passed for @c Storage.ptr when QCBOREncode_Init()
+ * was called, @c NULL will be returned here, but the length will be
+ * that of the CBOR that would have been encoded.
+ *
+ * Encoding errors primarily manifest here as most other encoding function
+ * do no return an error. They just set the error state in the encode
+ * context after which no encoding function does anything.
+ *
+ * Three types of errors manifest here. The first type are nesting
+ * errors where the number of @c QCBOREncode_OpenXxx() calls do not
+ * match the number @c QCBOREncode_CloseXxx() calls. The solution is to
+ * fix the calling code.
+ *
+ * The second type of error is because the buffer given is either too
+ * small or too large. The remedy is to give a correctly sized buffer.
+ *
+ * The third type are due to limits in this implementation.
+ * @ref QCBOR_ERR_ARRAY_NESTING_TOO_DEEP can be worked around by
+ * encoding the CBOR in two (or more) phases and adding the CBOR from
+ * the first phase to the second with @c QCBOREncode_AddEncoded().
+ *
+ * If an error is returned, the buffer may have partially encoded
+ * incorrect CBOR in it and it should not be used. Likewise, the length
+ * may be incorrect and should not be used.
+ *
+ * Note that the error could have occurred in one of the many
+ * @c QCBOREncode_AddXxx() calls long before QCBOREncode_Finish() was
+ * called. This error handling reduces the CBOR implementation size
+ * but makes debugging harder.
+ *
+ * This may be called multiple times. It will always return the
+ * same. It can also be interleaved with calls to
+ * QCBOREncode_FinishGetSize().
+ *
+ * QCBOREncode_GetErrorState() can be called to get the current
+ * error state in order to abort encoding early as an optimization, but
+ * calling it is is never required.
*/
-QCBORError QCBOREncode_Finish(QCBOREncodeContext *pCtx, UsefulBufC *pEncodedCBOR);
+QCBORError
+QCBOREncode_Finish(QCBOREncodeContext *pCtx, UsefulBufC *pEncodedCBOR);
/**
- @brief Get the encoded CBOR and error status.
-
- @param[in] pCtx The context to finish encoding with.
- @param[out] uEncodedLen The length of the encoded or potentially
- encoded CBOR in bytes.
-
- @return The same errors as QCBOREncode_Finish().
-
- This functions the same as QCBOREncode_Finish(), but only returns the
- size of the encoded output.
+ * @brief Get the encoded CBOR and error status.
+ *
+ * @param[in] pCtx The context to finish encoding with.
+ * @param[out] uEncodedLen The length of the encoded or potentially
+ * encoded CBOR in bytes.
+ *
+ * @return The same errors as QCBOREncode_Finish().
+ *
+ * This functions the same as QCBOREncode_Finish(), but only returns the
+ * size of the encoded output.
*/
-QCBORError QCBOREncode_FinishGetSize(QCBOREncodeContext *pCtx, size_t *uEncodedLen);
+QCBORError
+QCBOREncode_FinishGetSize(QCBOREncodeContext *pCtx, size_t *uEncodedLen);
/**
- @brief Indicate whether output buffer is NULL or not.
-
- @param[in] pCtx The encoding context.
-
- @return 1 if the output buffer is @c NULL.
-
- Sometimes a @c NULL input buffer is given to QCBOREncode_Init() so
- that the size of the generated CBOR can be calculated without
- allocating a buffer for it. This returns 1 when the output buffer is
- NULL and 0 when it is not.
-*/
-static int QCBOREncode_IsBufferNULL(QCBOREncodeContext *pCtx);
-
-
-/**
- @brief Get the encoding error state.
-
- @param[in] pCtx The encoding context.
-
- @return One of @ref QCBORError. See return values from
- QCBOREncode_Finish()
-
- Normally encoding errors need only be handled at the end of encoding
- when QCBOREncode_Finish() is called. This can be called to get the
- error result before finish should there be a need to halt encoding
- before QCBOREncode_Finish() is called.
-*/
-static QCBORError QCBOREncode_GetErrorState(QCBOREncodeContext *pCtx);
-
-
-/**
- Encode the "head" of a CBOR data item.
-
- @param buffer Buffer to output the encoded head to; must be
- @ref QCBOR_HEAD_BUFFER_SIZE bytes in size.
- @param uMajorType One of CBOR_MAJOR_TYPE_XX.
- @param uMinLen The minimum number of bytes to encode uNumber. Almost always
- this is 0 to use preferred minimal encoding. If this is 4,
- then even the values 0xffff and smaller will be encoded
- in 4 bytes. This is used primarily when encoding a
- float or double put into uNumber as the leading zero bytes
- for them must be encoded.
- @param uNumber The numeric argument part of the CBOR head.
- @return Pointer and length of the encoded head or
- @ref NULLUsefulBufC if the output buffer is too small.
-
- Callers do not to need to call this for normal CBOR encoding. Note that it doesn't even
- take a @ref QCBOREncodeContext argument.
-
- This encodes the major type and argument part of a data item. The
- argument is an integer that is usually either the value or the length
- of the data item.
-
- This is exposed in the public interface to allow hashing of some CBOR
- data types, bstr in particular, a chunk at a time so the full CBOR
- doesn't have to be encoded in a contiguous buffer.
-
- For example, if you have a 100,000 byte binary blob in a buffer that
- needs to be a bstr encoded and then hashed. You could allocate a
- 100,010 byte buffer and encode it normally. Alternatively, you can
- encode the head in a 10 byte buffer with this function, hash that and
- then hash the 100,000 bytes using the same hash context.
-
- See also QCBOREncode_AddBytesLenOnly();
+ * @brief Indicate whether output buffer is NULL or not.
+ *
+ * @param[in] pCtx The encoding context.
+ *
+ * @return 1 if the output buffer is @c NULL.
+ *
+ * Sometimes a @c NULL input buffer is given to QCBOREncode_Init() so
+ * that the size of the generated CBOR can be calculated without
+ * allocating a buffer for it. This returns 1 when the output buffer
+ * is @c NULL and 0 when it is not.
*/
-UsefulBufC QCBOREncode_EncodeHead(UsefulBuf buffer,
- uint8_t uMajorType,
- uint8_t uMinLen,
- uint64_t uNumber);
+static int
+QCBOREncode_IsBufferNULL(QCBOREncodeContext *pCtx);
+
+
+/**
+ * @brief Get the encoding error state.
+ *
+ * @param[in] pCtx The encoding context.
+ *
+ * @return One of @ref QCBORError. See return values from
+ * QCBOREncode_Finish()
+ *
+ * Normally encoding errors need only be handled at the end of
+ * encoding when QCBOREncode_Finish() is called. This can be called to
+ * get the error result before finish should there be a need to halt
+ * encoding before QCBOREncode_Finish() is called.
+ */
+static QCBORError
+QCBOREncode_GetErrorState(QCBOREncodeContext *pCtx);
+
+
+/**
+ * Encode the "head" of a CBOR data item.
+ *
+ * @param buffer Buffer to output the encoded head to; must be
+ * @ref QCBOR_HEAD_BUFFER_SIZE bytes in size.
+ * @param uMajorType One of CBOR_MAJOR_TYPE_XX.
+ * @param uMinLen The minimum number of bytes to encode uNumber. Almost
+ * always this is 0 to use preferred
+ * serialization. If this is 4, then even the
+ * values 0xffff and smaller will be encoded in 4
+ * bytes. This is used primarily when encoding a
+ * float or double put into uNumber as the leading
+ * zero bytes for them must be encoded.
+ * @param uNumber The numeric argument part of the CBOR head.
+ * @return Pointer and length of the encoded head or
+ * @ref NULLUsefulBufC if the output buffer is too small.
+ *
+ * Callers do not to need to call this for normal CBOR encoding. Note
+ * that it doesn't even take a @ref QCBOREncodeContext argument.
+ *
+ * This encodes the major type and argument part of a data item. The
+ * argument is an integer that is usually either the value or the length
+ * of the data item.
+ *
+ * This is exposed in the public interface to allow hashing of some CBOR
+ * data types, bstr in particular, a chunk at a time so the full CBOR
+ * doesn't have to be encoded in a contiguous buffer.
+ *
+ * For example, if you have a 100,000 byte binary blob in a buffer that
+ * needs to be a bstr encoded and then hashed. You could allocate a
+ * 100,010 byte buffer and encode it normally. Alternatively, you can
+ * encode the head in a 10 byte buffer with this function, hash that and
+ * then hash the 100,000 bytes using the same hash context.
+ *
+ * See also QCBOREncode_AddBytesLenOnly();
+ */
+UsefulBufC
+QCBOREncode_EncodeHead(UsefulBuf buffer,
+ uint8_t uMajorType,
+ uint8_t uMinLen,
+ uint64_t uNumber);
@@ -2114,174 +2302,199 @@
========================================================================= */
/**
- @brief Semi-private method to add a buffer full of bytes to encoded output
-
- @param[in] pCtx The encoding context to add the integer to.
- @param[in] uMajorType The CBOR major type of the bytes.
- @param[in] Bytes The bytes to add.
-
- Use QCBOREncode_AddText() or QCBOREncode_AddBytes() or
- QCBOREncode_AddEncoded() instead. They are inline functions that call
- this and supply the correct major type. This function is public to
- make the inline functions work to keep the overall code size down and
- because the C language has no way to make it private.
-
- If this is called the major type should be @c
- CBOR_MAJOR_TYPE_TEXT_STRING, @c CBOR_MAJOR_TYPE_BYTE_STRING or @c
- CBOR_MAJOR_NONE_TYPE_RAW. The last one is special for adding
- already-encoded CBOR.
+ * @brief Semi-private method to add a buffer full of bytes to encoded output
+ *
+ * @param[in] pCtx The encoding context to add the integer to.
+ * @param[in] uMajorType The CBOR major type of the bytes.
+ * @param[in] Bytes The bytes to add.
+ *
+ * Use QCBOREncode_AddText() or QCBOREncode_AddBytes() or
+ * QCBOREncode_AddEncoded() instead. They are inline functions that
+ * call this and supply the correct major type. This function is
+ * public to make the inline functions work to keep the overall code
+ * size down and because the C language has no way to make it private.
+ *
+ * If this is called the major type should be @c CBOR_MAJOR_TYPE_TEXT_STRING,
+ * @c CBOR_MAJOR_TYPE_BYTE_STRING or @c CBOR_MAJOR_NONE_TYPE_RAW. The
+ * last one is special for adding already-encoded CBOR.
*/
-void QCBOREncode_AddBuffer(QCBOREncodeContext *pCtx, uint8_t uMajorType, UsefulBufC Bytes);
+void
+QCBOREncode_AddBuffer(QCBOREncodeContext *pCtx,
+ uint8_t uMajorType,
+ UsefulBufC Bytes);
/**
- @brief Semi-private method to open a map, array or bstr-wrapped CBOR
-
- @param[in] pCtx The context to add to.
- @param[in] uMajorType The major CBOR type to close
-
- Call QCBOREncode_OpenArray(), QCBOREncode_OpenMap() or
- QCBOREncode_BstrWrap() instead of this.
+ * @brief Semi-private method to open a map, array or bstr-wrapped CBOR
+ *
+ * @param[in] pCtx The context to add to.
+ * @param[in] uMajorType The major CBOR type to close
+ *
+ * Call QCBOREncode_OpenArray(), QCBOREncode_OpenMap() or
+ * QCBOREncode_BstrWrap() instead of this.
*/
-void QCBOREncode_OpenMapOrArray(QCBOREncodeContext *pCtx, uint8_t uMajorType);
+void
+QCBOREncode_OpenMapOrArray(QCBOREncodeContext *pCtx, uint8_t uMajorType);
/**
- @brief Semi-private method to open a map, array with indefinite length
-
- @param[in] pCtx The context to add to.
- @param[in] uMajorType The major CBOR type to close
-
- Call QCBOREncode_OpenArrayIndefiniteLength() or
- QCBOREncode_OpenMapIndefiniteLength() instead of this.
+ * @brief Semi-private method to open a map, array with indefinite length
+ *
+ * @param[in] pCtx The context to add to.
+ * @param[in] uMajorType The major CBOR type to close
+ *
+ * Call QCBOREncode_OpenArrayIndefiniteLength() or
+ * QCBOREncode_OpenMapIndefiniteLength() instead of this.
*/
-void QCBOREncode_OpenMapOrArrayIndefiniteLength(QCBOREncodeContext *pCtx, uint8_t uMajorType);
+void
+QCBOREncode_OpenMapOrArrayIndefiniteLength(QCBOREncodeContext *pCtx,
+ uint8_t uMajorType);
/**
- @brief Semi-private method to close a map, array or bstr wrapped CBOR
-
- @param[in] pCtx The context to add to.
- @param[in] uMajorType The major CBOR type to close.
-
- Call QCBOREncode_CloseArray() or QCBOREncode_CloseMap() instead of this.
+ * @brief Semi-private method to close a map, array or bstr wrapped CBOR
+ *
+ * @param[in] pCtx The context to add to.
+ * @param[in] uMajorType The major CBOR type to close.
+ *
+ * Call QCBOREncode_CloseArray() or QCBOREncode_CloseMap() instead of this.
*/
-void QCBOREncode_CloseMapOrArray(QCBOREncodeContext *pCtx, uint8_t uMajorType);
+void
+QCBOREncode_CloseMapOrArray(QCBOREncodeContext *pCtx, uint8_t uMajorType);
/**
- @brief Semi-private method to close a map, array with indefinite length
-
- @param[in] pCtx The context to add to.
- @param[in] uMajorType The major CBOR type to close.
-
- Call QCBOREncode_CloseArrayIndefiniteLength() or
- QCBOREncode_CloseMapIndefiniteLength() instead of this.
+ * @brief Semi-private method to close a map, array with indefinite length
+ *
+ * @param[in] pCtx The context to add to.
+ * @param[in] uMajorType The major CBOR type to close.
+ *
+ * Call QCBOREncode_CloseArrayIndefiniteLength() or
+ * QCBOREncode_CloseMapIndefiniteLength() instead of this.
*/
-void QCBOREncode_CloseMapOrArrayIndefiniteLength(QCBOREncodeContext *pCtx,
- uint8_t uMajorType);
+void
+QCBOREncode_CloseMapOrArrayIndefiniteLength(QCBOREncodeContext *pCtx,
+ uint8_t uMajorType);
/**
- @brief Semi-private method to add simple types.
-
- @param[in] pCtx The encoding context to add the simple value to.
- @param[in] uMinLen Minimum encoding size for uNum. Usually 0.
- @param[in] uNum One of CBOR_SIMPLEV_FALSE through _UNDEF or other.
-
- This is used to add simple types like true and false.
-
- Call QCBOREncode_AddBool(), QCBOREncode_AddNULL(),
- QCBOREncode_AddUndef() instead of this.
-
- This function can add simple values that are not defined by CBOR
- yet. This expansion point in CBOR should not be used unless they are
- standardized.
-
- Error handling is the same as QCBOREncode_AddInt64().
+ * @brief Semi-private method to add simple types.
+ *
+ * @param[in] pCtx The encoding context to add the simple value to.
+ * @param[in] uMinLen Minimum encoding size for uNum. Usually 0.
+ * @param[in] uNum One of CBOR_SIMPLEV_FALSE through _UNDEF or other.
+ *
+ * This is used to add simple types like true and false.
+ *
+ * Call QCBOREncode_AddBool(), QCBOREncode_AddNULL(),
+ * QCBOREncode_AddUndef() instead of this.
+ *
+ * This function can add simple values that are not defined by CBOR
+ * yet. This expansion point in CBOR should not be used unless they are
+ * standardized.
+ *
+ * Error handling is the same as QCBOREncode_AddInt64().
*/
-void QCBOREncode_AddType7(QCBOREncodeContext *pCtx, uint8_t uMinLen, uint64_t uNum);
+void
+QCBOREncode_AddType7(QCBOREncodeContext *pCtx,
+ uint8_t uMinLen,
+ uint64_t uNum);
/**
- @brief Semi-private method to add bigfloats and decimal fractions.
-
- @param[in] pCtx The encoding context to add the value to.
- @param[in] uTag The type 6 tag indicating what this is to be.
- @param[in] BigNumMantissa Is @ref NULLUsefulBufC if mantissa is an
- @c int64_t or the actual big number mantissa
- if not.
- @param[in] bBigNumIsNegative This is @c true if the big number is negative.
- @param[in] nMantissa The @c int64_t mantissa if it is not a big number.
- @param[in] nExponent The exponent.
-
- This outputs either the @ref CBOR_TAG_DECIMAL_FRACTION or @ref
- CBOR_TAG_BIGFLOAT tag. if @c uTag is @ref CBOR_TAG_INVALID64, then
- this outputs the "borrowed" content format.
-
- The tag content output by this is an array with two members, the
- exponent and then the mantissa. The mantissa can be either a big
- number or an @c int64_t.
-
- This implementation cannot output an exponent further from 0 than
- @c INT64_MAX.
-
- To output a mantissa that is between INT64_MAX and UINT64_MAX from 0,
- it must be as a big number.
-
- Typically, QCBOREncode_AddDecimalFraction(), QCBOREncode_AddBigFloat(),
- QCBOREncode_AddDecimalFractionBigNum() or QCBOREncode_AddBigFloatBigNum()
- is called instead of this.
+ * @brief Semi-private method to add bigfloats and decimal fractions.
+ *
+ * @param[in] pCtx The encoding context to add the value to.
+ * @param[in] uTag The type 6 tag indicating what this is to be.
+ * @param[in] BigNumMantissa Is @ref NULLUsefulBufC if mantissa is an
+ * @c int64_t or the actual big number mantissa
+ * if not.
+ * @param[in] bBigNumIsNegative This is @c true if the big number is negative.
+ * @param[in] nMantissa The @c int64_t mantissa if it is not a big number.
+ * @param[in] nExponent The exponent.
+ *
+ * This outputs either the @ref CBOR_TAG_DECIMAL_FRACTION or
+ * @ref CBOR_TAG_BIGFLOAT tag. if @c uTag is @ref CBOR_TAG_INVALID64,
+ * then this outputs the "borrowed" content format.
+ *
+ * The tag content output by this is an array with two members, the
+ * exponent and then the mantissa. The mantissa can be either a big
+ * number or an @c int64_t.
+ *
+ * This implementation cannot output an exponent further from 0 than
+ * @c INT64_MAX.
+ *
+ * To output a mantissa that is between INT64_MAX and UINT64_MAX from 0,
+ * it must be as a big number.
+ *
+ * Typically, QCBOREncode_AddDecimalFraction(), QCBOREncode_AddBigFloat(),
+ * QCBOREncode_AddDecimalFractionBigNum() or QCBOREncode_AddBigFloatBigNum()
+ * is called instead of this.
*/
-void QCBOREncode_AddExponentAndMantissa(QCBOREncodeContext *pCtx,
- uint64_t uTag,
- UsefulBufC BigNumMantissa,
- bool bBigNumIsNegative,
- int64_t nMantissa,
- int64_t nExponent);
+void
+QCBOREncode_AddExponentAndMantissa(QCBOREncodeContext *pCtx,
+ uint64_t uTag,
+ UsefulBufC BigNumMantissa,
+ bool bBigNumIsNegative,
+ int64_t nMantissa,
+ int64_t nExponent);
/**
- @brief Semi-private method to add only the type and length of a byte string.
-
- @param[in] pCtx The context to initialize.
- @param[in] Bytes Pointer and length of the input data.
-
- This is the same as QCBOREncode_AddBytes() except it only adds the
- CBOR encoding for the type and the length. It doesn't actually add
- the bytes. You can't actually produce correct CBOR with this and the
- rest of this API. It is only used for a special case where
- the valid CBOR is created manually by putting this type and length in
- and then adding the actual bytes. In particular, when only a hash of
- the encoded CBOR is needed, where the type and header are hashed
- separately and then the bytes is hashed. This makes it possible to
- implement COSE Sign1 with only one copy of the payload in the output
- buffer, rather than two, roughly cutting memory use in half.
-
- This is only used for this odd case, but this is a supported
- tested function.
-
- See also QCBOREncode_EncodeHead().
+ * @brief Semi-private method to add only the type and length of a byte string.
+ *
+ * @param[in] pCtx The context to initialize.
+ * @param[in] Bytes Pointer and length of the input data.
+ *
+ * This is the same as QCBOREncode_AddBytes() except it only adds the
+ * CBOR encoding for the type and the length. It doesn't actually add
+ * the bytes. You can't actually produce correct CBOR with this and
+ * the rest of this API. It is only used for a special case where the
+ * valid CBOR is created manually by putting this type and length in
+ * and then adding the actual bytes. In particular, when only a hash
+ * of the encoded CBOR is needed, where the type and header are hashed
+ * separately and then the bytes is hashed. This makes it possible to
+ * implement COSE Sign1 with only one copy of the payload in the
+ * output buffer, rather than two, roughly cutting memory use in half.
+ *
+ * This is only used for this odd case, but this is a supported
+ * tested function.
+ *
+ * See also QCBOREncode_EncodeHead().
*/
-static inline void QCBOREncode_AddBytesLenOnly(QCBOREncodeContext *pCtx, UsefulBufC Bytes);
+static inline void
+QCBOREncode_AddBytesLenOnly(QCBOREncodeContext *pCtx,
+ UsefulBufC Bytes);
-static inline void QCBOREncode_AddBytesLenOnlyToMap(QCBOREncodeContext *pCtx, const char *szLabel, UsefulBufC Bytes);
+static inline void
+QCBOREncode_AddBytesLenOnlyToMap(QCBOREncodeContext *pCtx,
+ const char *szLabel,
+ UsefulBufC Bytes);
-static inline void QCBOREncode_AddBytesLenOnlyToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, UsefulBufC Bytes);
+static inline void
+QCBOREncode_AddBytesLenOnlyToMapN(QCBOREncodeContext *pCtx,
+ int64_t nLabel,
+ UsefulBufC Bytes);
static inline void
-QCBOREncode_AddInt64ToMap(QCBOREncodeContext *pMe, const char *szLabel, int64_t uNum)
+QCBOREncode_AddInt64ToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ int64_t uNum)
{
- // Use _AddBuffer() because _AddSZString() is defined below, not above
- QCBOREncode_AddBuffer(pMe, CBOR_MAJOR_TYPE_TEXT_STRING, UsefulBuf_FromSZ(szLabel));
+ /* Use _AddBuffer() because _AddSZString() is defined below, not above */
+ QCBOREncode_AddBuffer(pMe,
+ CBOR_MAJOR_TYPE_TEXT_STRING,
+ UsefulBuf_FromSZ(szLabel));
QCBOREncode_AddInt64(pMe, uNum);
}
static inline void
-QCBOREncode_AddInt64ToMapN(QCBOREncodeContext *pMe, int64_t nLabel, int64_t uNum)
+QCBOREncode_AddInt64ToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ int64_t uNum)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddInt64(pMe, uNum);
@@ -2289,15 +2502,21 @@
static inline void
-QCBOREncode_AddUInt64ToMap(QCBOREncodeContext *pMe, const char *szLabel, uint64_t uNum)
+QCBOREncode_AddUInt64ToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ uint64_t uNum)
{
- // Use _AddBuffer() because _AddSZString() is defined below, not above
- QCBOREncode_AddBuffer(pMe, CBOR_MAJOR_TYPE_TEXT_STRING, UsefulBuf_FromSZ(szLabel));
+ /* Use _AddBuffer() because _AddSZString() is defined below, not above */
+ QCBOREncode_AddBuffer(pMe,
+ CBOR_MAJOR_TYPE_TEXT_STRING,
+ UsefulBuf_FromSZ(szLabel));
QCBOREncode_AddUInt64(pMe, uNum);
}
static inline void
-QCBOREncode_AddUInt64ToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint64_t uNum)
+QCBOREncode_AddUInt64ToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint64_t uNum)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddUInt64(pMe, uNum);
@@ -2311,14 +2530,18 @@
}
static inline void
-QCBOREncode_AddTextToMap(QCBOREncodeContext *pMe, const char *szLabel, UsefulBufC Text)
+QCBOREncode_AddTextToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBufC Text)
{
QCBOREncode_AddText(pMe, UsefulBuf_FromSZ(szLabel));
QCBOREncode_AddText(pMe, Text);
}
static inline void
-QCBOREncode_AddTextToMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBufC Text)
+QCBOREncode_AddTextToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBufC Text)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddText(pMe, Text);
@@ -2332,14 +2555,18 @@
}
static inline void
-QCBOREncode_AddSZStringToMap(QCBOREncodeContext *pMe, const char *szLabel, const char *szString)
+QCBOREncode_AddSZStringToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ const char *szString)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddSZString(pMe, szString);
}
static inline void
-QCBOREncode_AddSZStringToMapN(QCBOREncodeContext *pMe, int64_t nLabel, const char *szString)
+QCBOREncode_AddSZStringToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ const char *szString)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddSZString(pMe, szString);
@@ -2348,21 +2575,27 @@
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
static inline void
-QCBOREncode_AddDoubleToMap(QCBOREncodeContext *pMe, const char *szLabel, double dNum)
+QCBOREncode_AddDoubleToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ double dNum)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddDouble(pMe, dNum);
}
static inline void
-QCBOREncode_AddDoubleToMapN(QCBOREncodeContext *pMe, int64_t nLabel, double dNum)
+QCBOREncode_AddDoubleToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ double dNum)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddDouble(pMe, dNum);
}
static inline void
-QCBOREncode_AddFloatToMap(QCBOREncodeContext *pMe, const char *szLabel, float dNum)
+QCBOREncode_AddFloatToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ float dNum)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddFloat(pMe, dNum);
@@ -2376,28 +2609,36 @@
}
static inline void
-QCBOREncode_AddDoubleNoPreferredToMap(QCBOREncodeContext *pMe, const char *szLabel, double dNum)
+QCBOREncode_AddDoubleNoPreferredToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ double dNum)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddDoubleNoPreferred(pMe, dNum);
}
static inline void
-QCBOREncode_AddDoubleNoPreferredToMapN(QCBOREncodeContext *pMe, int64_t nLabel, double dNum)
+QCBOREncode_AddDoubleNoPreferredToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ double dNum)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddDoubleNoPreferred(pMe, dNum);
}
static inline void
-QCBOREncode_AddFloatNoPreferredToMap(QCBOREncodeContext *pMe, const char *szLabel, float dNum)
+QCBOREncode_AddFloatNoPreferredToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ float dNum)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddFloatNoPreferred(pMe, dNum);
}
static inline void
-QCBOREncode_AddFloatNoPreferredToMapN(QCBOREncodeContext *pMe, int64_t nLabel, float dNum)
+QCBOREncode_AddFloatNoPreferredToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ float dNum)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddFloatNoPreferred(pMe, dNum);
@@ -2416,14 +2657,20 @@
}
static inline void
-QCBOREncode_AddTDateEpochToMapSZ(QCBOREncodeContext *pMe, const char *szLabel, uint8_t uTag, int64_t nDate)
+QCBOREncode_AddTDateEpochToMapSZ(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ uint8_t uTag,
+ int64_t nDate)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddTDateEpoch(pMe, uTag, nDate);
}
static inline void
-QCBOREncode_AddTDateEpochToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint8_t uTag, int64_t nDate)
+QCBOREncode_AddTDateEpochToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTag,
+ int64_t nDate)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddTDateEpoch(pMe, uTag, nDate);
@@ -2436,14 +2683,18 @@
}
static inline void
-QCBOREncode_AddDateEpochToMap(QCBOREncodeContext *pMe, const char *szLabel, int64_t nDate)
+QCBOREncode_AddDateEpochToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ int64_t nDate)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddDateEpoch(pMe, nDate);
}
static inline void
-QCBOREncode_AddDateEpochToMapN(QCBOREncodeContext *pMe, int64_t nLabel, int64_t nDate)
+QCBOREncode_AddDateEpochToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ int64_t nDate)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddDateEpoch(pMe, nDate);
@@ -2460,14 +2711,20 @@
}
static inline void
-QCBOREncode_AddTDaysEpochToMapSZ(QCBOREncodeContext *pMe, const char *szLabel, uint8_t uTag, int64_t nDays)
+QCBOREncode_AddTDaysEpochToMapSZ(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ uint8_t uTag,
+ int64_t nDays)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddTDaysEpoch(pMe, uTag, nDays);
}
static inline void
-QCBOREncode_AddTDaysEpochToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint8_t uTag, int64_t nDays)
+QCBOREncode_AddTDaysEpochToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTag,
+ int64_t nDays)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddTDaysEpoch(pMe, uTag, nDays);
@@ -2481,28 +2738,36 @@
}
static inline void
-QCBOREncode_AddBytesToMap(QCBOREncodeContext *pMe, const char *szLabel, UsefulBufC Bytes)
+QCBOREncode_AddBytesToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBufC Bytes)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddBytes(pMe, Bytes);
}
static inline void
-QCBOREncode_AddBytesToMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBufC Bytes)
+QCBOREncode_AddBytesToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBufC Bytes)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddBytes(pMe, Bytes);
}
static inline void
-QCBOREncode_OpenBytesInMapSZ(QCBOREncodeContext *pMe, const char *szLabel, UsefulBuf *pPlace)
+QCBOREncode_OpenBytesInMapSZ(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBuf *pPlace)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_OpenBytes(pMe, pPlace);
}
static inline void
-QCBOREncode_OpenBytesInMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBuf *pPlace)
+QCBOREncode_OpenBytesInMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBuf *pPlace)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_OpenBytes(pMe, pPlace);
@@ -2515,14 +2780,18 @@
}
static inline void
-QCBOREncode_AddBytesLenOnlyToMap(QCBOREncodeContext *pMe, const char *szLabel, UsefulBufC Bytes)
+QCBOREncode_AddBytesLenOnlyToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBufC Bytes)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddBytesLenOnly(pMe, Bytes);
}
static inline void
-QCBOREncode_AddBytesLenOnlyToMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBufC Bytes)
+QCBOREncode_AddBytesLenOnlyToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBufC Bytes)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddBytesLenOnly(pMe, Bytes);
@@ -2530,7 +2799,9 @@
static inline void
-QCBOREncode_AddTBinaryUUID(QCBOREncodeContext *pMe, uint8_t uTagRequirement, UsefulBufC Bytes)
+QCBOREncode_AddTBinaryUUID(QCBOREncodeContext *pMe,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes)
{
if(uTagRequirement == QCBOR_ENCODE_AS_TAG) {
QCBOREncode_AddTag(pMe, CBOR_TAG_BIN_UUID);
@@ -2549,7 +2820,10 @@
}
static inline void
-QCBOREncode_AddTBinaryUUIDToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint8_t uTagRequirement, UsefulBufC Bytes)
+QCBOREncode_AddTBinaryUUIDToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddTBinaryUUID(pMe, uTagRequirement, Bytes);
@@ -2562,20 +2836,29 @@
}
static inline void
-QCBOREncode_AddBinaryUUIDToMap(QCBOREncodeContext *pMe, const char *szLabel, UsefulBufC Bytes)
+QCBOREncode_AddBinaryUUIDToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBufC Bytes)
{
QCBOREncode_AddTBinaryUUIDToMapSZ(pMe, szLabel, QCBOR_ENCODE_AS_TAG, Bytes);
}
static inline void
-QCBOREncode_AddBinaryUUIDToMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBufC Bytes)
+QCBOREncode_AddBinaryUUIDToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBufC Bytes)
{
- QCBOREncode_AddTBinaryUUIDToMapN(pMe, nLabel, QCBOR_ENCODE_AS_TAG, Bytes);
+ QCBOREncode_AddTBinaryUUIDToMapN(pMe,
+ nLabel,
+ QCBOR_ENCODE_AS_TAG,
+ Bytes);
}
static inline void
-QCBOREncode_AddTPositiveBignum(QCBOREncodeContext *pMe, uint8_t uTagRequirement, UsefulBufC Bytes)
+QCBOREncode_AddTPositiveBignum(QCBOREncodeContext *pMe,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes)
{
if(uTagRequirement == QCBOR_ENCODE_AS_TAG) {
QCBOREncode_AddTag(pMe, CBOR_TAG_POS_BIGNUM);
@@ -2594,7 +2877,10 @@
}
static inline void
-QCBOREncode_AddTPositiveBignumToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint8_t uTagRequirement, UsefulBufC Bytes)
+QCBOREncode_AddTPositiveBignumToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddTPositiveBignum(pMe, uTagRequirement, Bytes);
@@ -2607,20 +2893,32 @@
}
static inline void
-QCBOREncode_AddPositiveBignumToMap(QCBOREncodeContext *pMe, const char *szLabel, UsefulBufC Bytes)
+QCBOREncode_AddPositiveBignumToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBufC Bytes)
{
- QCBOREncode_AddTPositiveBignumToMapSZ(pMe, szLabel, QCBOR_ENCODE_AS_TAG, Bytes);
+ QCBOREncode_AddTPositiveBignumToMapSZ(pMe,
+ szLabel,
+ QCBOR_ENCODE_AS_TAG,
+ Bytes);
}
static inline void
-QCBOREncode_AddPositiveBignumToMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBufC Bytes)
+QCBOREncode_AddPositiveBignumToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBufC Bytes)
{
- QCBOREncode_AddTPositiveBignumToMapN(pMe, nLabel, QCBOR_ENCODE_AS_TAG, Bytes);
+ QCBOREncode_AddTPositiveBignumToMapN(pMe,
+ nLabel,
+ QCBOR_ENCODE_AS_TAG,
+ Bytes);
}
static inline void
-QCBOREncode_AddTNegativeBignum(QCBOREncodeContext *pMe, uint8_t uTagRequirement, UsefulBufC Bytes)
+QCBOREncode_AddTNegativeBignum(QCBOREncodeContext *pMe,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes)
{
if(uTagRequirement == QCBOR_ENCODE_AS_TAG) {
QCBOREncode_AddTag(pMe, CBOR_TAG_NEG_BIGNUM);
@@ -2639,7 +2937,10 @@
}
static inline void
-QCBOREncode_AddTNegativeBignumToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint8_t uTagRequirement, UsefulBufC Bytes)
+QCBOREncode_AddTNegativeBignumToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddTNegativeBignum(pMe, uTagRequirement, Bytes);
@@ -2652,15 +2953,25 @@
}
static inline void
-QCBOREncode_AddNegativeBignumToMap(QCBOREncodeContext *pMe, const char *szLabel, UsefulBufC Bytes)
+QCBOREncode_AddNegativeBignumToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBufC Bytes)
{
- QCBOREncode_AddTNegativeBignumToMapSZ(pMe, szLabel, QCBOR_ENCODE_AS_TAG, Bytes);
+ QCBOREncode_AddTNegativeBignumToMapSZ(pMe,
+ szLabel,
+ QCBOR_ENCODE_AS_TAG,
+ Bytes);
}
static inline void
-QCBOREncode_AddNegativeBignumToMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBufC Bytes)
+QCBOREncode_AddNegativeBignumToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBufC Bytes)
{
- QCBOREncode_AddTNegativeBignumToMapN(pMe, nLabel, QCBOR_ENCODE_AS_TAG, Bytes);
+ QCBOREncode_AddTNegativeBignumToMapN(pMe,
+ nLabel,
+ QCBOR_ENCODE_AS_TAG,
+ Bytes);
}
@@ -2695,7 +3006,10 @@
int64_t nBase10Exponent)
{
QCBOREncode_AddSZString(pMe, szLabel);
- QCBOREncode_AddTDecimalFraction(pMe, uTagRequirement, nMantissa, nBase10Exponent);
+ QCBOREncode_AddTDecimalFraction(pMe,
+ uTagRequirement,
+ nMantissa,
+ nBase10Exponent);
}
static inline void
@@ -2706,7 +3020,10 @@
int64_t nBase10Exponent)
{
QCBOREncode_AddInt64(pMe, nLabel);
- QCBOREncode_AddTDecimalFraction(pMe, uTagRequirement, nMantissa, nBase10Exponent);
+ QCBOREncode_AddTDecimalFraction(pMe,
+ uTagRequirement,
+ nMantissa,
+ nBase10Exponent);
}
static inline void
@@ -2714,7 +3031,10 @@
int64_t nMantissa,
int64_t nBase10Exponent)
{
- QCBOREncode_AddTDecimalFraction(pMe, QCBOR_ENCODE_AS_TAG, nMantissa, nBase10Exponent);
+ QCBOREncode_AddTDecimalFraction(pMe,
+ QCBOR_ENCODE_AS_TAG,
+ nMantissa,
+ nBase10Exponent);
}
static inline void
@@ -2723,7 +3043,11 @@
int64_t nMantissa,
int64_t nBase10Exponent)
{
- QCBOREncode_AddTDecimalFractionToMapSZ(pMe, szLabel, QCBOR_ENCODE_AS_TAG, nMantissa, nBase10Exponent);
+ QCBOREncode_AddTDecimalFractionToMapSZ(pMe,
+ szLabel,
+ QCBOR_ENCODE_AS_TAG,
+ nMantissa,
+ nBase10Exponent);
}
static inline void
@@ -2732,7 +3056,11 @@
int64_t nMantissa,
int64_t nBase10Exponent)
{
- QCBOREncode_AddTDecimalFractionToMapN(pMe, nLabel, QCBOR_ENCODE_AS_TAG, nMantissa, nBase10Exponent);
+ QCBOREncode_AddTDecimalFractionToMapN(pMe,
+ nLabel,
+ QCBOR_ENCODE_AS_TAG,
+ nMantissa,
+ nBase10Exponent);
}
@@ -2766,7 +3094,11 @@
int64_t nBase10Exponent)
{
QCBOREncode_AddSZString(pMe, szLabel);
- QCBOREncode_AddTDecimalFractionBigNum(pMe, uTagRequirement, Mantissa, bIsNegative, nBase10Exponent);
+ QCBOREncode_AddTDecimalFractionBigNum(pMe,
+ uTagRequirement,
+ Mantissa,
+ bIsNegative,
+ nBase10Exponent);
}
static inline void
@@ -2778,7 +3110,11 @@
int64_t nBase10Exponent)
{
QCBOREncode_AddInt64(pMe, nLabel);
- QCBOREncode_AddTDecimalFractionBigNum(pMe, uTagRequirement, Mantissa, bIsNegative, nBase10Exponent);
+ QCBOREncode_AddTDecimalFractionBigNum(pMe,
+ uTagRequirement,
+ Mantissa,
+ bIsNegative,
+ nBase10Exponent);
}
static inline void
@@ -2787,7 +3123,11 @@
bool bIsNegative,
int64_t nBase10Exponent)
{
- QCBOREncode_AddTDecimalFractionBigNum(pMe, QCBOR_ENCODE_AS_TAG, Mantissa, bIsNegative, nBase10Exponent);
+ QCBOREncode_AddTDecimalFractionBigNum(pMe,
+ QCBOR_ENCODE_AS_TAG,
+ Mantissa,
+ bIsNegative,
+ nBase10Exponent);
}
static inline void
@@ -2836,7 +3176,12 @@
} else {
uTag = CBOR_TAG_INVALID64;
}
- QCBOREncode_AddExponentAndMantissa(pMe, uTag, NULLUsefulBufC, false, nMantissa, nBase2Exponent);
+ QCBOREncode_AddExponentAndMantissa(pMe,
+ uTag,
+ NULLUsefulBufC,
+ false,
+ nMantissa,
+ nBase2Exponent);
}
static inline void
@@ -2866,7 +3211,10 @@
int64_t nMantissa,
int64_t nBase2Exponent)
{
- QCBOREncode_AddTBigFloat(pMe, QCBOR_ENCODE_AS_TAG, nMantissa, nBase2Exponent);
+ QCBOREncode_AddTBigFloat(pMe,
+ QCBOR_ENCODE_AS_TAG,
+ nMantissa,
+ nBase2Exponent);
}
static inline void
@@ -2875,7 +3223,11 @@
int64_t nMantissa,
int64_t nBase2Exponent)
{
- QCBOREncode_AddTBigFloatToMapSZ(pMe, szLabel, QCBOR_ENCODE_AS_TAG, nMantissa, nBase2Exponent);
+ QCBOREncode_AddTBigFloatToMapSZ(pMe,
+ szLabel,
+ QCBOR_ENCODE_AS_TAG,
+ nMantissa,
+ nBase2Exponent);
}
static inline void
@@ -2884,7 +3236,11 @@
int64_t nMantissa,
int64_t nBase2Exponent)
{
- QCBOREncode_AddTBigFloatToMapN(pMe, nLabel, QCBOR_ENCODE_AS_TAG, nMantissa, nBase2Exponent);
+ QCBOREncode_AddTBigFloatToMapN(pMe,
+ nLabel,
+ QCBOR_ENCODE_AS_TAG,
+ nMantissa,
+ nBase2Exponent);
}
@@ -2902,7 +3258,12 @@
} else {
uTag = CBOR_TAG_INVALID64;
}
- QCBOREncode_AddExponentAndMantissa(pMe, uTag, Mantissa, bIsNegative, 0, nBase2Exponent);
+ QCBOREncode_AddExponentAndMantissa(pMe,
+ uTag,
+ Mantissa,
+ bIsNegative,
+ 0,
+ nBase2Exponent);
}
static inline void
@@ -2914,7 +3275,11 @@
int64_t nBase2Exponent)
{
QCBOREncode_AddSZString(pMe, szLabel);
- QCBOREncode_AddTBigFloatBigNum(pMe, uTagRequirement, Mantissa, bIsNegative, nBase2Exponent);
+ QCBOREncode_AddTBigFloatBigNum(pMe,
+ uTagRequirement,
+ Mantissa,
+ bIsNegative,
+ nBase2Exponent);
}
static inline void
@@ -2926,7 +3291,11 @@
int64_t nBase2Exponent)
{
QCBOREncode_AddInt64(pMe, nLabel);
- QCBOREncode_AddTBigFloatBigNum(pMe, uTagRequirement, Mantissa, bIsNegative, nBase2Exponent);
+ QCBOREncode_AddTBigFloatBigNum(pMe,
+ uTagRequirement,
+ Mantissa,
+ bIsNegative,
+ nBase2Exponent);
}
@@ -2936,7 +3305,10 @@
bool bIsNegative,
int64_t nBase2Exponent)
{
- QCBOREncode_AddTBigFloatBigNum(pMe, QCBOR_ENCODE_AS_TAG, Mantissa, bIsNegative, nBase2Exponent);
+ QCBOREncode_AddTBigFloatBigNum(pMe,
+ QCBOR_ENCODE_AS_TAG,
+ Mantissa, bIsNegative,
+ nBase2Exponent);
}
static inline void
@@ -2946,7 +3318,12 @@
bool bIsNegative,
int64_t nBase2Exponent)
{
- QCBOREncode_AddTBigFloatBigNumToMapSZ(pMe, szLabel, QCBOR_ENCODE_AS_TAG, Mantissa, bIsNegative, nBase2Exponent);
+ QCBOREncode_AddTBigFloatBigNumToMapSZ(pMe,
+ szLabel,
+ QCBOR_ENCODE_AS_TAG,
+ Mantissa,
+ bIsNegative,
+ nBase2Exponent);
}
static inline void
@@ -2956,13 +3333,20 @@
bool bIsNegative,
int64_t nBase2Exponent)
{
- QCBOREncode_AddTBigFloatBigNumToMapN(pMe, nLabel, QCBOR_ENCODE_AS_TAG, Mantissa, bIsNegative, nBase2Exponent);
+ QCBOREncode_AddTBigFloatBigNumToMapN(pMe,
+ nLabel,
+ QCBOR_ENCODE_AS_TAG,
+ Mantissa,
+ bIsNegative,
+ nBase2Exponent);
}
#endif /* QCBOR_DISABLE_EXP_AND_MANTISSA */
static inline void
-QCBOREncode_AddTURI(QCBOREncodeContext *pMe, uint8_t uTagRequirement, UsefulBufC URI)
+QCBOREncode_AddTURI(QCBOREncodeContext *pMe,
+ uint8_t uTagRequirement,
+ UsefulBufC URI)
{
if(uTagRequirement == QCBOR_ENCODE_AS_TAG) {
QCBOREncode_AddTag(pMe, CBOR_TAG_URI);
@@ -2971,14 +3355,20 @@
}
static inline void
-QCBOREncode_AddTURIToMapSZ(QCBOREncodeContext *pMe, const char *szLabel, uint8_t uTagRequirement, UsefulBufC URI)
+QCBOREncode_AddTURIToMapSZ(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC URI)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddTURI(pMe, uTagRequirement, URI);
}
static inline void
-QCBOREncode_AddTURIToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint8_t uTagRequirement, UsefulBufC URI)
+QCBOREncode_AddTURIToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC URI)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddTURI(pMe, uTagRequirement, URI);
@@ -2991,13 +3381,17 @@
}
static inline void
-QCBOREncode_AddURIToMap(QCBOREncodeContext *pMe, const char *szLabel, UsefulBufC URI)
+QCBOREncode_AddURIToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBufC URI)
{
QCBOREncode_AddTURIToMapSZ(pMe, szLabel, QCBOR_ENCODE_AS_TAG, URI);
}
static inline void
-QCBOREncode_AddURIToMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBufC URI)
+QCBOREncode_AddURIToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBufC URI)
{
QCBOREncode_AddTURIToMapN(pMe, nLabel, QCBOR_ENCODE_AS_TAG, URI);
}
@@ -3005,7 +3399,9 @@
static inline void
-QCBOREncode_AddTB64Text(QCBOREncodeContext *pMe, uint8_t uTagRequirement, UsefulBufC B64Text)
+QCBOREncode_AddTB64Text(QCBOREncodeContext *pMe,
+ uint8_t uTagRequirement,
+ UsefulBufC B64Text)
{
if(uTagRequirement == QCBOR_ENCODE_AS_TAG) {
QCBOREncode_AddTag(pMe, CBOR_TAG_B64);
@@ -3024,7 +3420,10 @@
}
static inline void
-QCBOREncode_AddTB64TextToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint8_t uTagRequirement, UsefulBufC B64Text)
+QCBOREncode_AddTB64TextToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC B64Text)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddTB64Text(pMe, uTagRequirement, B64Text);
@@ -3037,13 +3436,17 @@
}
static inline void
-QCBOREncode_AddB64TextToMap(QCBOREncodeContext *pMe, const char *szLabel, UsefulBufC B64Text)
+QCBOREncode_AddB64TextToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBufC B64Text)
{
QCBOREncode_AddTB64TextToMapSZ(pMe, szLabel, QCBOR_ENCODE_AS_TAG, B64Text);
}
static inline void
-QCBOREncode_AddB64TextToMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBufC B64Text)
+QCBOREncode_AddB64TextToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBufC B64Text)
{
QCBOREncode_AddTB64TextToMapN(pMe, nLabel, QCBOR_ENCODE_AS_TAG, B64Text);
}
@@ -3051,7 +3454,9 @@
static inline void
-QCBOREncode_AddTB64URLText(QCBOREncodeContext *pMe, uint8_t uTagRequirement, UsefulBufC B64Text)
+QCBOREncode_AddTB64URLText(QCBOREncodeContext *pMe,
+ uint8_t uTagRequirement,
+ UsefulBufC B64Text)
{
if(uTagRequirement == QCBOR_ENCODE_AS_TAG) {
QCBOREncode_AddTag(pMe, CBOR_TAG_B64URL);
@@ -3070,7 +3475,10 @@
}
static inline void
-QCBOREncode_AddTB64URLTextToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint8_t uTagRequirement, UsefulBufC B64Text)
+QCBOREncode_AddTB64URLTextToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC B64Text)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddTB64URLText(pMe, uTagRequirement, B64Text);
@@ -3083,13 +3491,20 @@
}
static inline void
-QCBOREncode_AddB64URLTextToMap(QCBOREncodeContext *pMe, const char *szLabel, UsefulBufC B64Text)
+QCBOREncode_AddB64URLTextToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBufC B64Text)
{
- QCBOREncode_AddTB64URLTextToMapSZ(pMe, szLabel, QCBOR_ENCODE_AS_TAG, B64Text);
+ QCBOREncode_AddTB64URLTextToMapSZ(pMe,
+ szLabel,
+ QCBOR_ENCODE_AS_TAG,
+ B64Text);
}
static inline void
-QCBOREncode_AddB64URLTextToMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBufC B64Text)
+QCBOREncode_AddB64URLTextToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBufC B64Text)
{
QCBOREncode_AddTB64URLTextToMapN(pMe, nLabel, QCBOR_ENCODE_AS_TAG, B64Text);
}
@@ -3097,7 +3512,9 @@
static inline void
-QCBOREncode_AddTRegex(QCBOREncodeContext *pMe, uint8_t uTagRequirement, UsefulBufC Bytes)
+QCBOREncode_AddTRegex(QCBOREncodeContext *pMe,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes)
{
if(uTagRequirement == QCBOR_ENCODE_AS_TAG) {
QCBOREncode_AddTag(pMe, CBOR_TAG_REGEX);
@@ -3106,14 +3523,20 @@
}
static inline void
-QCBOREncode_AddTRegexToMapSZ(QCBOREncodeContext *pMe, const char *szLabel, uint8_t uTagRequirement, UsefulBufC Bytes)
+QCBOREncode_AddTRegexToMapSZ(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddTRegex(pMe, uTagRequirement, Bytes);
}
static inline void
-QCBOREncode_AddTRegexToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint8_t uTagRequirement, UsefulBufC Bytes)
+QCBOREncode_AddTRegexToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC Bytes)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddTRegex(pMe, uTagRequirement, Bytes);
@@ -3126,13 +3549,17 @@
}
static inline void
-QCBOREncode_AddRegexToMap(QCBOREncodeContext *pMe, const char *szLabel, UsefulBufC Bytes)
+QCBOREncode_AddRegexToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBufC Bytes)
{
QCBOREncode_AddTRegexToMapSZ(pMe, szLabel, QCBOR_ENCODE_AS_TAG, Bytes);
}
static inline void
-QCBOREncode_AddRegexToMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBufC Bytes)
+QCBOREncode_AddRegexToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBufC Bytes)
{
QCBOREncode_AddTRegexToMapN(pMe, nLabel, QCBOR_ENCODE_AS_TAG, Bytes);
@@ -3140,7 +3567,9 @@
static inline void
-QCBOREncode_AddTMIMEData(QCBOREncodeContext *pMe, uint8_t uTagRequirement, UsefulBufC MIMEData)
+QCBOREncode_AddTMIMEData(QCBOREncodeContext *pMe,
+ uint8_t uTagRequirement,
+ UsefulBufC MIMEData)
{
if(uTagRequirement == QCBOR_ENCODE_AS_TAG) {
QCBOREncode_AddTag(pMe, CBOR_TAG_BINARY_MIME);
@@ -3159,7 +3588,10 @@
}
static inline void
-QCBOREncode_AddTMIMEDataToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint8_t uTagRequirement, UsefulBufC MIMEData)
+QCBOREncode_AddTMIMEDataToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC MIMEData)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddTMIMEData(pMe, uTagRequirement, MIMEData);
@@ -3172,20 +3604,26 @@
}
static inline void
-QCBOREncode_AddMIMEDataToMap(QCBOREncodeContext *pMe, const char *szLabel, UsefulBufC MIMEData)
+QCBOREncode_AddMIMEDataToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBufC MIMEData)
{
QCBOREncode_AddTMIMEDataToMapSZ(pMe, szLabel, QCBOR_ENCODE_AS_TAG, MIMEData);
}
static inline void
-QCBOREncode_AddMIMEDataToMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBufC MIMEData)
+QCBOREncode_AddMIMEDataToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBufC MIMEData)
{
QCBOREncode_AddTMIMEDataToMapN(pMe, nLabel, QCBOR_ENCODE_AS_TAG, MIMEData);
}
static inline void
-QCBOREncode_AddTDateString(QCBOREncodeContext *pMe, uint8_t uTagRequirement, const char *szDate)
+QCBOREncode_AddTDateString(QCBOREncodeContext *pMe,
+ uint8_t uTagRequirement,
+ const char *szDate)
{
if(uTagRequirement == QCBOR_ENCODE_AS_TAG) {
QCBOREncode_AddTag(pMe, CBOR_TAG_DATE_STRING);
@@ -3204,7 +3642,10 @@
}
static inline void
-QCBOREncode_AddTDateStringToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint8_t uTagRequirement, const char *szDate)
+QCBOREncode_AddTDateStringToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ const char *szDate)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddTDateString(pMe, uTagRequirement, szDate);
@@ -3217,20 +3658,26 @@
}
static inline void
-QCBOREncode_AddDateStringToMap(QCBOREncodeContext *pMe, const char *szLabel, const char *szDate)
+QCBOREncode_AddDateStringToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ const char *szDate)
{
QCBOREncode_AddTDateStringToMapSZ(pMe, szLabel, QCBOR_ENCODE_AS_TAG, szDate);
}
static inline void
-QCBOREncode_AddDateStringToMapN(QCBOREncodeContext *pMe, int64_t nLabel, const char *szDate)
+QCBOREncode_AddDateStringToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ const char *szDate)
{
QCBOREncode_AddTDateStringToMapN(pMe, nLabel, QCBOR_ENCODE_AS_TAG, szDate);
}
static inline void
-QCBOREncode_AddTDaysString(QCBOREncodeContext *pMe, uint8_t uTagRequirement, const char *szDate)
+QCBOREncode_AddTDaysString(QCBOREncodeContext *pMe,
+ uint8_t uTagRequirement,
+ const char *szDate)
{
if(uTagRequirement == QCBOR_ENCODE_AS_TAG) {
QCBOREncode_AddTag(pMe, CBOR_TAG_DAYS_STRING);
@@ -3249,7 +3696,10 @@
}
static inline void
-QCBOREncode_AddTDaysStringToMapN(QCBOREncodeContext *pMe, int64_t nLabel, uint8_t uTagRequirement, const char *szDate)
+QCBOREncode_AddTDaysStringToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ const char *szDate)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddTDaysString(pMe, uTagRequirement, szDate);
@@ -3264,14 +3714,18 @@
}
static inline void
-QCBOREncode_AddSimpleToMap(QCBOREncodeContext *pMe, const char *szLabel, uint8_t uSimple)
+QCBOREncode_AddSimpleToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ uint8_t uSimple)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddSimple(pMe, uSimple);
}
static inline void
-QCBOREncode_AddSimpleToMapN(QCBOREncodeContext *pMe, int nLabel, uint8_t uSimple)
+QCBOREncode_AddSimpleToMapN(QCBOREncodeContext *pMe,
+ int nLabel,
+ uint8_t uSimple)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddSimple(pMe, uSimple);
@@ -3405,14 +3859,16 @@
}
static inline void
-QCBOREncode_OpenArrayIndefiniteLengthInMap(QCBOREncodeContext *pMe, const char *szLabel)
+QCBOREncode_OpenArrayIndefiniteLengthInMap(QCBOREncodeContext *pMe,
+ const char *szLabel)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_OpenArrayIndefiniteLength(pMe);
}
static inline void
-QCBOREncode_OpenArrayIndefiniteLengthInMapN(QCBOREncodeContext *pMe, int64_t nLabel)
+QCBOREncode_OpenArrayIndefiniteLengthInMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_OpenArrayIndefiniteLength(pMe);
@@ -3432,14 +3888,16 @@
}
static inline void
-QCBOREncode_OpenMapIndefiniteLengthInMap(QCBOREncodeContext *pMe, const char *szLabel)
+QCBOREncode_OpenMapIndefiniteLengthInMap(QCBOREncodeContext *pMe,
+ const char *szLabel)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_OpenMapIndefiniteLength(pMe);
}
static inline void
-QCBOREncode_OpenMapIndefiniteLengthInMapN(QCBOREncodeContext *pMe, int64_t nLabel)
+QCBOREncode_OpenMapIndefiniteLengthInMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_OpenMapIndefiniteLength(pMe);
@@ -3486,14 +3944,18 @@
}
static inline void
-QCBOREncode_AddEncodedToMap(QCBOREncodeContext *pMe, const char *szLabel, UsefulBufC Encoded)
+QCBOREncode_AddEncodedToMap(QCBOREncodeContext *pMe,
+ const char *szLabel,
+ UsefulBufC Encoded)
{
QCBOREncode_AddSZString(pMe, szLabel);
QCBOREncode_AddEncoded(pMe, Encoded);
}
static inline void
-QCBOREncode_AddEncodedToMapN(QCBOREncodeContext *pMe, int64_t nLabel, UsefulBufC Encoded)
+QCBOREncode_AddEncodedToMapN(QCBOREncodeContext *pMe,
+ int64_t nLabel,
+ UsefulBufC Encoded)
{
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddEncoded(pMe, Encoded);
diff --git a/inc/qcbor/qcbor_spiffy_decode.h b/inc/qcbor/qcbor_spiffy_decode.h
index 0faddc3..f2e1592 100644
--- a/inc/qcbor/qcbor_spiffy_decode.h
+++ b/inc/qcbor/qcbor_spiffy_decode.h
@@ -1,15 +1,15 @@
-/*============================================================================
- qcbor_spiffy_decode.h -- higher-level easier-to-use CBOR decoding.
-
- Copyright (c) 2020-2021, Laurence Lundblade. All rights reserved.
- Copyright (c) 2021, Arm Limited. All rights reserved.
-
- SPDX-License-Identifier: BSD-3-Clause
-
- See BSD-3-Clause license in README.md
-
- Forked from qcbor_decode.h on 7/23/2020
- ============================================================================*/
+/* ==========================================================================
+ * qcbor_spiffy_decode.h -- higher-level easier-to-use CBOR decoding.
+ *
+ * Copyright (c) 2020-2023, Laurence Lundblade. All rights reserved.
+ * Copyright (c) 2021, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * See BSD-3-Clause license in README.md
+ *
+ * Forked from qcbor_decode.h on 7/23/2020
+ * ========================================================================== */
#ifndef qcbor_spiffy_decode_h
#define qcbor_spiffy_decode_h
@@ -26,1662 +26,1783 @@
/**
- @file qcbor_spiffy_decode.h
-
- @anchor SpiffyDecode
- # Spiffy Decode
-
- This section discusses spiffy decoding assuming familiarity with
- the general description of decoding in the
- @ref BasicDecode section.
-
- Spiffy decode is extra decode features over and above the @ref
- BasicDecode features that generally are easier to use, mirror the
- encoding functions better and can result in smaller code size for
- larger and more complex CBOR protocols. In particular, spiffy decode
- facilitates getting the next data item of a specific type, setting an
- error if it is not of that type. It facilitates explicitly entering
- and exiting arrays and maps. It facilates fetching items by label
- from a map including duplicate label detection.
-
- Encoded CBOR can be viewed to have a tree structure where the leaf
- nodes are non-aggregate types like integers and strings and the
- intermediate nodes are either arrays or maps. Fundamentally, all
- decoding is a pre-order traversal of the tree. Calling
- QCBORDecode_GetNext() repeatedly will perform this.
-
- This pre-order traversal gives natural decoding of arrays where the
- array members are taken in order, but does not give natural decoding
- of maps where access by label is usually preferred. Using the
- QCBORDecode_EnterMap() and QCBORDecode_GetXxxxInMapX() methods like
- QCBORDecode_GetInt64InMapN(), map items can be accessed by
- label. QCBORDecode_EnterMap() bounds decoding to a particular
- map. QCBORDecode_GetXxxxInMapX() methods allows decoding the item of
- a particular label in the particular map. This can be used with
- nested maps by using QCBORDecode_EnterMapFromMapX().
-
- When QCBORDecode_EnterMap() is called, pre-order traversal continues
- to work. There is a cursor that is run over the tree with calls to
- QCBORDecode_GetNext(). This can be intermixed with calls to
- QCBORDecode_GetXxxxInMapX(). The pre-order traversal is limited just
- to the map entered. Attempts to QCBORDecode_GetNext() beyond the end
- of the map will give the @ref QCBOR_ERR_NO_MORE_ITEMS error.
-
- There is also QCBORDecode_EnterArray() to decode arrays. It will
- narrow the traversal to the extent of the array entered.
-
- All the QCBORDecode_GetXxxxInMapX() methods support duplicate label
- detection and will result in an error if the map has duplicate
- labels.
-
- All the QCBORDecode_GetXxxxInMapX() methods are implemented by
- performing the pre-order traversal of the map to find the labeled
- item everytime it is called. It doesn't build up a hash table, a
- binary search tree or some other efficiently searchable structure
- internally. For simple trees this is fine and for high-speed CPUs
- this is fine, but for complex trees on slow CPUs, it may have
- performance issues (these have not be quantified yet). One way ease
- this is to use QCBORDecode_GetItemsInMap() which allows decoding of a
- list of items expected in an map in one traveral.
-
- @anchor Tag-Usage
- ## Tag Usage
-
- Data types beyond the basic CBOR types of numbers, strings, maps and
- arrays are called tags. The main registry of these new types is in
- the IANA CBOR tags registry. These new types may be simple such a
- number that is to be interpreted as a date, or of moderate complexity
- such as defining a decimal fraction that is an array containing a
- mantissa and exponent, or complex such as format for signing and
- encryption.
-
- When a tag occurs in a protocol it is encoded as an integer tag
- number plus the content of the tag.
-
- The content format of a tag may also be "borrowed". For example, a
- protocol definition may say that a particular data item is an epoch
- date just like tag 1, but not actually tag 1. In practice the
- difference is the presence or absence of the integer tag number in
- the encoded CBOR.
-
- The decoding functions for these new types takes a tag requirement
- parameter to say whether the item is a tag, is just borrowing the
- content format and is not a tag, or whether either is OK.
-
- If the parameter indicates the item must be a tag (@ref
- QCBOR_TAG_REQUIREMENT_TAG), then @ref QCBOR_ERR_UNEXPECTED_TYPE is
- set if it is not one of the expected tag types. To decode correctly
- the contents of the tag must also be of the correct type. For
- example, to decode an epoch date tag the content must be an integer
- or floating-point value.
-
- If the parameter indicates it should not be a tag
- (@ref QCBOR_TAG_REQUIREMENT_NOT_A_TAG), then
- @ref QCBOR_ERR_UNEXPECTED_TYPE set if it is a tag or the type of the
- encoded CBOR is not what is expected. In the example of an epoch
- date, the data type must be an integer or floating-point value. This
- is the case where the content format of a tag is borrowed.
-
- The parameter can also indicate that either a tag or no tag is
- allowed ( @ref QCBOR_TAG_REQUIREMENT_OPTIONAL_TAG ). A good protocol
- design should however be clear and choose one or the other and not
- need this option. This is a way to implement "be liberal in what you
- accept", however these days that is less in favor. See
- https://tools.ietf.org/id/draft-thomson-postel-was-wrong-03.html.
-
- Map searching works with indefinite length strings. A string
- allocator must be set up the same as for any handling of indefinite
- length strings. However, It currently over-allocates memory from the
- string pool and thus requires a much larger string pool than it
- should. The over-allocation happens every time a map is searched by
- label. (This may be corrected in the future).
-*/
+ * @file qcbor_spiffy_decode.h
+ *
+ * @anchor SpiffyDecode
+ * # Spiffy Decode
+ *
+ * This section discusses spiffy decoding assuming familiarity with
+ * the general description of decoding in the
+ * @ref BasicDecode section.
+ *
+ * Spiffy decode is extra decode features over and above the @ref
+ * BasicDecode features that generally are easier to use, mirror the
+ * encoding functions better and can result in smaller code size for
+ * larger and more complex CBOR protocols. In particular, spiffy
+ * decode facilitates getting the next data item of a specific type,
+ * setting an error if it is not of that type. It facilitates
+ * explicitly entering and exiting arrays and maps. It facilates
+ * fetching items by label from a map including duplicate label
+ * detection.
+ *
+ * Encoded CBOR can be viewed to have a tree structure where the leaf
+ * nodes are non-aggregate types like integers and strings and the
+ * intermediate nodes are either arrays or maps. Fundamentally, all
+ * decoding is a pre-order traversal of the tree. Calling
+ * QCBORDecode_GetNext() repeatedly will perform this.
+ *
+ * This pre-order traversal gives natural decoding of arrays where the
+ * array members are taken in order, but does not give natural decoding
+ * of maps where access by label is usually preferred. Using the
+ * QCBORDecode_EnterMap() and QCBORDecode_GetXxxxInMapX() methods like
+ * QCBORDecode_GetInt64InMapN(), map items can be accessed by
+ * label. QCBORDecode_EnterMap() bounds decoding to a particular
+ * map. QCBORDecode_GetXxxxInMapX() methods allows decoding the item of
+ * a particular label in the particular map. This can be used with
+ * nested maps by using QCBORDecode_EnterMapFromMapX().
+ *
+ * When QCBORDecode_EnterMap() is called, pre-order traversal
+ * continues to work. There is a cursor that is run over the tree with
+ * calls to QCBORDecode_GetNext(). This can be intermixed with calls
+ * TODO: this is not quite true
+ * to QCBORDecode_GetXxxxInMapX(). The pre-order traversal is limited
+ * just to the map entered. Attempts to QCBORDecode_GetNext() beyond
+ * the end of the map will give the @ref QCBOR_ERR_NO_MORE_ITEMS
+ * error.
+ *
+ * There is also QCBORDecode_EnterArray() to decode arrays. It will
+ * narrow the traversal to the extent of the array entered.
+ *
+ * All the QCBORDecode_GetXxxxInMapX() methods support duplicate label
+ * detection and will result in an error if the map has duplicate
+ * labels.
+ *
+ * All the QCBORDecode_GetXxxxInMapX() methods are implemented by
+ * performing the pre-order traversal of the map to find the labeled
+ * item everytime it is called. It doesn't build up a hash table, a
+ * binary search tree or some other efficiently searchable structure
+ * internally. For simple trees this is fine and for high-speed CPUs
+ * this is fine, but for complex trees on slow CPUs, it may have
+ * performance issues (these have not be quantified yet). One way ease
+ * this is to use QCBORDecode_GetItemsInMap() which allows decoding of
+ * a list of items expected in an map in one traveral.
+ *
+ * @anchor Tag-Usage
+ * ## Tag Usage
+ *
+ * Data types beyond the basic CBOR types of numbers, strings, maps and
+ * arrays are called tags. The main registry of these new types is in
+ * the IANA CBOR tags registry. These new types may be simple such a
+ * number that is to be interpreted as a date, or of moderate complexity
+ * such as defining a decimal fraction that is an array containing a
+ * mantissa and exponent, or complex such as format for signing and
+ * encryption.
+ *
+ * When a tag occurs in a protocol it is encoded as an integer tag
+ * number plus the content of the tag.
+ *
+ * The content format of a tag may also be "borrowed". For example, a
+ * protocol definition may say that a particular data item is an epoch
+ * date just like tag 1, but not actually tag 1. In practice the
+ * difference is the presence or absence of the integer tag number in
+ * the encoded CBOR.
+ *
+ * The decoding functions for these new types takes a tag requirement
+ * parameter to say whether the item is a tag, is just borrowing the
+ * content format and is not a tag, or whether either is OK.
+ *
+ * If the parameter indicates the item must be a tag (@ref
+ * QCBOR_TAG_REQUIREMENT_TAG), then @ref QCBOR_ERR_UNEXPECTED_TYPE is
+ * set if it is not one of the expected tag types. To decode correctly
+ * the contents of the tag must also be of the correct type. For
+ * example, to decode an epoch date tag the content must be an integer
+ * or floating-point value.
+ *
+ * If the parameter indicates it should not be a tag
+ * (@ref QCBOR_TAG_REQUIREMENT_NOT_A_TAG), then
+ * @ref QCBOR_ERR_UNEXPECTED_TYPE set if it is a tag or the type of the
+ * encoded CBOR is not what is expected. In the example of an epoch
+ * date, the data type must be an integer or floating-point value. This
+ * is the case where the content format of a tag is borrowed.
+ *
+ * The parameter can also indicate that either a tag or no tag is
+ * allowed ( @ref QCBOR_TAG_REQUIREMENT_OPTIONAL_TAG ). A good protocol
+ * design should however be clear and choose one or the other and not
+ * need this option. This is a way to implement "be liberal in what you
+ * accept", however these days that is less in favor. See
+ * https://tools.ietf.org/id/draft-thomson-postel-was-wrong-03.html.
+ *
+ * Map searching works with indefinite length strings. A string
+ * allocator must be set up the same as for any handling of indefinite
+ * length strings. However, It currently over-allocates memory from the
+ * string pool and thus requires a much larger string pool than it
+ * should. The over-allocation happens every time a map is searched by
+ * label. (This may be corrected in the future).
+ */
/** The data item must be a tag of the expected type. It is an error
- if it is not. For example when calling QCBORDecode_GetEpochDate(),
- the data item must be an @ref CBOR_TAG_DATE_EPOCH tag.
- See @ref Tag-Usage. */
+ * if it is not. For example when calling QCBORDecode_GetEpochDate(),
+ * the data item must be an @ref CBOR_TAG_DATE_EPOCH tag. See
+ * @ref Tag-Usage. */
#define QCBOR_TAG_REQUIREMENT_TAG 0
/** The data item must be of the type expected for content data type
- being fetched. It is an error if it is not. For example, when
- calling QCBORDecode_GetEpochDate() and it must not be an @ref
- CBOR_TAG_DATE_EPOCH tag. See @ref Tag-Usage. */
+ * being fetched. It is an error if it is not. For example, when
+ * calling QCBORDecode_GetEpochDate() and it must not be an @ref
+ * CBOR_TAG_DATE_EPOCH tag. See @ref Tag-Usage. */
#define QCBOR_TAG_REQUIREMENT_NOT_A_TAG 1
/** Either of the above two are allowed. This allows implementation of
- being liberal in what you receive, but it is better if CBOR-based
- protocols pick one and stick to and not required the reciever to
- take either. See @ref Tag-Usage. */
+ * being liberal in what you receive, but it is better if CBOR-based
+ * protocols pick one and stick to and not required the reciever to
+ * take either. See @ref Tag-Usage. */
#define QCBOR_TAG_REQUIREMENT_OPTIONAL_TAG 2
/** Add this into the above value if other tags not processed by QCBOR
- are to be allowed to surround the data item. See @ref Tag-Usage. */
+ * are to be allowed to surround the data item. See @ref Tag-Usage. */
#define QCBOR_TAG_REQUIREMENT_ALLOW_ADDITIONAL_TAGS 0x80
/** Conversion will proceed if the CBOR item to be decoded is an
- integer or either type 0 (unsigned) or type 1 (negative). */
+ * integer or either type 0 (unsigned) or type 1 (negative). */
#define QCBOR_CONVERT_TYPE_XINT64 0x01
/** Conversion will proceed if the CBOR item to be decoded is either
- double, single or half-precision floating-point (major type 7). */
+ * double, single or half-precision floating-point (major type 7). */
#define QCBOR_CONVERT_TYPE_FLOAT 0x02
/** Conversion will proceed if the CBOR item to be decoded is a big
- number, positive or negative (tag 2 or tag 3). */
+ * number, positive or negative (tag 2 or tag 3). */
#define QCBOR_CONVERT_TYPE_BIG_NUM 0x04
/** Conversion will proceed if the CBOR item to be decoded is a
- decimal fraction (tag 4). */
+ * decimal fraction (tag 4). */
#define QCBOR_CONVERT_TYPE_DECIMAL_FRACTION 0x08
/** Conversion will proceed if the CBOR item to be decoded is a big
- float (tag 5). */
+ * float (tag 5). */
#define QCBOR_CONVERT_TYPE_BIGFLOAT 0x10
/**
- @brief Decode next item into a signed 64-bit integer.
-
- @param[in] pCtx The decode context.
- @param[out] pnValue The returned 64-bit signed integer.
-
- The CBOR data item to decode must be a positive or negative integer
- (CBOR major type 0 or 1). If not @ref QCBOR_ERR_UNEXPECTED_TYPE is set.
-
- If the CBOR integer is either too large or too small to fit in an
- int64_t, the error @ref QCBOR_ERR_INT_OVERFLOW or @ref
- QCBOR_ERR_CONVERSION_UNDER_OVER_FLOW is set. Note that type 0
- unsigned integers can be larger than will fit in an int64_t and type
- 1 negative integers can be smaller than will fit in an int64_t.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See also QCBORDecode_GetUInt64(), QCBORDecode_GetInt64Convert() and
- QCBORDecode_GetInt64ConvertAll().
+ * @brief Decode next item into a signed 64-bit integer.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[out] pnValue The returned 64-bit signed integer.
+ *
+ * The CBOR data item to decode must be a positive or negative integer
+ * (CBOR major type 0 or 1). If not @ref QCBOR_ERR_UNEXPECTED_TYPE is set.
+ *
+ * If the CBOR integer is either too large or too small to fit in an
+ * int64_t, the error @ref QCBOR_ERR_INT_OVERFLOW or
+ * @ref QCBOR_ERR_CONVERSION_UNDER_OVER_FLOW is set. Note that type 0
+ * unsigned integers can be larger than will fit in an int64_t and
+ * type 1 negative integers can be smaller than will fit in an
+ * int64_t.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See also QCBORDecode_GetUInt64(), QCBORDecode_GetInt64Convert(),
+ * QCBORDecode_GetInt64ConvertAll() and QCBORDecode_GetDoubleConvert()
*/
-static void QCBORDecode_GetInt64(QCBORDecodeContext *pCtx,
- int64_t *pnValue);
+static void
+QCBORDecode_GetInt64(QCBORDecodeContext *pCtx,
+ int64_t *pnValue);
-static void QCBORDecode_GetInt64InMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- int64_t *pnValue);
+static void
+QCBORDecode_GetInt64InMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ int64_t *pnValue);
-static void QCBORDecode_GetInt64InMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- int64_t *pnValue);
+static void
+QCBORDecode_GetInt64InMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ int64_t *pnValue);
/**
- @brief Decode next item into a signed 64-bit integer with basic conversions.
-
- @param[in] pCtx The decode context.
- @param[in] uConvertTypes The integer conversion options.
- @param[out] pnValue The returned 64-bit signed integer.
-
- @c uConvertTypes controls what conversions this will perform and thus
- what CBOR types will be decoded. @c uConvertType is a bit map
- listing the conversions to be allowed. This function supports @ref
- QCBOR_CONVERT_TYPE_XINT64 and @ref QCBOR_CONVERT_TYPE_FLOAT
- conversions.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- If the CBOR data type can never be convered by this function or the
- conversion was not selected in @c uConversionTypes @ref
- @ref QCBOR_ERR_UNEXPECTED_TYPE is set.
-
- When converting floating-point values, the integer is rounded to the
- nearest integer using llround(). By default, floating-point suport is
- enabled for QCBOR.
-
- If floating-point HW use is disabled this will set
- @ref QCBOR_ERR_HW_FLOAT_DISABLED if a single-precision
- number is encountered. If half-precision support is disabled,
- this will set QCBOR_ERR_HALF_PRECISION_DISABLED if
- a half-precision number is encountered.
-
- If floating-point usage is disabled this will set @ref QCBOR_ERR_ALL_FLOAT_DISABLED
- if a floating point value is encountered.
-
- See also QCBORDecode_GetInt64ConvertAll() which will perform the same
- conversions as this and a lot more at the cost of adding more object
- code to your executable.
+ * @brief Decode next item into a signed 64-bit integer with basic conversions.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uConvertTypes The integer conversion options.
+ * @param[out] pnValue The returned 64-bit signed integer.
+ *
+ * @c uConvertTypes controls what conversions this will perform and
+ * thus what CBOR types will be decoded. @c uConvertType is a bit map
+ * listing the conversions to be allowed. This function supports
+ * @ref QCBOR_CONVERT_TYPE_XINT64 and @ref QCBOR_CONVERT_TYPE_FLOAT
+ * conversions.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * If the CBOR data type can never be convered by this function or the
+ * conversion was not selected in @c uConversionTypes
+ * @ref QCBOR_ERR_UNEXPECTED_TYPE is set.
+ *
+ * When converting floating-point values, the integer is rounded to
+ * the nearest integer using llround(). By default, floating-point
+ * suport is enabled for QCBOR.
+ *
+ * If floating-point HW use is disabled this will set
+ * @ref QCBOR_ERR_HW_FLOAT_DISABLED if a single-precision number is
+ * encountered. If half-precision support is disabled, this will set
+ * @ref QCBOR_ERR_HALF_PRECISION_DISABLED if a half-precision number
+ * is encountered.
+ *
+ * If floating-point usage is disabled this will set
+ * @ref QCBOR_ERR_ALL_FLOAT_DISABLED if a floating point value is
+ * encountered.
+ *
+ * See also QCBORDecode_GetInt64ConvertAll() which will perform the
+ * same conversions as this and a lot more at the cost of adding more
+ * object code to your executable.
*/
-static void QCBORDecode_GetInt64Convert(QCBORDecodeContext *pCtx,
- uint32_t uConvertTypes,
- int64_t *pnValue);
+static void
+QCBORDecode_GetInt64Convert(QCBORDecodeContext *pCtx,
+ uint32_t uConvertTypes,
+ int64_t *pnValue);
-static void QCBORDecode_GetInt64ConvertInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint32_t uConvertTypes,
- int64_t *pnValue);
+static void
+QCBORDecode_GetInt64ConvertInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint32_t uConvertTypes,
+ int64_t *pnValue);
-static void QCBORDecode_GetInt64ConvertInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint32_t uConvertTypes,
- int64_t *pnValue);
+static void
+QCBORDecode_GetInt64ConvertInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint32_t uConvertTypes,
+ int64_t *pnValue);
/**
- @brief Decode next item into a signed 64-bit integer with conversions.
-
- @param[in] pCtx The decode context.
- @param[in] uConvertTypes The integer conversion options.
- @param[out] pnValue The returned 64-bit signed integer.
-
- This is the same as QCBORDecode_GetInt64Convert() but additionally
- supports conversion from positive and negative bignums, decimal
- fractions and big floats, including decimal fractions and big floats
- that use bignums. The conversion types supported are @ref
- QCBOR_CONVERT_TYPE_XINT64, @ref QCBOR_CONVERT_TYPE_FLOAT, @ref
- QCBOR_CONVERT_TYPE_BIG_NUM, @ref QCBOR_CONVERT_TYPE_DECIMAL_FRACTION
- and @ref QCBOR_CONVERT_TYPE_BIGFLOAT.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- Note that most these types can support numbers much larger that can
- be represented by in a 64-bit integer, so @ref
- QCBOR_ERR_CONVERSION_UNDER_OVER_FLOW may often be encountered.
-
- When converting bignums and decimal fractions @ref
- QCBOR_ERR_CONVERSION_UNDER_OVER_FLOW will be set if the result is
- below 1, unless the mantissa is zero, in which case the coversion is
- successful and the value of 0 is returned.
-
- See also QCBORDecode_GetInt64ConvertAll() which does some of these
- conversions, but links in much less object code. See also
- QCBORDecode_GetUInt64ConvertAll().
-
- This relies on CBOR tags to identify big numbers, decimal fractions
- and big floats. It will not attempt to decode non-tag CBOR that might
- be one of these. (If QCBOR_DISABLE_TAGS is set, this is effectively
- the same as QCBORDecode_GetInt64Convert() because all the additional
- number types this decodes are tags).
+ * @brief Decode next item into a signed 64-bit integer with conversions.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uConvertTypes The integer conversion options.
+ * @param[out] pnValue The returned 64-bit signed integer.
+ *
+ * This is the same as QCBORDecode_GetInt64Convert() but additionally
+ * supports conversion from positive and negative bignums, decimal
+ * fractions and big floats, including decimal fractions and big floats
+ * that use bignums. The conversion types supported are
+ * @ref QCBOR_CONVERT_TYPE_XINT64, @ref QCBOR_CONVERT_TYPE_FLOAT,
+ * @ref QCBOR_CONVERT_TYPE_BIG_NUM,
+ * @ref QCBOR_CONVERT_TYPE_DECIMAL_FRACTION and
+ * @ref QCBOR_CONVERT_TYPE_BIGFLOAT.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * Note that most these types can support numbers much larger that can
+ * be represented by in a 64-bit integer, so
+ * @ref QCBOR_ERR_CONVERSION_UNDER_OVER_FLOW may often be encountered.
+ *
+ * When converting bignums and decimal fractions,
+ * @ref QCBOR_ERR_CONVERSION_UNDER_OVER_FLOW will be set if the result
+ * is below 1, unless the mantissa is zero, in which case the
+ * coversion is successful and the value of 0 is returned.
+ *
+ * See also QCBORDecode_GetInt64ConvertAll() which does some of these
+ * conversions, but links in much less object code. See also
+ * QCBORDecode_GetUInt64ConvertAll().
+ *
+ * This relies on CBOR tags to identify big numbers, decimal fractions
+ * and big floats. It will not attempt to decode non-tag CBOR that might
+ * be one of these. (If QCBOR_DISABLE_TAGS is set, this is effectively
+ * the same as QCBORDecode_GetInt64Convert() because all the additional
+ * number types this decodes are tags).
*/
-void QCBORDecode_GetInt64ConvertAll(QCBORDecodeContext *pCtx,
- uint32_t uConvertTypes,
- int64_t *pnValue);
+void
+QCBORDecode_GetInt64ConvertAll(QCBORDecodeContext *pCtx,
+ uint32_t uConvertTypes,
+ int64_t *pnValue);
-void QCBORDecode_GetInt64ConvertAllInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint32_t uConvertTypes,
- int64_t *pnValue);
-
-void QCBORDecode_GetInt64ConvertAllInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint32_t uConvertTypes,
- int64_t *pnValue);
-
-
-/**
- @brief Decode next item into an unsigned 64-bit integer.
-
- @param[in] pCtx The decode context.
- @param[out] puValue The returned 64-bit unsigned integer.
-
- This is the same as QCBORDecode_GetInt64(), but returns an unsigned integer
- and thus can only decode CBOR positive integers.
- @ref QCBOR_ERR_NUMBER_SIGN_CONVERSION is set if the input is a negative
- integer.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See also QCBORDecode_GetUInt64Convert() and QCBORDecode_GetUInt64ConvertAll().
-*/
-static void QCBORDecode_GetUInt64(QCBORDecodeContext *pCtx,
- uint64_t *puValue);
-
-static void QCBORDecode_GetUInt64InMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint64_t *puValue);
-
-static void QCBORDecode_GetUInt64InMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint64_t *puValue);
-
-
-/**
- @brief Decode next item as an unsigned 64-bit integer with basic conversions.
-
- @param[in] pCtx The decode context.
- @param[in] uConvertTypes The integer conversion options.
- @param[out] puValue The returned 64-bit unsigned integer.
-
- This is the same as QCBORDecode_GetInt64Convert(), but returns an
- unsigned integer and thus sets @ref QCBOR_ERR_NUMBER_SIGN_CONVERSION
- is set if the value to be decoded is negatve.
-
- If floating-point HW use is disabled this will set
- @ref QCBOR_ERR_HW_FLOAT_DISABLED if a single-precision
- number is encountered. If half-precision support is disabled,
- this will set QCBOR_ERR_HALF_PRECISION_DISABLED if
- a half-precision number is encountered.
-
- If floating-point usage is disabled this will set @ref QCBOR_ERR_ALL_FLOAT_DISABLED
- if a floating point value is encountered.
-
- See also QCBORDecode_GetUInt64Convert() and
- QCBORDecode_GetUInt64ConvertAll().
-*/
-static void QCBORDecode_GetUInt64Convert(QCBORDecodeContext *pCtx,
- uint32_t uConvertTypes,
- uint64_t *puValue);
-
-static void QCBORDecode_GetUInt64ConvertInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint32_t uConvertTypes,
- uint64_t *puValue);
-
-static void QCBORDecode_GetUInt64ConvertInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint32_t uConvertTypes,
- uint64_t *puValue);
-
-
-/**
- @brief Decode next item into an unsigned 64-bit integer with conversions
-
- @param[in] pCtx The decode context.
- @param[in] uConvertTypes The integer conversion options.
- @param[out] puValue The returned 64-bit unsigned integer.
-
- This is the same as QCBORDecode_GetInt64ConvertAll(), but returns an
- unsigned integer and thus sets @ref QCBOR_ERR_NUMBER_SIGN_CONVERSION
- if the value to be decoded is negatve.
-
- See also QCBORDecode_GetUInt64() and
- QCBORDecode_GetUInt64Convert().
-*/
-void QCBORDecode_GetUInt64ConvertAll(QCBORDecodeContext *pCtx,
+void
+QCBORDecode_GetInt64ConvertAllInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
uint32_t uConvertTypes,
- uint64_t *puValue);
+ int64_t *pnValue);
-void QCBORDecode_GetUInt64ConvertAllInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint32_t uConvertTypes,
- uint64_t *puValue);
-
-void QCBORDecode_GetUInt64ConvertAllInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint32_t uConvertTypes,
- uint64_t *puValue);
-
-
+void
+QCBORDecode_GetInt64ConvertAllInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint32_t uConvertTypes,
+ int64_t *pnValue);
/**
- @brief Decode the next item as a byte string
-
- @param[in] pCtx The decode context
- @param[out] pBytes The decoded byte string
-
- The CBOR item to decode must be a byte string, CBOR type 2.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- If the CBOR item to decode is not a byte string, the @ref
- QCBOR_ERR_UNEXPECTED_TYPE error is set.
+ * @brief Decode next item into an unsigned 64-bit integer.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[out] puValue The returned 64-bit unsigned integer.
+ *
+ * This is the same as QCBORDecode_GetInt64(), but returns an unsigned integer
+ * and thus can only decode CBOR positive integers.
+ * @ref QCBOR_ERR_NUMBER_SIGN_CONVERSION is set if the input is a negative
+ * integer.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See also QCBORDecode_GetUInt64Convert() and QCBORDecode_GetUInt64ConvertAll().
*/
-static void QCBORDecode_GetByteString(QCBORDecodeContext *pCtx,
- UsefulBufC *pBytes);
+static void
+QCBORDecode_GetUInt64(QCBORDecodeContext *pCtx,
+ uint64_t *puValue);
-static void QCBORDecode_GetByteStringInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- UsefulBufC *pBytes);
+static void
+QCBORDecode_GetUInt64InMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint64_t *puValue);
-static void QCBORDecode_GetByteStringInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- UsefulBufC *pBytes);
+static void
+QCBORDecode_GetUInt64InMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint64_t *puValue);
/**
- @brief Decode the next item as a text string.
+ * @brief Decode next item as an unsigned 64-bit integer with basic conversions.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uConvertTypes The integer conversion options.
+ * @param[out] puValue The returned 64-bit unsigned integer.
+ *
+ * This is the same as QCBORDecode_GetInt64Convert(), but returns an
+ * unsigned integer and thus sets @ref QCBOR_ERR_NUMBER_SIGN_CONVERSION
+ * if the value to be decoded is negatve.
+ *
+ * If floating-point HW use is disabled this will set
+ * @ref QCBOR_ERR_HW_FLOAT_DISABLED if a single-precision number is
+ * encountered. If half-precision support is disabled, this will set
+ * @ref QCBOR_ERR_HALF_PRECISION_DISABLED if a half-precision number
+ * is encountered.
+ *
+ * If floating-point usage is disabled this will set
+ * @ref QCBOR_ERR_ALL_FLOAT_DISABLED if a floating point value is
+ * encountered.
+ *
+ * See also QCBORDecode_GetUInt64Convert() and
+ * QCBORDecode_GetUInt64ConvertAll().
+ */
+static void
+QCBORDecode_GetUInt64Convert(QCBORDecodeContext *pCtx,
+ uint32_t uConvertTypes,
+ uint64_t *puValue);
- @param[in] pCtx The decode context.
- @param[out] pText The decoded byte string.
+static void
+QCBORDecode_GetUInt64ConvertInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint32_t uConvertTypes,
+ uint64_t *puValue);
- The CBOR item to decode must be a text string, CBOR type 3.
+static void
+QCBORDecode_GetUInt64ConvertInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint32_t uConvertTypes,
+ uint64_t *puValue);
- Please see @ref Decode-Errors-Overview "Decode Errors Overview". It the CBOR item
- to decode is not a text string, the @ref QCBOR_ERR_UNEXPECTED_TYPE
- error is set.
- This does no translation of line endings. See QCBOREncode_AddText()
- for a discussion of line endings in CBOR.
-*/
-static void QCBORDecode_GetTextString(QCBORDecodeContext *pCtx,
- UsefulBufC *pText);
+/**
+ * @brief Decode next item into an unsigned 64-bit integer with conversions
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uConvertTypes The integer conversion options.
+ * @param[out] puValue The returned 64-bit unsigned integer.
+ *
+ * This is the same as QCBORDecode_GetInt64ConvertAll(), but returns
+ * an unsigned integer and thus sets @ref QCBOR_ERR_NUMBER_SIGN_CONVERSION
+ * if the value to be decoded is negatve.
+ *
+ * See also QCBORDecode_GetUInt64() and QCBORDecode_GetUInt64Convert().
+ */
+void
+QCBORDecode_GetUInt64ConvertAll(QCBORDecodeContext *pCtx,
+ uint32_t uConvertTypes,
+ uint64_t *puValue);
-static void QCBORDecode_GetTextStringInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- UsefulBufC *pText);
+void
+QCBORDecode_GetUInt64ConvertAllInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint32_t uConvertTypes,
+ uint64_t *puValue);
-static void QCBORDecode_GetTextStringInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- UsefulBufC *pText);
+void
+QCBORDecode_GetUInt64ConvertAllInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint32_t uConvertTypes,
+ uint64_t *puValue);
+
+
+
+
+/**
+ * @brief Decode the next item as a byte string
+ *
+ * @param[in] pCtx The decode context.
+ * @param[out] pBytes The decoded byte string.
+ *
+ * The CBOR item to decode must be a byte string, CBOR type 2.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * If the CBOR item to decode is not a byte string, the
+ * @ref QCBOR_ERR_UNEXPECTED_TYPE error is set.
+ */
+static void
+QCBORDecode_GetByteString(QCBORDecodeContext *pCtx,
+ UsefulBufC *pBytes);
+
+static void
+QCBORDecode_GetByteStringInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ UsefulBufC *pBytes);
+
+static void
+QCBORDecode_GetByteStringInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ UsefulBufC *pBytes);
+
+
+/**
+ * @brief Decode the next item as a text string.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[out] pText The decoded byte string.
+ *
+ * The CBOR item to decode must be a text string, CBOR type 3.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ * It the CBOR item to decode is not a text string, the
+ * @ref QCBOR_ERR_UNEXPECTED_TYPE error is set.
+ *
+ * This does no translation of line endings. See QCBOREncode_AddText()
+ * for a discussion of line endings in CBOR.
+ */
+static void
+QCBORDecode_GetTextString(QCBORDecodeContext *pCtx,
+ UsefulBufC *pText);
+
+static void
+QCBORDecode_GetTextStringInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ UsefulBufC *pText);
+
+static void
+QCBORDecode_GetTextStringInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ UsefulBufC *pText);
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
/**
- @brief Decode next item into a double floating-point value.
+ * @brief Decode next item into a double floating-point value.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[out] pValue The returned floating-point value.
+ *
+ * The CBOR data item to decode must be a half-precision,
+ * single-precision or double-precision floating-point value. If not
+ * @ref QCBOR_ERR_UNEXPECTED_TYPE is set.
+ *
+ * If floating-point HW use is disabled this will set
+ * @ref QCBOR_ERR_HW_FLOAT_DISABLED if a single-precision number is
+ * encountered. If half-precision support is disabled, this will set
+ * @ref QCBOR_ERR_HALF_PRECISION_DISABLED if a half-precision number
+ * is encountered.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See also QCBORDecode_GetDoubleConvert() and
+ * QCBORDecode_GetDoubleConvertAll().
+ */
+static void
+QCBORDecode_GetDouble(QCBORDecodeContext *pCtx,
+ double *pValue);
- @param[in] pCtx The decode context
- @param[out] pValue The returned floating-point value.
+static void
+QCBORDecode_GetDoubleInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ double *pdValue);
- The CBOR data item to decode must be a half-precision,
- single-precision or double-precision floating-point value. If not
- @ref QCBOR_ERR_UNEXPECTED_TYPE is set.
-
- If floating-point HW use is disabled this will set
- @ref QCBOR_ERR_HW_FLOAT_DISABLED if a single-precision
- number is encountered. If half-precision support is disabled,
- this will set QCBOR_ERR_HALF_PRECISION_DISABLED if
- a half-precision number is encountered.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See also QCBORDecode_GetDoubleConvert() and
- QCBORDecode_GetDoubleConvertAll().
-*/
-static void QCBORDecode_GetDouble(QCBORDecodeContext *pCtx,
- double *pValue);
-
-static void QCBORDecode_GetDoubleInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- double *pdValue);
-
-static void QCBORDecode_GetDoubleInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- double *pdValue);
+static void
+QCBORDecode_GetDoubleInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ double *pdValue);
/**
- @brief Decode next item into a double floating-point value with basic conversion.
+ * @brief Decode next item into a double floating-point with basic conversion.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uConvertTypes The integer conversion options.
+ * @param[out] pdValue The returned floating-point value.
+ *
+ * This will decode CBOR integer and floating-point numbers, returning
+ * them as a double floating-point number. This function supports
- @param[in] pCtx The decode context.
- @param[in] uConvertTypes The integer conversion options.
- @param[out] pdValue The returned floating-point value.
+ * @ref QCBOR_CONVERT_TYPE_XINT64 and @ref QCBOR_CONVERT_TYPE_FLOAT
+ * conversions. If the encoded CBOR is not one of the requested types
+ * or a type not supported by this function, @ref QCBOR_ERR_UNEXPECTED_TYPE
+ * is set.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * If floating-point HW use is disabled this will set
+ * @ref QCBOR_ERR_HW_FLOAT_DISABLED if a single-precision number is
+ * encountered. If half-precision support is disabled, this will set
+ * @ref QCBOR_ERR_HALF_PRECISION_DISABLED if a half-precision number is
+ * encountered.
+ *
+ * Positive and negative integers can always be converted to
+ * floating-point, so this will never error on CBOR major type 0 or 1.
+ *
+ * Note that a large 64-bit integer can have more precision (64 bits)
+ * than even a double floating-point (52 bits) value, so there is loss
+ * of precision in some conversions.
+ *
+ * See also QCBORDecode_GetDouble() and QCBORDecode_GetDoubleConvertAll().
+ */
+static void
+QCBORDecode_GetDoubleConvert(QCBORDecodeContext *pCtx,
+ uint32_t uConvertTypes,
+ double *pdValue);
- This will decode CBOR integer and floating-point numbers, returning
- them as a double floating-point number. This function supports @ref
- QCBOR_CONVERT_TYPE_XINT64 and @ref QCBOR_CONVERT_TYPE_FLOAT
- conversions. If the encoded CBOR is not one of the requested types or a type
- not supported by this function, @ref QCBOR_ERR_UNEXPECTED_TYPE is
- set.
+static void
+QCBORDecode_GetDoubleConvertInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint32_t uConvertTypes,
+ double *pdValue);
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- If floating-point HW use is disabled this will set
- @ref QCBOR_ERR_HW_FLOAT_DISABLED if a single-precision
- number is encountered. If half-precision support is disabled,
- this will set QCBOR_ERR_HALF_PRECISION_DISABLED if
- a half-precision number is encountered.
-
- Positive and negative integers can always be converted to
- floating-point, so this will never error on CBOR major type 0 or 1.
-
- Note that a large 64-bit integer can have more precision (64 bits)
- than even a double floating-point (52 bits) value, so there is loss
- of precision in some conversions.
-
- See also QCBORDecode_GetDouble() and QCBORDecode_GetDoubleConvertAll().
-*/
-static void QCBORDecode_GetDoubleConvert(QCBORDecodeContext *pCtx,
- uint32_t uConvertTypes,
- double *pdValue);
-
-static void QCBORDecode_GetDoubleConvertInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint32_t uConvertTypes,
- double *pdValue);
-
-static void QCBORDecode_GetDoubleConvertInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint32_t uConvertTypes,
- double *pdValue);
+static void
+QCBORDecode_GetDoubleConvertInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint32_t uConvertTypes,
+ double *pdValue);
/**
- @brief Decode next item as a double floating-point value with conversion.
+ * @brief Decode next item as a double floating-point value with conversion.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uConvertTypes The integer conversion options.
+ * @param[out] pdValue The returned floating-point value.
+ *
+ * This is the same as QCBORDecode_GetDoubleConvert() but supports
+ * many more conversions at the cost of linking in more object
+ * code. The conversion types supported are @ref QCBOR_CONVERT_TYPE_XINT64,
+ * @ref QCBOR_CONVERT_TYPE_FLOAT, @ref QCBOR_CONVERT_TYPE_BIG_NUM,
+ * @ref QCBOR_CONVERT_TYPE_DECIMAL_FRACTION and
+ * @ref QCBOR_CONVERT_TYPE_BIGFLOAT.
+ *
+ * Big numbers, decimal fractions and big floats that are too small or
+ * too large to be reprented as a double floating-point number will be
+ * returned as plus or minus zero or infinity rather than setting an
+ * under or overflow error.
+ *
+ * There is often loss of precision in the conversion.
+ *
+ * See also QCBORDecode_GetDoubleConvert() and QCBORDecode_GetDoubleConvert().
+ */
+void
+QCBORDecode_GetDoubleConvertAll(QCBORDecodeContext *pCtx,
+ uint32_t uConvertTypes,
+ double *pdValue);
- @param[in] pCtx The decode context.
- @param[in] uConvertTypes The integer conversion options.
- @param[out] pdValue The returned floating-point value.
+void
+QCBORDecode_GetDoubleConvertAllInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint32_t uConvertTypes,
+ double *pdValue);
- This is the same as QCBORDecode_GetDoubleConvert() but supports many
- more conversions at the cost of linking in more object code. The
- conversion types supported are @ref QCBOR_CONVERT_TYPE_XINT64, @ref
- QCBOR_CONVERT_TYPE_FLOAT, @ref QCBOR_CONVERT_TYPE_BIG_NUM, @ref
- QCBOR_CONVERT_TYPE_DECIMAL_FRACTION and @ref
- QCBOR_CONVERT_TYPE_BIGFLOAT.
-
- Big numbers, decimal fractions and big floats that are too small or
- too large to be reprented as a double floating-point number will be
- returned as plus or minus zero or infinity rather than setting an
- under or overflow error.
-
- There is often loss of precision in the conversion.
-
- See also QCBORDecode_GetDoubleConvert() and QCBORDecode_GetDoubleConvert().
-*/
-void QCBORDecode_GetDoubleConvertAll(QCBORDecodeContext *pCtx,
- uint32_t uConvertTypes,
- double *pdValue);
-
-void QCBORDecode_GetDoubleConvertAllInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint32_t uConvertTypes,
- double *pdValue);
-
-void QCBORDecode_GetDoubleConvertAllInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint32_t uConvertTypes,
- double *pdValue);
+void
+QCBORDecode_GetDoubleConvertAllInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint32_t uConvertTypes,
+ double *pdValue);
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
/**
- @brief Enter an array for decoding in bounded mode.
-
- @param[in] pCtx The decode context.
- @param[out] pItem The optionally returned QCBORItem that has the
- label and tags for the array. May be @c NULL (and
- usually is).
-
- This enters an array for decoding in bounded mode. The items in array
- are decoded in order the same as when not in bounded mode, but the
- decoding will not proceed past the end or the array. The error @ref
- QCBOR_ERR_NO_MORE_ITEMS will be set when the end of the array is
- encountered. To decode past the end of the array,
- QCBORDecode_ExitArray() must be called. Also, QCBORDecode_Finish()
- will return an error if all arrays that were enetered are not exited.
-
- This works the same for definite and indefinite length arrays.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- If attempting to enter a data item that is not an array @ref
- QCBOR_ERR_UNEXPECTED_TYPE wil be set.
-
- Nested arrays and maps may be entered to a depth of @ref
- QCBOR_MAX_ARRAY_NESTING.
-
- See also QCBORDecode_ExitArray(), QCBORDecode_EnterMap() and
- QCBORDecode_EnterBstrWrapped().
-*/
-static void QCBORDecode_EnterArray(QCBORDecodeContext *pCtx, QCBORItem *pItem);
-
-void QCBORDecode_EnterArrayFromMapN(QCBORDecodeContext *pMe, int64_t uLabel);
-
-void QCBORDecode_EnterArrayFromMapSZ(QCBORDecodeContext *pMe, const char *szLabel);
-
-
-/**
- @brief Exit an array that has been enetered.
-
- @param[in] pCtx The decode context.
-
- An array must have been entered for this to succeed.
-
- The items in the array that was entered do not have to have been
- consumed for this to succeed.
-
- This sets the pre-order traversal cursor to the item after the array
- that was exited.
-
- This will result in an error if any item in the array is not well
- formed (since all items in the array must be decoded to find its
- end), or there are not enough items in the array.
-*/
-static void QCBORDecode_ExitArray(QCBORDecodeContext *pCtx);
-
-
-
-
-/**
- @brief Enter a map for decoding and searching.
-
- @param[in] pCtx The decode context.
- @param[out] pItem The optionally returned QCBORItem that has the
- label and tags for the map. May be @c NULL (and
- usually is).
-
- The next item in the CBOR input must be map or this sets an error.
-
- This puts the decoder in bounded mode which narrows decoding to the
- map entered and enables getting items by label.
-
- All items in the map must be well-formed to be able to search it by
- label because a full traversal is done for each search. If not, the
- search will retun an error for the item that is not well-formed.
- This will be the first non-well-formed item which may not be the item
- with the label that is the target of the search.
-
- Nested maps can be decoded like this by entering each map in turn.
-
- Call QCBORDecode_ExitMap() to exit the current map decoding
- level. When all map decoding layers are exited then bounded mode is
- fully exited.
-
- While in bounded mode, QCBORDecode_GetNext() works as usual on the
- map and the in-order traversal cursor is maintained. It starts out at
- the first item in the map just entered. Attempts to get items off the
- end of the map will give error @ref QCBOR_ERR_NO_MORE_ITEMS rather
- going to the next item after the map as it would when not in bounded
- mode.
-
- Exiting leaves the pre-order cursor at the data item following the
- last entry in the map or at the end of the input CBOR if there
- nothing after the map.
-
- Entering and Exiting a map is a way to skip over an entire map and
- its contents. After QCBORDecode_ExitMap(), the pre-order traversal
- cursor will be at the first item after the map.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See also QCBORDecode_EnterArray() and QCBORDecode_EnterBstrWrapped().
- Entering and exiting any nested combination of maps, arrays and
- bstr-wrapped CBOR is supported up to the maximum of @ref
- QCBOR_MAX_ARRAY_NESTING.
+ * @brief Enter an array for decoding in bounded mode.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[out] pItem The optionally returned QCBORItem that has the
+ * label and tags for the array. May be @c NULL (and
+ * usually is).
+ *
+ * This enters an array for decoding in bounded mode. The items in
+ * array are decoded in order the same as when not in bounded mode,
+ * but the decoding will not proceed past the end or the array. The
+ * error @ref QCBOR_ERR_NO_MORE_ITEMS will be set when the end of the
+ * array is encountered. To decode past the end of the array,
+ * QCBORDecode_ExitArray() must be called. Also, QCBORDecode_Finish()
+ * will return an error if all arrays that were enetered are not
+ * exited.
+ *
+ * This works the same for definite and indefinite length arrays.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * If attempting to enter a data item that is not an array
+ * @ref QCBOR_ERR_UNEXPECTED_TYPE wil be set.
+ *
+ * Nested arrays and maps may be entered to a depth of
+ * @ref QCBOR_MAX_ARRAY_NESTING.
+ *
+ * See also QCBORDecode_ExitArray(), QCBORDecode_EnterMap() and
+ * QCBORDecode_EnterBstrWrapped().
*/
-static void QCBORDecode_EnterMap(QCBORDecodeContext *pCtx, QCBORItem *pItem);
+static void
+QCBORDecode_EnterArray(QCBORDecodeContext *pCtx, QCBORItem *pItem);
-void QCBORDecode_EnterMapFromMapN(QCBORDecodeContext *pCtx, int64_t nLabel);
+void
+QCBORDecode_EnterArrayFromMapN(QCBORDecodeContext *pMe, int64_t uLabel);
-void QCBORDecode_EnterMapFromMapSZ(QCBORDecodeContext *pCtx, const char *szLabel);
+void
+QCBORDecode_EnterArrayFromMapSZ(QCBORDecodeContext *pMe, const char *szLabel);
/**
- @brief Exit a map that has been enetered.
-
- @param[in] pCtx The decode context.
-
- A map must have been entered for this to succeed.
-
- The items in the map that was entered do not have to have been
- consumed for this to succeed.
-
- This sets the pre-order traversal cursor to the item after the map
- that was exited.
-
- This will result in an error if any item in the map is not well
- formed (since all items in the map must be decoded to find its end),
- or there are not enough items in the map.
-*/
-static void QCBORDecode_ExitMap(QCBORDecodeContext *pCtx);
-
-
-/**
- @brief Reset traversal cursor to start of map, array, byte-string
- wrapped CBOR or start of input.
-
- @param[in] pCtx The decode context.
-
- If an array, map or wrapping byte string has been entered this sets
- the traversal cursor to its beginning. If several arrays, maps or
- byte strings have been entered, this sets the traversal cursor to the
- beginning of the one most recently entered.
-
- If no map or array has been entered, this resets the traversal cursor
- to the beginning of the input CBOR.
-
- This also resets the error state.
+ * @brief Exit an array that has been enetered.
+ *
+ * @param[in] pCtx The decode context.
+ *
+ * An array must have been entered for this to succeed.
+ *
+ * The items in the array that was entered do not have to have been
+ * consumed for this to succeed.
+ *
+ * This sets the pre-order traversal cursor to the item after the
+ * array that was exited.
+ *
+ * This will result in an error if any item in the array is not well
+ * formed (since all items in the array must be decoded to find its
+ * end), or there are not enough items in the array.
*/
-void QCBORDecode_Rewind(QCBORDecodeContext *pCtx);
+static void
+QCBORDecode_ExitArray(QCBORDecodeContext *pCtx);
+
+
/**
- @brief Get an item in map by label and type.
-
- @param[in] pCtx The decode context.
- @param[in] nLabel The integer label.
- @param[in] uQcborType The QCBOR type. One of @c QCBOR_TYPE_XXX.
- @param[out] pItem The returned item.
-
- A map must have been entered to use this. If not @ref
- QCBOR_ERR_MAP_NOT_ENTERED is set.
-
- The map is searched for an item of the requested label and type.
- @ref QCBOR_TYPE_ANY can be given to search for the label without
- matching the type.
-
- This will always search the entire map. This will always perform
- duplicate label detection, setting @ref QCBOR_ERR_DUPLICATE_LABEL if
- there is more than one occurance of the label being searched for.
-
- Duplicate label detection is performed for the item being sought, but
- only for the item being sought.
-
- This performs a full decode of every item in the map being searched,
- which involves a full traversal of every item. For maps with little
- nesting, this is of little consequence, but may be of consequence for
- large deeply nested CBOR structures on slow CPUs.
-
- The position of the pre-order traversal cursor is not changed.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See also QCBORDecode_GetItemsInMap() for error discussion.
-*/
-void QCBORDecode_GetItemInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uQcborType,
- QCBORItem *pItem);
-
-void QCBORDecode_GetItemInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uQcborType,
- QCBORItem *pItem);
-
-
-/**
- @brief Get a group of labeled items all at once from a map
-
- @param[in] pCtx The decode context.
- @param[in,out] pItemList On input the items to search for. On output the returned items.
-
- This gets several labeled items out of a map.
-
- @c pItemList is an array of items terminated by an item with @c
- uLabelType @ref QCBOR_TYPE_NONE.
-
- On input the labels to search for are in the @c uLabelType and label
- fields in the items in @c pItemList.
-
- Also on input are the requested QCBOR types in the field @c
- uDataType. To match any type, searching just by label, @c uDataType
- can be @ref QCBOR_TYPE_ANY.
-
- This is a CPU-efficient way to decode a bunch of items in a map. It
- is more efficient than scanning each individually because the map
- only needs to be traversed once.
-
- This will return maps and arrays that are in the map, but provides no
- way to descend into and decode them. Use
- QCBORDecode_EnterMapinMapN(), QCBORDecode_EnterArrayInMapN() and such
- to descend into and process maps and arrays.
-
- The position of the pre-order traversal cursor is not changed.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- The following errors are set:
-
- @ref QCBOR_ERR_MAP_NOT_ENTERED when calling this without previousl
- calling QCBORDecode_EnterMap() or other methods to enter a map.
-
- @ref QCBOR_ERR_DUPLICATE_LABEL when one of the labels being searched
- for is duplicate.
-
- @ref QCBOR_ERR_HIT_END or other errors classifed as not-well-formed
- by QCBORDecode_IsNotWellFormed() as it is not possible to traverse
- maps that have any non-well formed items.
-
- @ref QCBOR_ERR_UNEXPECTED_TYPE when the type of an item found by
- matching a label is not the type requested.
-
- @ref QCBOR_ERR_ARRAY_NESTING_TOO_DEEP and other implementation limit
- errors as it is not possible to travere a map beyond the limits of
- the implementation.
-
- The error may occur on items that are not being searched for. For
- example, it is impossible to traverse over a map that has an array in
- it that is not closed or over array and map nesting deeper than this
- implementation can track.
-
- See also QCBORDecode_GetItemInMapN().
+ * @brief Enter a map for decoding and searching.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[out] pItem The optionally returned QCBORItem that has the
+ * label and tags for the map. May be @c NULL (and
+ * usually is).
+ *
+ * The next item in the CBOR input must be map or this sets an error.
+ *
+ * This puts the decoder in bounded mode which narrows decoding to the
+ * map entered and enables getting items by label.
+ *
+ * All items in the map must be well-formed to be able to search it by
+ * label because a full traversal is done for each search. If not, the
+ * search will retun an error for the item that is not well-formed.
+ * This will be the first non-well-formed item which may not be the
+ * item with the label that is the target of the search.
+ *
+ * Nested maps can be decoded like this by entering each map in turn.
+ *
+ * Call QCBORDecode_ExitMap() to exit the current map decoding
+ * level. When all map decoding layers are exited then bounded mode is
+ * fully exited.
+ *
+ * While in bounded mode, QCBORDecode_GetNext() works as usual on the
+ * map and the in-order traversal cursor is maintained. It starts out
+ * at the first item in the map just entered. Attempts to get items
+ * off the end of the map will give error @ref QCBOR_ERR_NO_MORE_ITEMS
+ * rather going to the next item after the map as it would when not in
+ * bounded mode.
+ *
+ * Exiting leaves the pre-order cursor at the data item following the
+ * last entry in the map or at the end of the input CBOR if there
+ * nothing after the map.
+ *
+ * Entering and Exiting a map is a way to skip over an entire map and
+ * its contents. After QCBORDecode_ExitMap(), the pre-order traversal
+ * cursor will be at the first item after the map.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See also QCBORDecode_EnterArray() and
+ * QCBORDecode_EnterBstrWrapped(). Entering and exiting any nested
+ * combination of maps, arrays and bstr-wrapped CBOR is supported up
+ * to the maximum of @ref QCBOR_MAX_ARRAY_NESTING.
*/
-void QCBORDecode_GetItemsInMap(QCBORDecodeContext *pCtx, QCBORItem *pItemList);
+static void
+QCBORDecode_EnterMap(QCBORDecodeContext *pCtx, QCBORItem *pItem);
+
+void
+QCBORDecode_EnterMapFromMapN(QCBORDecodeContext *pCtx, int64_t nLabel);
+
+void
+QCBORDecode_EnterMapFromMapSZ(QCBORDecodeContext *pCtx, const char *szLabel);
/**
- @brief Per-item callback for map searching.
+ * @brief Exit a map that has been enetered.
+ *
+ * @param[in] pCtx The decode context.
+ *
+ * A map must have been entered for this to succeed.
+ *
+ * The items in the map that was entered do not have to have been
+ * consumed for this to succeed.
+ *
+ * This sets the pre-order traversal cursor to the item after the map
+ * that was exited.
+ *
+ * This will result in an error if any item in the map is not well
+ * formed (since all items in the map must be decoded to find its
+ * end), or there are not enough items in the map.
+ */
+static void
+QCBORDecode_ExitMap(QCBORDecodeContext *pCtx);
- @param[in] pCallbackCtx Pointer to the caller-defined context for the callback
- @param[in] pItem The item from the map.
- The error set is intended for QCBOR errors, not general protocol
- decoding errors. If this sets other than @ref QCBOR_SUCCESS, the
- search will stop and the value it returns will be set in
- QCBORDecode_GetItemsInMapWithCallback(). The special error, @ref
- QCBOR_ERR_CALLBACK_FAIL, can be returned to indicate some protocol
- processing error that is not a CBOR error. The specific details of
- the protocol processing error can be returned the call back context.
+/**
+ * @brief Reset traversal cursor to start of map, array, byte-string
+ * wrapped CBOR or start of input.
+ *
+ * @param[in] pCtx The decode context.
+ *
+ * If an array, map or wrapping byte string has been entered this sets
+ * the traversal cursor to its beginning. If several arrays, maps or
+ * byte strings have been entered, this sets the traversal cursor to
+ * the beginning of the one most recently entered.
+ *
+ * If no map or array has been entered, this resets the traversal
+ * cursor to the beginning of the input CBOR.
+ *
+ * This also resets the error state.
+ */
+void
+QCBORDecode_Rewind(QCBORDecodeContext *pCtx);
+
+
+/**
+ * @brief Get an item in map by label and type.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] nLabel The integer label.
+ * @param[in] uQcborType The QCBOR type. One of @c QCBOR_TYPE_XXX.
+ * @param[out] pItem The returned item.
+ *
+ * A map must have been entered to use this. If not
+ * @ref QCBOR_ERR_MAP_NOT_ENTERED is set.
+ *
+ * The map is searched for an item of the requested label and type.
+ * @ref QCBOR_TYPE_ANY can be given to search for the label without
+ * matching the type.
+ *
+ * This will always search the entire map. This will always perform
+ * duplicate label detection, setting @ref QCBOR_ERR_DUPLICATE_LABEL
+ * if there is more than one occurance of the label being searched
+ * for.
+ *
+ * Duplicate label detection is performed for the item being sought,
+ * but only for the item being sought.
+ *
+ * This performs a full decode of every item in the map being
+ * searched, which involves a full traversal of every item. For maps
+ * with little nesting, this is of little consequence, but may be of
+ * consequence for large deeply nested CBOR structures on slow CPUs.
+ *
+ * The position of the pre-order traversal cursor is not changed.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See also QCBORDecode_GetItemsInMap() for error discussion.
+ */
+void
+QCBORDecode_GetItemInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uQcborType,
+ QCBORItem *pItem);
+
+void
+QCBORDecode_GetItemInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uQcborType,
+ QCBORItem *pItem);
+
+
+/**
+ * @brief Get a group of labeled items all at once from a map
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in,out] pItemList On input, the items to search for. On output,
+ * the returne *d items.
+ *
+ * This gets several labeled items out of a map.
+ *
+ * @c pItemList is an array of items terminated by an item with @c
+ * uLabelType @ref QCBOR_TYPE_NONE.
+ *
+ * On input the labels to search for are in the @c uLabelType and
+ * label fields in the items in @c pItemList.
+ *
+ * Also on input are the requested QCBOR types in the field
+ * @c uDataType. To match any type, searching just by label,
+ * @c uDataType can be @ref QCBOR_TYPE_ANY.
+ *
+ * This is a CPU-efficient way to decode a bunch of items in a map. It
+ * is more efficient than scanning each individually because the map
+ * only needs to be traversed once.
+ *
+ * This will return maps and arrays that are in the map, but provides
+ * no way to descend into and decode them. Use
+ * QCBORDecode_EnterMapinMapN(), QCBORDecode_EnterArrayInMapN() and
+ * such to descend into and process maps and arrays.
+ *
+ * The position of the pre-order traversal cursor is not changed.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * The following errors are set:
+ *
+ * @ref QCBOR_ERR_MAP_NOT_ENTERED when calling this without previousl
+ * calling QCBORDecode_EnterMap() or other methods to enter a map.
+ *
+ * @ref QCBOR_ERR_DUPLICATE_LABEL when one of the labels being searched
+ * for is duplicate.
+ *
+ * @ref QCBOR_ERR_HIT_END or other errors classifed as not-well-formed
+ * by QCBORDecode_IsNotWellFormed() as it is not possible to traverse
+ * maps that have any non-well formed items.
+ *
+ * @ref QCBOR_ERR_UNEXPECTED_TYPE when the type of an item found by
+ * matching a label is not the type requested.
+ *
+ * @ref QCBOR_ERR_ARRAY_NESTING_TOO_DEEP and other implementation
+ * limit errors as it is not possible to travere a map beyond the
+ * limits of the implementation.
+ *
+ * The error may occur on items that are not being searched for. For
+ * example, it is impossible to traverse over a map that has an array in
+ * it that is not closed or over array and map nesting deeper than this
+ * implementation can track.
+ *
+ * See also QCBORDecode_GetItemInMapN().
+ */
+void
+QCBORDecode_GetItemsInMap(QCBORDecodeContext *pCtx, QCBORItem *pItemList);
+
+
+/**
+ * @brief Per-item callback for map searching.
+ *
+ * @param[in] pCallbackCtx Pointer to the caller-defined context for the callback.
+ * @param[in] pItem The item from the map.
+ *
+ * The error set is intended for QCBOR errors, not general protocol
+ * decoding errors. If this sets other than @ref QCBOR_SUCCESS, the
+ * search will stop and the value it returns will be set in
+ * QCBORDecode_GetItemsInMapWithCallback(). The special error,
+ * @ref QCBOR_ERR_CALLBACK_FAIL, can be returned to indicate some
+ * protocol processing error that is not a CBOR error. The specific
+ * details of the protocol processing error can be returned the call
+ * back context.
*/
typedef QCBORError (*QCBORItemCallback)(void *pCallbackCtx,
const QCBORItem *pItem);
/**
- @brief Get a group of labeled items all at once from a map with a callback
-
- @param[in] pCtx The decode context.
- @param[in,out] pItemList On input the items to search for. On output the returned items.
- @param[in,out] pCallbackCtx Pointer to a context structure for @ref QCBORItemCallback
- @param[in] pfCB pointer to function of type @ref QCBORItemCallback that is called on unmatched items.
-
- This searchs a map like QCBORDecode_GetItemsInMap(), but calls a
- callback on items not matched rather than ignoring them. If @c
- pItemList is empty, the call back will be called on every item in the
- map.
-
- Like QCBORDecode_GetItemsInMap(), this only matches and calls back on
- the items at the top level of the map entered. Items in nested
- maps and arrays are skipped over and not candidate for matching or the
- callback.
-
- See QCBORItemCallback() for error handling.
+ * @brief Get a group of labeled items all at once from a map with a callback.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in,out] pItemList On input, the items to search for. On output,
+ * the returne *d items.
+ * @param[in,out] pCallbackCtx Pointer to a context structure for
+ * @ref QCBORItemCallback
+ * @param[in] pfCB Pointer to function of type
+ * @ref QCBORItemCallback that is called on
+ * unmatched items.
+ *
+ * This searchs a map like QCBORDecode_GetItemsInMap(), but calls a
+ * callback on items not matched rather than ignoring them. If @c
+ * pItemList is empty, the call back will be called on every item in the
+ * map.
+ *
+ * Like QCBORDecode_GetItemsInMap(), this only matches and calls back on
+ * the items at the top level of the map entered. Items in nested
+ * maps and arrays are skipped over and not candidate for matching or the
+ * callback.
+ *
+ * See QCBORItemCallback() for error handling.
*/
-void QCBORDecode_GetItemsInMapWithCallback(QCBORDecodeContext *pCtx,
- QCBORItem *pItemList,
- void *pCallbackCtx,
- QCBORItemCallback pfCB);
+void
+QCBORDecode_GetItemsInMapWithCallback(QCBORDecodeContext *pCtx,
+ QCBORItem *pItemList,
+ void *pCallbackCtx,
+ QCBORItemCallback pfCB);
/**
- @brief Decode the next item as a Boolean.
-
- @param[in] pCtx The decode context.
- @param[out] pbBool The decoded byte string.
-
- The CBOR item to decode must be either the CBOR simple value (CBOR
- type 7) @c true or @c false.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview". If
- the CBOR item to decode is not true or false the @ref
- QCBOR_ERR_UNEXPECTED_TYPE error is set.
+ * @brief Decode the next item as a Boolean.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[out] pbBool The decoded byte string.
+ *
+ * The CBOR item to decode must be either the CBOR simple value (CBOR
+ * type 7) @c true or @c false.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview". If
+ * the CBOR item to decode is not true or false the @ref
+ * QCBOR_ERR_UNEXPECTED_TYPE error is set.
*/
-void QCBORDecode_GetBool(QCBORDecodeContext *pCtx, bool *pbBool);
+void
+QCBORDecode_GetBool(QCBORDecodeContext *pCtx, bool *pbBool);
-void QCBORDecode_GetBoolInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- bool *pbBool);
+void
+QCBORDecode_GetBoolInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ bool *pbBool);
-void QCBORDecode_GetBoolInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- bool *pbBool);
+void
+QCBORDecode_GetBoolInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ bool *pbBool);
/**
- @brief Decode the next item as a null.
+ * @brief Decode the next item as a null.
+ *
+ * @param[in] pCtx The decode context.
+ *
+ * The CBOR item to decode must be the CBOR simple value (CBOR type 7)
+ * @c null. The reason to call this is to see if an error is returned
+ * or not indicating whether the item is a CBOR null. If it is not
+ * then the @ref QCBOR_ERR_UNEXPECTED_TYPE error is set.
+ */
+static void
+QCBORDecode_GetNull(QCBORDecodeContext *pCtx);
- @param[in] pCtx The decode context.
+static void
+QCBORDecode_GetNullInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel);
- The CBOR item to decode must be the CBOR simple value (CBOR type 7)
- @c null. The reason to call this is to see if an error is returned or
- not indicating whether the item is a CBOR null. If it is not then the
- @ref QCBOR_ERR_UNEXPECTED_TYPE error is set.
-*/
-static void QCBORDecode_GetNull(QCBORDecodeContext *pCtx);
-
-static void QCBORDecode_GetNullInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel);
-
-static void QCBORDecode_GetNullInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel);
+static void
+QCBORDecode_GetNullInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel);
/**
- @brief Decode the next item as a CBOR "undefined" item.
+ * @brief Decode the next item as a CBOR "undefined" item.
+ *
+ * @param[in] pCtx The decode context.
+ *
+ * The CBOR item to decode must be the CBOR simple value (CBOR type 7)
+ * @c undefined. The reason to call this is to see if an error is
+ * returned or not indicating whether the item is a CBOR undefed
+ * item. If it is not then the @ref QCBOR_ERR_UNEXPECTED_TYPE error is
+ * set.
+ */
+static void
+QCBORDecode_GetUndefined(QCBORDecodeContext *pCtx);
- @param[in] pCtx The decode context.
+static void
+QCBORDecode_GetUndefinedInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel);
- The CBOR item to decode must be the CBOR simple value (CBOR type 7)
- @c undefined. The reason to call this is to see if an error is
- returned or not indicating whether the item is a CBOR undefed
- item. If it is not then the @ref QCBOR_ERR_UNEXPECTED_TYPE error is
- set.
-*/
-static void QCBORDecode_GetUndefined(QCBORDecodeContext *pCtx);
-
-static void QCBORDecode_GetUndefinedInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel);
-
-static void QCBORDecode_GetUndefinedInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel);
+static void
+QCBORDecode_GetUndefinedInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel);
/**
- @brief Decode the next item as a date string.
+ * @brief Decode the next item as a date string.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pDateString The decoded date.
+ *
+ * This decodes the standard CBOR date/time string tag, integer tag
+ * number of 0, or encoded CBOR that is not a tag, but borrows the
+ * date string content format.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See @ref Tag-Usage for discussion on tag requirements.
+ *
+ * See also @ref CBOR_TAG_DATE_STRING, QCBOREncode_AddDateString() and
+ * @ref QCBOR_TYPE_DATE_STRING.
+ */
+static void
+QCBORDecode_GetDateString(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC *pDateString);
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pDateString The decoded date.
+static void
+QCBORDecode_GetDateStringInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pDateString);
- This decodes the standard CBOR date/time string tag, integer tag
- number of 0, or encoded CBOR that is not a tag, but borrows the
- date string content format.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See @ref Tag-Usage for discussion on tag requirements.
-
- See also @ref CBOR_TAG_DATE_STRING, QCBOREncode_AddDateString() and
- @ref QCBOR_TYPE_DATE_STRING.
-*/
-static void QCBORDecode_GetDateString(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC *pDateString);
-
-static void QCBORDecode_GetDateStringInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pDateString);
-
-static void QCBORDecode_GetDateStringInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pDateString);
-
-
-/**
- @brief Decode the next item as a date-only string.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pDateString The decoded date.
-
- This decodes the CBOR date-only string tag, integer tag
- number of 1004, or encoded CBOR that is not a tag, but borrows the
- date-only string content format. An example of the format
- is "1985-04-12".
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See @ref Tag-Usage for discussion on tag requirements.
-
- See also @ref CBOR_TAG_DAYS_STRING, QCBOREncode_AddDaysString() and
- @ref QCBOR_TYPE_DAYS_STRING.
-*/
-static void QCBORDecode_GetDaysString(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC *pDateString);
-
-static void QCBORDecode_GetDaysStringInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pDateString);
-
-static void QCBORDecode_GetDaysStringInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pDateString);
-
-
-/**
- @brief Decode the next item as an epoch date.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pnTime The decoded epoch date.
-
- This decodes the standard CBOR epoch date/time tag, integer tag
- number of 1. This will also decode any integer or floating-point
- number as an epoch date (a tag 1 epoch date is just an integer or
- floating-point number).
-
- This will set @ref QCBOR_ERR_DATE_OVERFLOW if the input integer will
- not fit in an @c int64_t. Note that an @c int64_t can represent a
- range of over 500 billion years with one second resolution.
-
- Floating-point dates are always returned as an @c int64_t. The
- fractional part is discarded.
-
- If the input is a floating-point date and the QCBOR library is
- compiled with some or all floating-point features disabled, the
- following errors will be set. If the input is half-precision and
- half-precision is disabled @ref QCBOR_ERR_HALF_PRECISION_DISABLED is
- set. This function needs hardware floating-point to convert the
- floating-point value to an integer so if HW floating point is
- disabled QCBOR_ERR_HW_FLOAT_DISABLED is set. If all floating-point is
- disabled then @ref QCBOR_ERR_ALL_FLOAT_DISABLED is set. A previous
- version of this function would return @ref QCBOR_ERR_FLOAT_DATE_DISABLED
- in some, but not all, cases when floating-point decoding was disabled.
-
- Floating-point dates that are plus infinity, minus infinity or NaN
- (not-a-number) will result in the @ref QCBOR_ERR_DATE_OVERFLOW error.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See @ref Tag-Usage for discussion on tag requirements.
-
- See also @ref CBOR_TAG_DATE_EPOCH, QCBOREncode_AddDateEpoch() and
- @ref QCBOR_TYPE_DATE_EPOCH.
-*/
-void QCBORDecode_GetEpochDate(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- int64_t *pnTime);
-
-void QCBORDecode_GetEpochDateInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- int64_t *pnTime);
-
-void QCBORDecode_GetEpochDateInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- int64_t *pnTime);
-
-
-/**
- @brief Decode the next item as an days-count epoch date.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pnDays The decoded epoch date.
-
- This decodes the CBOR epoch date tag, integer tag number of 100, or
- encoded CBOR that is not a tag, but borrows the content format. The
- date is the number of days (not number of seconds) before or after
- Jan 1, 1970.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See @ref Tag-Usage for discussion on tag requirements.
-
- See also @ref CBOR_TAG_DAYS_EPOCH, QCBOREncode_AddTDaysEpoch() and
- @ref QCBOR_TYPE_DAYS_EPOCH.
-*/
-void QCBORDecode_GetEpochDays(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- int64_t *pnDays);
-
-void QCBORDecode_GetEpochDaysInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- int64_t *pnDays);
-
-void QCBORDecode_GetEpochDaysInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- int64_t *pnDays);
-
-
-
-
-/**
- @brief Decode the next item as a big number.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pValue The returned big number.
- @param[out] pbIsNegative Is @c true if the big number is negative. This
- is only valid when @c uTagRequirement is
- @ref QCBOR_TAG_REQUIREMENT_TAG.
-
- This decodes a standard CBOR big number, integer tag number of 2 or
- 3, or encoded CBOR that is not a tag, but borrows the content format.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- The big number is in network byte order. The first byte in @c pValue
- is the most significant byte. There may be leading zeros.
-
- The negative value is computed as -1 - n, where n is the postive big
- number in @c pValue. There is no standard representation for
- big numbers, positive or negative in C, so this implementation leaves
- it up to the caller to apply this computation for negative big numbers.
-
- See @ref Tag-Usage for discussion on tag requirements.
-
- Determination of the sign of the big number depends on the tag
- requirement of the protocol using the big number. If the protocol
- requires tagging, @ref QCBOR_TAG_REQUIREMENT_TAG, then the sign
- indication is in the protocol and @c pbIsNegative indicates the
- sign. If the protocol doesn't use a tag, @ref
- QCBOR_TAG_REQUIREMENT_NOT_A_TAG, then the protocol design must have some
- way of indicating the sign.
-
- See also QCBORDecode_GetInt64ConvertAll(),
- QCBORDecode_GetUInt64ConvertAll() and
- QCBORDecode_GetDoubleConvertAll() which can convert big numbers.
-
- See also @ref CBOR_TAG_POS_BIGNUM, @ref CBOR_TAG_NEG_BIGNUM,
- QCBOREncode_AddPositiveBignum(), QCBOREncode_AddNegativeBignum(),
- @ref QCBOR_TYPE_POSBIGNUM and @ref QCBOR_TYPE_NEGBIGNUM.
-
-*/
-// Improvement: Add function that converts integers and other to big nums
-void QCBORDecode_GetBignum(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC *pValue,
- bool *pbIsNegative);
-
-void QCBORDecode_GetBignumInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
+static void
+QCBORDecode_GetDateStringInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
uint8_t uTagRequirement,
- UsefulBufC *pValue,
- bool *pbIsNegative);
+ UsefulBufC *pDateString);
-void QCBORDecode_GetBignumInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pValue,
- bool *pbIsNegative);
+
+/**
+ * @brief Decode the next item as a date-only string.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pDateString The decoded date.
+ *
+ * This decodes the CBOR date-only string tag, integer tag number of
+ * 1004, or encoded CBOR that is not a tag, but borrows the date-only
+ * string content format. An example of the format is "1985-04-12".
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See @ref Tag-Usage for discussion on tag requirements.
+ *
+ * See also @ref CBOR_TAG_DAYS_STRING, QCBOREncode_AddDaysString() and
+ * @ref QCBOR_TYPE_DAYS_STRING.
+ */
+static void
+QCBORDecode_GetDaysString(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC *pDateString);
+
+static void
+QCBORDecode_GetDaysStringInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pDateString);
+
+static void
+QCBORDecode_GetDaysStringInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pDateString);
+
+
+/**
+ * @brief Decode the next item as an epoch date.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pnTime The decoded epoch date.
+ *
+ * This decodes the standard CBOR epoch date/time tag, integer tag
+ * number of 1. This will also decode any integer or floating-point
+ * number as an epoch date (a tag 1 epoch date is just an integer or
+ * floating-point number).
+ *
+ * This will set @ref QCBOR_ERR_DATE_OVERFLOW if the input integer
+ * will not fit in an @c int64_t. Note that an @c int64_t can
+ * represent a range of over 500 billion years with one second
+ * resolution.
+ *
+ * Floating-point dates are always returned as an @c int64_t. The
+ * fractional part is discarded.
+ *
+ * If the input is a floating-point date and the QCBOR library is
+ * compiled with some or all floating-point features disabled, the
+ * following errors will be set. If the input is half-precision and
+ * half-precision is disabled @ref QCBOR_ERR_HALF_PRECISION_DISABLED
+ * is set. This function needs hardware floating-point to convert the
+ * floating-point value to an integer so if HW floating point is
+ * disabled @ref QCBOR_ERR_HW_FLOAT_DISABLED is set. If all
+ * floating-point is disabled then @ref QCBOR_ERR_ALL_FLOAT_DISABLED
+ * is set. A previous version of this function would return
+ * @ref QCBOR_ERR_FLOAT_DATE_DISABLED in some, but not all, cases when
+ * floating-point decoding was disabled.
+ *
+ * Floating-point dates that are plus infinity, minus infinity or NaN
+ * (not-a-number) will result in the @ref QCBOR_ERR_DATE_OVERFLOW
+ * error.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See @ref Tag-Usage for discussion on tag requirements.
+ *
+ * See also @ref CBOR_TAG_DATE_EPOCH, QCBOREncode_AddDateEpoch() and
+ * @ref QCBOR_TYPE_DATE_EPOCH.
+*/
+void
+QCBORDecode_GetEpochDate(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ int64_t *pnTime);
+
+void
+QCBORDecode_GetEpochDateInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ int64_t *pnTime);
+
+void
+QCBORDecode_GetEpochDateInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ int64_t *pnTime);
+
+
+/**
+ * @brief Decode the next item as an days-count epoch date.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pnDays The decoded epoch date.
+ *
+ * This decodes the CBOR epoch date tag, integer tag number of 100, or
+ * encoded CBOR that is not a tag, but borrows the content format. The
+ * date is the number of days (not number of seconds) before or after
+ * Jan 1, 1970.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See @ref Tag-Usage for discussion on tag requirements.
+ *
+ * See also @ref CBOR_TAG_DAYS_EPOCH, QCBOREncode_AddTDaysEpoch() and
+ * @ref QCBOR_TYPE_DAYS_EPOCH.
+*/
+void
+QCBORDecode_GetEpochDays(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ int64_t *pnDays);
+
+void
+QCBORDecode_GetEpochDaysInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ int64_t *pnDays);
+
+void
+QCBORDecode_GetEpochDaysInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ int64_t *pnDays);
+
+
+
+
+/**
+ * @brief Decode the next item as a big number.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pValue The returned big number.
+ * @param[out] pbIsNegative Is @c true if the big number is negative. This
+ * is only valid when @c uTagRequirement is
+ * @ref QCBOR_TAG_REQUIREMENT_TAG.
+ *
+ * This decodes a standard CBOR big number, integer tag number of 2 or
+ * 3, or encoded CBOR that is not a tag, but borrows the content
+ * format.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * The big number is in network byte order. The first byte in @c
+ * pValue is the most significant byte. There may be leading zeros.
+ *
+ * The negative value is computed as -1 - n, where n is the postive
+ * big number in @c pValue. There is no standard representation for
+ * big numbers, positive or negative in C, so this implementation
+ * leaves it up to the caller to apply this computation for negative
+ * big numbers.
+ *
+ * See @ref Tag-Usage for discussion on tag requirements.
+ *
+ * Determination of the sign of the big number depends on the tag
+ * requirement of the protocol using the big number. If the protocol
+ * requires tagging, @ref QCBOR_TAG_REQUIREMENT_TAG, then the sign
+ * indication is in the protocol and @c pbIsNegative indicates the
+ * sign. If the protocol doesn't use a tag, @ref QCBOR_TAG_REQUIREMENT_NOT_A_TAG,
+ * then the protocol design must have some way of indicating the sign.
+ *
+ * See also QCBORDecode_GetInt64ConvertAll(),
+ * QCBORDecode_GetUInt64ConvertAll() and
+ * QCBORDecode_GetDoubleConvertAll() which can convert big numbers.
+ *
+ * See also @ref CBOR_TAG_POS_BIGNUM, @ref CBOR_TAG_NEG_BIGNUM,
+ * QCBOREncode_AddPositiveBignum(), QCBOREncode_AddNegativeBignum(),
+ * @ref QCBOR_TYPE_POSBIGNUM and @ref QCBOR_TYPE_NEGBIGNUM.
+ */
+// Improvement: Add function that converts integers and other to big nums
+void
+QCBORDecode_GetBignum(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC *pValue,
+ bool *pbIsNegative);
+
+void
+QCBORDecode_GetBignumInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pValue,
+ bool *pbIsNegative);
+
+void
+QCBORDecode_GetBignumInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pValue,
+ bool *pbIsNegative);
#ifndef QCBOR_DISABLE_EXP_AND_MANTISSA
/**
- @brief Decode the next item as a decimal fraction.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pnMantissa The mantissa.
- @param[out] pnExponent The base 10 exponent.
-
- This decodes a standard CBOR decimal fraction, integer tag number of
- 4, or encoded CBOR that is not a tag, but borrows the content format.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- The value of this is computed by:
-
- mantissa * ( 10 ** exponent )
-
- In the encoded CBOR, the mantissa and exponent may be of CBOR type 0
- (positive integer), type 1 (negative integer), type 2 tag 2 (positive
- big number) or type 2 tag 3 (negative big number). This
- implementation will attempt to convert all of these to an @c
- int64_t. If the value won't fit, @ref
- QCBOR_ERR_CONVERSION_UNDER_OVER_FLOW or
- QCBOR_ERR_BAD_EXP_AND_MANTISSA will be set.
-
- This implementation limits the exponent to between @c INT64_MIN and
- @c INT64_MAX while CBOR allows the range of @c -UINT64_MAX to
- @c UINT64_MAX.
-
- Various format and type issues will result in @ref
- QCBOR_ERR_BAD_EXP_AND_MANTISSA being set.
-
- See @ref Tag-Usage for discussion on tag requirements.
-
- See also QCBORDecode_GetInt64ConvertAll(),
- QCBORDecode_GetUInt64ConvertAll() and
- QCBORDecode_GetDoubleConvertAll() which can convert big numbers.
-
- See also @ref CBOR_TAG_DECIMAL_FRACTION,
- QCBOREncode_AddDecimalFraction(), @ref QCBOR_TYPE_DECIMAL_FRACTION
- and QCBORDecode_GetDecimalFractionBig().
-
- If QCBOR_DISABLE_TAGS is set, the only input this will decode is
- an array of two integers. It will set an error if the the array is preceded
- by by a tag number or if the mantissa is a big number.
-*/
-void QCBORDecode_GetDecimalFraction(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- int64_t *pnMantissa,
- int64_t *pnExponent);
-
-void QCBORDecode_GetDecimalFractionInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- int64_t *pnMantissa,
- int64_t *pnExponent);
-
-void QCBORDecode_GetDecimalFractionInMapSZ(QCBORDecodeContext *pMe,
- const char *szLabel,
- uint8_t uTagRequirement,
- int64_t *pnMantissa,
- int64_t *pnExponent);
-
-
-/**
- @brief Decode the next item as a decimal fraction with a big number mantissa.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[in] MantissaBuffer The buffer in which to put the mantissa.
- @param[out] pMantissa The big num mantissa.
- @param[out] pbMantissaIsNegative Is @c true if @c pMantissa is negative.
- @param[out] pnExponent The base 10 exponent.
-
- This is the same as QCBORDecode_GetDecimalFraction() except the
- mantissa is returned as a big number.
-
- In the encoded CBOR, the mantissa may be a type 0 (positive integer),
- type 1 (negative integer), type 2 tag 2 (positive big number) or type
- 2 tag 3 (negative big number). This implementation will convert all
- these to a big number. The limit to this conversion is the size of @c
- MantissaBuffer.
-
- See also QCBORDecode_GetInt64ConvertAll(),
- QCBORDecode_GetUInt64ConvertAll() and
- QCBORDecode_GetDoubleConvertAll() which can convert decimal
- fractions.
-
- See also @ref CBOR_TAG_DECIMAL_FRACTION,
- QCBOREncode_AddDecimalFraction(), @ref QCBOR_TYPE_DECIMAL_FRACTION
- and QCBORDecode_GetDecimalFraction().
-*/
-void QCBORDecode_GetDecimalFractionBig(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBuf MantissaBuffer,
- UsefulBufC *pMantissa,
- bool *pbMantissaIsNegative,
- int64_t *pnExponent);
-
-void QCBORDecode_GetDecimalFractionBigInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBuf MantissaBuffer,
- UsefulBufC *pbMantissaIsNegative,
- bool *pbIsNegative,
- int64_t *pnExponent);
-
-void QCBORDecode_GetDecimalFractionBigInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBuf MantissaBuffer,
- UsefulBufC *pMantissa,
- bool *pbMantissaIsNegative,
- int64_t *pnExponent);
-
-
-/**
- @brief Decode the next item as a big float.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pnMantissa The mantissa.
- @param[out] pnExponent The base 2 exponent.
-
- This decodes a standard CBOR big float, integer tag number of 5, or
- encoded CBOR that is not a tag, but borrows the content format.
-
- This is the same as QCBORDecode_GetDecimalFraction() with the
- important distinction that the value is computed by:
-
- mantissa * ( 2 ** exponent )
-
- If the mantissa is a tag that is a positive or negative big number,
- this will attempt to fit it into the int64_t that @c pnMantissa is
- and set an overflow error if it doesn't fit.
-
- See also QCBORDecode_GetInt64ConvertAll(),
- QCBORDecode_GetUInt64ConvertAll() and
- QCBORDecode_GetDoubleConvertAll() which can convert big floats.
-
- See also @ref CBOR_TAG_BIGFLOAT, QCBOREncode_AddBigFloat(), @ref
- QCBOR_TYPE_BIGFLOAT and QCBORDecode_GetBigFloatBig().
+ * @brief Decode the next item as a decimal fraction.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pnMantissa The mantissa.
+ * @param[out] pnExponent The base 10 exponent.
+ *
+ * This decodes a standard CBOR decimal fraction, integer tag number
+ * of 4, or encoded CBOR that is not a tag, but borrows the content
+ * format.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * The value of this is computed by:
+ *
+ * mantissa * ( 10 ** exponent )
+ *
+ * In the encoded CBOR, the mantissa and exponent may be of CBOR type
+ * 0 (positive integer), type 1 (negative integer), type 2 tag 2
+ * (positive big number) or type 2 tag 3 (negative big number). This
+ * implementation will attempt to convert all of these to an @c
+ * int64_t. If the value won't fit, @ref QCBOR_ERR_CONVERSION_UNDER_OVER_FLOW
+ * or @ref QCBOR_ERR_BAD_EXP_AND_MANTISSA will be set.
+ *
+ * This implementation limits the exponent to between @c INT64_MIN and
+ * @c INT64_MAX while CBOR allows the range of @c -UINT64_MAX to
+ * @c UINT64_MAX.
+ *
+ * Various format and type issues will result in
+ * @ref QCBOR_ERR_BAD_EXP_AND_MANTISSA being set.
+ *
+ * See @ref Tag-Usage for discussion on tag requirements.
+ *
+ * See also QCBORDecode_GetInt64ConvertAll(),
+ * QCBORDecode_GetUInt64ConvertAll() and
+ * QCBORDecode_GetDoubleConvertAll() which can convert big numbers.
+ *
+ * See also @ref CBOR_TAG_DECIMAL_FRACTION,
+ * QCBOREncode_AddDecimalFraction(), @ref QCBOR_TYPE_DECIMAL_FRACTION
+ * and QCBORDecode_GetDecimalFractionBig().
+ *
+ * If QCBOR_DISABLE_TAGS is set, the only input this will decode is an
+ * array of two integers. It will set an error if the the array is
+ * preceded by by a tag number or if the mantissa is a big number.
*/
-void QCBORDecode_GetBigFloat(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- int64_t *pnMantissa,
- int64_t *pnExponent);
+void
+QCBORDecode_GetDecimalFraction(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ int64_t *pnMantissa,
+ int64_t *pnExponent);
-void QCBORDecode_GetBigFloatInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- int64_t *pnMantissa,
- int64_t *pnExponent);
+void
+QCBORDecode_GetDecimalFractionInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ int64_t *pnMantissa,
+ int64_t *pnExponent);
-void QCBORDecode_GetBigFloatInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- int64_t *pnMantissa,
- int64_t *pnExponent);
-
-
-/**
- @brief Decode the next item as a big float with a big number mantissa.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[in] MantissaBuffer The buffer in which to put the mantissa.
- @param[out] pMantissa The big num mantissa.
- @param[out] pbMantissaIsNegative Is @c true if @c pMantissa is negative.
- @param[out] pnExponent The base 2 exponent.
-
- This is the same as QCBORDecode_GetDecimalFractionBig() with the
- important distinction that the value is computed by:
-
- mantissa * ( 2 ** exponent )
-
- See also QCBORDecode_GetInt64ConvertAll(),
- QCBORDecode_GetUInt64ConvertAll() and
- QCBORDecode_GetDoubleConvertAll() which can convert big floats.
-
- See also @ref CBOR_TAG_BIGFLOAT, QCBOREncode_AddBigFloat(),
- @ref QCBOR_TYPE_BIGFLOAT and QCBORDecode_GetBigFloat().
- */
-void QCBORDecode_GetBigFloatBig(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBuf MantissaBuffer,
- UsefulBufC *pMantissa,
- bool *pbMantissaIsNegative,
- int64_t *pnExponent);
-
-void QCBORDecode_GetBigFloatBigInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
+void
+QCBORDecode_GetDecimalFractionInMapSZ(QCBORDecodeContext *pMe,
+ const char *szLabel,
uint8_t uTagRequirement,
- UsefulBuf MantissaBuffer,
- UsefulBufC *pMantissa,
- bool *pbMantissaIsNegative,
+ int64_t *pnMantissa,
int64_t *pnExponent);
-void QCBORDecode_GetBigFloatBigInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBuf MantissaBuffer,
- UsefulBufC *pMantissa,
- bool *pbMantissaIsNegative,
- int64_t *pnExponent);
+
+/**
+ * @brief Decode the next item as a decimal fraction with a big number mantissa.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[in] MantissaBuffer The buffer in which to put the mantissa.
+ * @param[out] pMantissa The big num mantissa.
+ * @param[out] pbMantissaIsNegative Is @c true if @c pMantissa is negative.
+ * @param[out] pnExponent The base 10 exponent.
+ *
+ * This is the same as QCBORDecode_GetDecimalFraction() except the
+ * mantissa is returned as a big number.
+ *
+ * In the encoded CBOR, the mantissa may be a type 0 (positive
+ * integer), type 1 (negative integer), type 2 tag 2 (positive big
+ * number) or type 2 tag 3 (negative big number). This implementation
+ * will convert all these to a big number. The limit to this
+ * conversion is the size of @c MantissaBuffer.
+ *
+ * See also QCBORDecode_GetInt64ConvertAll(),
+ * QCBORDecode_GetUInt64ConvertAll() and
+ * QCBORDecode_GetDoubleConvertAll() which can convert decimal
+ * fractions.
+ *
+ * See also @ref CBOR_TAG_DECIMAL_FRACTION,
+ * QCBOREncode_AddDecimalFraction(), @ref QCBOR_TYPE_DECIMAL_FRACTION
+ * and QCBORDecode_GetDecimalFraction().
+ */
+void
+QCBORDecode_GetDecimalFractionBig(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBuf MantissaBuffer,
+ UsefulBufC *pMantissa,
+ bool *pbMantissaIsNegative,
+ int64_t *pnExponent);
+
+void
+QCBORDecode_GetDecimalFractionBigInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBuf MantissaBuffer,
+ UsefulBufC *pbMantissaIsNegative,
+ bool *pbIsNegative,
+ int64_t *pnExponent);
+
+void
+QCBORDecode_GetDecimalFractionBigInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBuf MantissaBuffer,
+ UsefulBufC *pMantissa,
+ bool *pbMantissaIsNegative,
+ int64_t *pnExponent);
+
+
+/**
+ * @brief Decode the next item as a big float.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pnMantissa The mantissa.
+ * @param[out] pnExponent The base 2 exponent.
+ *
+ * This decodes a standard CBOR big float, integer tag number of 5, or
+ * encoded CBOR that is not a tag, but borrows the content format.
+ *
+ * This is the same as QCBORDecode_GetDecimalFraction() with the
+ * important distinction that the value is computed by:
+ *
+ * mantissa * ( 2 ** exponent )
+ *
+ * If the mantissa is a tag that is a positive or negative big number,
+ * this will attempt to fit it into the int64_t that @c pnMantissa is
+ * and set an overflow error if it doesn't fit.
+ *
+ * See also QCBORDecode_GetInt64ConvertAll(),
+ * QCBORDecode_GetUInt64ConvertAll() and
+ * QCBORDecode_GetDoubleConvertAll() which can convert big floats.
+ *
+ * See also @ref CBOR_TAG_BIGFLOAT, QCBOREncode_AddBigFloat(), @ref
+ * QCBOR_TYPE_BIGFLOAT and QCBORDecode_GetBigFloatBig().
+ */
+void
+QCBORDecode_GetBigFloat(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ int64_t *pnMantissa,
+ int64_t *pnExponent);
+
+void
+QCBORDecode_GetBigFloatInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ int64_t *pnMantissa,
+ int64_t *pnExponent);
+
+void
+QCBORDecode_GetBigFloatInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ int64_t *pnMantissa,
+ int64_t *pnExponent);
+
+
+/**
+ * @brief Decode the next item as a big float with a big number mantissa.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[in] MantissaBuffer The buffer in which to put the mantissa.
+ * @param[out] pMantissa The big num mantissa.
+ * @param[out] pbMantissaIsNegative Is @c true if @c pMantissa is negative.
+ * @param[out] pnExponent The base 2 exponent.
+ *
+ * This is the same as QCBORDecode_GetDecimalFractionBig() with the
+ * important distinction that the value is computed by:
+ *
+ * mantissa * ( 2 ** exponent )
+ *
+ * See also QCBORDecode_GetInt64ConvertAll(),
+ * QCBORDecode_GetUInt64ConvertAll() and
+ * QCBORDecode_GetDoubleConvertAll() which can convert big floats.
+ *
+ * See also @ref CBOR_TAG_BIGFLOAT, QCBOREncode_AddBigFloat(),
+ * @ref QCBOR_TYPE_BIGFLOAT and QCBORDecode_GetBigFloat().
+ */
+void
+QCBORDecode_GetBigFloatBig(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBuf MantissaBuffer,
+ UsefulBufC *pMantissa,
+ bool *pbMantissaIsNegative,
+ int64_t *pnExponent);
+
+void
+QCBORDecode_GetBigFloatBigInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBuf MantissaBuffer,
+ UsefulBufC *pMantissa,
+ bool *pbMantissaIsNegative,
+ int64_t *pnExponent);
+
+void
+QCBORDecode_GetBigFloatBigInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBuf MantissaBuffer,
+ UsefulBufC *pMantissa,
+ bool *pbMantissaIsNegative,
+ int64_t *pnExponent);
#endif /* #ifndef QCBOR_DISABLE_EXP_AND_MANTISSA */
/**
- @brief Decode the next item as a URI.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pURI The decoded URI.
-
- This decodes a standard CBOR URI tag, integer tag number of 32,
- or encoded CBOR that is not a tag, that is a URI encoded in a text string.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See @ref Tag-Usage for discussion on tag requirements.
-
- See also @ref CBOR_TAG_URI, QCBOREncode_AddURI() and
- @ref QCBOR_TYPE_URI.
+ * @brief Decode the next item as a URI.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pURI The decoded URI.
+ *
+ * This decodes a standard CBOR URI tag, integer tag number of 32, or
+ * encoded CBOR that is not a tag, that is a URI encoded in a text
+ * string.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See @ref Tag-Usage for discussion on tag requirements.
+ *
+ * See also @ref CBOR_TAG_URI, QCBOREncode_AddURI() and
+ * @ref QCBOR_TYPE_URI.
*/
-static void QCBORDecode_GetURI(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC *pURI);
+static void
+QCBORDecode_GetURI(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC *pURI);
-static void QCBORDecode_GetURIInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pURI);
+static void
+QCBORDecode_GetURIInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pURI);
-static void QCBORDecode_GetURIInMapSZ(QCBORDecodeContext *pCtx,
- const char * szLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pURI);
+static void
+QCBORDecode_GetURIInMapSZ(QCBORDecodeContext *pCtx,
+ const char * szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pURI);
/**
- @brief Decode the next item as base64 encoded text.
+ * @brief Decode the next item as base64 encoded text.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pB64Text The decoded base64 text.
+ *
+ * This decodes a standard CBOR base64 tag, integer tag number of 34,
+ * or encoded CBOR that is not a tag, that is base64 encoded bytes
+ * encoded in a text string.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See @ref Tag-Usage for discussion on tag requirements.
+ *
+ * Note that this does not actually remove the base64 encoding.
+ *
+ * See also @ref CBOR_TAG_B64, QCBOREncode_AddB64Text() and
+ * @ref QCBOR_TYPE_BASE64.
+ */
+static void
+QCBORDecode_GetB64(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC *pB64Text);
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pB64Text The decoded base64 text.
+static void
+QCBORDecode_GetB64InMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pB64Text);
- This decodes a standard CBOR base64 tag, integer tag number of 34, or
- encoded CBOR that is not a tag, that is base64 encoded bytes encoded
- in a text string.
+static void
+QCBORDecode_GetB64InMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pB64Text);
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+/**
+ * @brief Decode the next item as base64URL encoded text.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pB64Text The decoded base64 text.
+ *
+ * This decodes a standard CBOR base64url tag, integer tag number of
+ * 33, or encoded CBOR that is not a tag, that is base64url encoded
+ * bytes encoded in a text string.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See @ref Tag-Usage for discussion on tag requirements.
+ *
+ * Note that this does not actually remove the base64url encoding.
+ *
+ * See also @ref CBOR_TAG_B64URL, QCBOREncode_AddB64URLText() and
+ * @ref QCBOR_TYPE_BASE64URL.
+ */
+static void
+QCBORDecode_GetB64URL(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC *pB64Text);
- See @ref Tag-Usage for discussion on tag requirements.
+static void
+QCBORDecode_GetB64URLInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pB64Text);
- Note that this does not actually remove the base64 encoding.
+static void
+QCBORDecode_GetB64URLInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pB64Text);
- See also @ref CBOR_TAG_B64, QCBOREncode_AddB64Text() and
- @ref QCBOR_TYPE_BASE64.
-*/
-static void QCBORDecode_GetB64(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC *pB64Text);
+/**
+ * @brief Decode the next item as a regular expression.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pRegex The decoded regular expression.
+ *
+ * This decodes a standard CBOR regex tag, integer tag number of 35,
+ * or encoded CBOR that is not a tag, that is a PERL-compatible
+ * regular expression encoded in a text string.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See @ref Tag-Usage for discussion on tag requirements.
+ *
+ * See also @ref CBOR_TAG_REGEX, QCBOREncode_AddRegex() and
+ * @ref QCBOR_TYPE_REGEX.
+ */
+static void
+QCBORDecode_GetRegex(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC *pRegex);
-static void QCBORDecode_GetB64InMapN(QCBORDecodeContext *pCtx,
+static void
+QCBORDecode_GetRegexInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pRegex);
+
+static void
+QCBORDecode_GetRegexInMapSZ(QCBORDecodeContext *pCtx,
+ const char * szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pRegex);
+
+
+/**
+ * @brief Decode the next item as a MIME message.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pMessage The decoded regular expression.
+ * @param[out] pbIsTag257 @c true if tag was 257. May be @c NULL.
+ *
+ * This decodes the standard CBOR MIME and binary MIME tags, integer
+ * tag numbers of 36 or 257, or encoded CBOR that is not a tag, that
+ * is a MIME message encoded in a text or binary string.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See @ref Tag-Usage for discussion on tag requirements.
+ *
+ * The MIME message itself is not parsed.
+ *
+ * This decodes both tag 36 and 257. If it is tag 257, pbIsTag257 is
+ * @c true. The difference between the two is that tag 36 is utf8 and
+ * tag 257 is a byte string that can carry binary MIME. QCBOR
+ * processes them exactly the same. Possibly the difference can be
+ * ignored. NULL can be passed to have no value returned.
+ *
+ * See also @ref CBOR_TAG_MIME, @ref CBOR_TAG_BINARY_MIME,
+ * QCBOREncode_AddTMIMEData(), @ref QCBOR_TYPE_MIME and
+ * @ref QCBOR_TYPE_BINARY_MIME.
+ *
+ * This does no translation of line endings. See QCBOREncode_AddText()
+ * for a discussion of line endings in CBOR.
+ */
+static void
+QCBORDecode_GetMIMEMessage(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC *pMessage,
+ bool *pbIsTag257);
+
+static void
+QCBORDecode_GetMIMEMessageInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pMessage,
+ bool *pbIsTag257);
+
+
+static void
+QCBORDecode_GetMIMEMessageInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pMessage,
+ bool *pbIsTag257);
+
+/**
+ * @brief Decode the next item as a UUID.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pUUID The decoded UUID
+ *
+ * This decodes a standard CBOR UUID tag, integer tag number of 37, or
+ * encoded CBOR that is not a tag, that is a UUID encoded in a byte
+ * string.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See @ref Tag-Usage for discussion on tag requirements.
+ *
+ * See also @ref CBOR_TAG_BIN_UUID, QCBOREncode_AddBinaryUUID() and
+ * @ref QCBOR_TYPE_UUID.
+ */
+static void
+QCBORDecode_GetBinaryUUID(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC *pUUID);
+
+static void
+QCBORDecode_GetBinaryUUIDInMapN(QCBORDecodeContext *pCtx,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pUUID);
+
+static void
+QCBORDecode_GetBinaryUUIDInMapSZ(QCBORDecodeContext *pCtx,
+ const char *szLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pUUID);
+
+
+
+/**
+ * @brief Decode some byte-string wrapped CBOR.
+ *
+ * @param[in] pCtx The decode context.
+ * @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
+ * @param[out] pBstr Pointer and length of byte-string wrapped CBOR (optional).
+ *
+ * This is for use on some CBOR that has been wrapped in a byte
+ * string. There are several ways that this can occur.
+ *
+ * First is tag 24 and tag 63. Tag 24 wraps a single CBOR data item
+ * and 63 a CBOR sequence. This implementation doesn't distinguish
+ * between the two (it would be more code and doesn't seem important).
+ *
+ * The @ref Tag-Usage discussion on the tag requirement applies here
+ * just the same as any other tag.
+ *
+ * In other cases, CBOR is wrapped in a byte string, but it is
+ * identified as CBOR by other means. The contents of a COSE payload
+ * are one example of that. They can be identified by the COSE content
+ * type, or they can be identified as CBOR indirectly by the protocol
+ * that uses COSE. for example, if a blob of CBOR is identified as a
+ * CWT, then the COSE payload is CBOR. To enter into CBOR of this
+ * type use the @ref QCBOR_TAG_REQUIREMENT_NOT_A_TAG as the \c
+ * uTagRequirement argument.
+ *
+ * Note that byte string wrapped CBOR can also be decoded by getting
+ * the byte string with QCBORDecode_GetItem() or
+ * QCBORDecode_GetByteString() and feeding it into another instance of
+ * QCBORDecode. Doing it with this function has the advantage of using
+ * less memory as another instance of QCBORDecode is not necessary.
+ *
+ * When the wrapped CBOR is entered with this function, the pre-order
+ * traversal and such are bounded to the wrapped
+ * CBOR. QCBORDecode_ExitBstrWrapped() must be called to resume
+ * processing CBOR outside the wrapped CBOR.
+ *
+ * This does not (currently) work on indefinite-length strings. The
+ * (confusing) error @ref QCBOR_ERR_INPUT_TOO_LARGE will be set.
+ *
+ * If @c pBstr is not @c NULL the pointer and length of the wrapped
+ * CBOR will be returned. This is usually not needed, but sometimes
+ * useful, particularly in the case of verifying signed data like the
+ * COSE payload. This is usually the pointer and length of the data is
+ * that is hashed or MACed.
+ *
+ * Please see @ref Decode-Errors-Overview "Decode Errors Overview".
+ *
+ * See also QCBORDecode_ExitBstrWrapped(), QCBORDecode_EnterMap() and
+ * QCBORDecode_EnterArray().
+ */
+void
+QCBORDecode_EnterBstrWrapped(QCBORDecodeContext *pCtx,
+ uint8_t uTagRequirement,
+ UsefulBufC *pBstr);
+
+void
+QCBORDecode_EnterBstrWrappedFromMapN(QCBORDecodeContext *pCtx,
int64_t nLabel,
uint8_t uTagRequirement,
- UsefulBufC *pB64Text);
+ UsefulBufC *pBstr);
-static void QCBORDecode_GetB64InMapSZ(QCBORDecodeContext *pCtx,
+void
+QCBORDecode_EnterBstrWrappedFromMapSZ(QCBORDecodeContext *pCtx,
const char *szLabel,
uint8_t uTagRequirement,
- UsefulBufC *pB64Text);
+ UsefulBufC *pBstr);
+
/**
- @brief Decode the next item as base64URL encoded text.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pB64Text The decoded base64 text.
-
- This decodes a standard CBOR base64url tag, integer tag number of 33,
- or encoded CBOR that is not a tag, that is base64url encoded bytes
- encoded in a text string.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See @ref Tag-Usage for discussion on tag requirements.
-
- Note that this does not actually remove the base64url encoding.
-
- See also @ref CBOR_TAG_B64URL, QCBOREncode_AddB64URLText() and
- @ref QCBOR_TYPE_BASE64URL.
-*/
-static void QCBORDecode_GetB64URL(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC *pB64Text);
-
-static void QCBORDecode_GetB64URLInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pB64Text);
-
-static void QCBORDecode_GetB64URLInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pB64Text);
-
-/**
- @brief Decode the next item as a regular expression.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pRegex The decoded regular expression.
-
- This decodes a standard CBOR regex tag, integer tag number of 35, or
- encoded CBOR that is not a tag, that is a PERL-compatible regular
- expression encoded in a text string.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See @ref Tag-Usage for discussion on tag requirements.
-
- See also @ref CBOR_TAG_REGEX, QCBOREncode_AddRegex() and
- @ref QCBOR_TYPE_REGEX.
+ * @brief Exit some bstr-wrapped CBOR has been enetered.
+ *
+ * @param[in] pCtx The decode context.
+ *
+ * Bstr-wrapped CBOR must have been entered for this to succeed.
+ *
+ * The items in the wrapped CBOR that was entered do not have to have
+ * been consumed for this to succeed.
+ *
+ * The this sets the pre-order traversal cursor to the item after the
+ * byte string that was exited.
*/
-static void QCBORDecode_GetRegex(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC *pRegex);
-
-static void QCBORDecode_GetRegexInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pRegex);
-
-static void QCBORDecode_GetRegexInMapSZ(QCBORDecodeContext *pCtx,
- const char * szLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pRegex);
-
-
-/**
- @brief Decode the next item as a MIME message.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pMessage The decoded regular expression.
- @param[out] pbIsTag257 @c true if tag was 257. May be @c NULL.
-
- This decodes the standard CBOR MIME and binary MIME tags, integer tag
- numbers of 36 or 257, or encoded CBOR that is not a tag, that is a
- MIME message encoded in a text or binary string.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See @ref Tag-Usage for discussion on tag requirements.
-
- The MIME message itself is not parsed.
-
- This decodes both tag 36 and 257. If it is tag 257, pbIsTag257
- is @c true. The difference between the two is that
- tag 36 is utf8 and tag 257 is a byte string that can
- carry binary MIME. QCBOR processes them exactly
- the same. Possibly the difference can be ignored.
- NULL can be passed to have no value returned.
-
- See also @ref CBOR_TAG_MIME, @ref CBOR_TAG_BINARY_MIME,
- QCBOREncode_AddTMIMEData(), @ref QCBOR_TYPE_MIME and
- @ref QCBOR_TYPE_BINARY_MIME.
-
- This does no translation of line endings. See QCBOREncode_AddText()
- for a discussion of line endings in CBOR.
-*/
-static void QCBORDecode_GetMIMEMessage(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC *pMessage,
- bool *pbIsTag257);
-
-static void QCBORDecode_GetMIMEMessageInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pMessage,
- bool *pbIsTag257);
-
-
-static void QCBORDecode_GetMIMEMessageInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pMessage,
- bool *pbIsTag257);
-
-/**
- @brief Decode the next item as a UUID
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pUUID The decoded UUID
-
- This decodes a standard CBOR UUID tag, integer tag number of 37, or
- encoded CBOR that is not a tag, that is a UUID encoded in a byte
- string.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See @ref Tag-Usage for discussion on tag requirements.
-
- See also @ref CBOR_TAG_BIN_UUID, QCBOREncode_AddBinaryUUID() and
- @ref QCBOR_TYPE_UUID.
- */
-static inline void QCBORDecode_GetBinaryUUID(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC *pUUID);
-
-inline static void QCBORDecode_GetBinaryUUIDInMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pUUID);
-
-inline static void QCBORDecode_GetBinaryUUIDInMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pUUID);
-
-
-
-/**
- @brief Decode some byte-string wrapped CBOR.
-
- @param[in] pCtx The decode context.
- @param[in] uTagRequirement One of @c QCBOR_TAG_REQUIREMENT_XXX.
- @param[out] pBstr Pointer and length of byte-string wrapped CBOR (optional).
-
- This is for use on some CBOR that has been wrapped in a byte
- string. There are several ways that this can occur.
-
- First is tag 24 and tag 63. Tag 24 wraps a single CBOR data item and
- 63 a CBOR sequence. This implementation doesn't distinguish between
- the two (it would be more code and doesn't seem important).
-
- The @ref Tag-Usage discussion on the tag requirement applies here
- just the same as any other tag.
-
- In other cases, CBOR is wrapped in a byte string, but it is
- identified as CBOR by other means. The contents of a COSE payload are
- one example of that. They can be identified by the COSE content type,
- or they can be identified as CBOR indirectly by the protocol that
- uses COSE. for example, if a blob of CBOR is identified as a CWT,
- then the COSE payload is CBOR. To enter into CBOR of this type use
- the @ref QCBOR_TAG_REQUIREMENT_NOT_A_TAG as the \c uTagRequirement
- argument.
-
- Note that byte string wrapped CBOR can also be decoded by getting the
- byte string with QCBORDecode_GetItem() or QCBORDecode_GetByteString()
- and feeding it into another instance of QCBORDecode. Doing it with
- this function has the advantage of using less memory as another
- instance of QCBORDecode is not necessary.
-
- When the wrapped CBOR is entered with this function, the pre-order
- traversal and such are bounded to the wrapped
- CBOR. QCBORDecode_ExitBstrWrapped() must be called to resume processing
- CBOR outside the wrapped CBOR.
-
- This does not (currently) work on indefinite-length strings. The
- (confusing) error @ref QCBOR_ERR_INPUT_TOO_LARGE will be set.
-
- If @c pBstr is not @c NULL the pointer and length of the wrapped
- CBOR will be returned. This is usually not needed, but sometimes
- useful, particularly in the case of verifying signed data like the
- COSE payload. This is usually the pointer and length of the
- data is that is hashed or MACed.
-
- Please see @ref Decode-Errors-Overview "Decode Errors Overview".
-
- See also QCBORDecode_ExitBstrWrapped(), QCBORDecode_EnterMap() and
- QCBORDecode_EnterArray().
- */
-void QCBORDecode_EnterBstrWrapped(QCBORDecodeContext *pCtx,
- uint8_t uTagRequirement,
- UsefulBufC *pBstr);
-
-void QCBORDecode_EnterBstrWrappedFromMapN(QCBORDecodeContext *pCtx,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pBstr);
-
-void QCBORDecode_EnterBstrWrappedFromMapSZ(QCBORDecodeContext *pCtx,
- const char *szLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pBstr);
-
-
-/**
- @brief Exit some bstr-wrapped CBOR has been enetered.
-
- @param[in] pCtx The decode context.
-
- Bstr-wrapped CBOR must have been entered for this to succeed.
-
- The items in the wrapped CBOR that was entered do not have to have been
- consumed for this to succeed.
-
- The this sets the pre-order traversal cursor to the item after
- the byte string that was exited.
-*/
-void QCBORDecode_ExitBstrWrapped(QCBORDecodeContext *pCtx);
+void
+QCBORDecode_ExitBstrWrapped(QCBORDecodeContext *pCtx);
@@ -1715,15 +1836,16 @@
QCBORItem *pItem);
-void QCBORDecode_GetUInt64Convert(QCBORDecodeContext *pMe,
- uint32_t uConvertTypes,
- uint64_t *puValue)
+static inline void
+QCBORDecode_GetUInt64Convert(QCBORDecodeContext *pMe,
+ uint32_t uConvertTypes,
+ uint64_t *puValue)
{
QCBORItem Item;
QCBORDecode_GetUInt64ConvertInternal(pMe, uConvertTypes, puValue, &Item);
}
-inline static void
+static inline void
QCBORDecode_GetUInt64ConvertInMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
uint32_t uConvertTypes,
@@ -1737,7 +1859,7 @@
&Item);
}
-inline static void
+static inline void
QCBORDecode_GetUInt64ConvertInMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
uint32_t uConvertTypes,
@@ -1757,7 +1879,7 @@
QCBORDecode_GetUInt64Convert(pMe, QCBOR_CONVERT_TYPE_XINT64, puValue);
}
-inline static void
+static inline void
QCBORDecode_GetUInt64InMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
uint64_t *puValue)
@@ -1768,7 +1890,7 @@
puValue);
}
-inline static void
+static inline void
QCBORDecode_GetUInt64InMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
uint64_t *puValue)
@@ -1781,28 +1903,35 @@
// Semi-private
-void QCBORDecode_EnterBoundedMapOrArray(QCBORDecodeContext *pMe, uint8_t uType, QCBORItem *pItem);
+void QCBORDecode_EnterBoundedMapOrArray(QCBORDecodeContext *pMe,
+ uint8_t uType,
+ QCBORItem *pItem);
// Semi-private
-inline static void QCBORDecode_EnterMap(QCBORDecodeContext *pMe, QCBORItem *pItem) {
+static inline void
+QCBORDecode_EnterMap(QCBORDecodeContext *pMe, QCBORItem *pItem) {
QCBORDecode_EnterBoundedMapOrArray(pMe, QCBOR_TYPE_MAP, pItem);
}
// Semi-private
-inline static void QCBORDecode_EnterArray(QCBORDecodeContext *pMe, QCBORItem *pItem) {
+static inline void
+QCBORDecode_EnterArray(QCBORDecodeContext *pMe, QCBORItem *pItem) {
QCBORDecode_EnterBoundedMapOrArray(pMe, QCBOR_TYPE_ARRAY, pItem);
}
// Semi-private
-void QCBORDecode_ExitBoundedMapOrArray(QCBORDecodeContext *pMe, uint8_t uType);
+void
+QCBORDecode_ExitBoundedMapOrArray(QCBORDecodeContext *pMe, uint8_t uType);
-static inline void QCBORDecode_ExitArray(QCBORDecodeContext *pMe)
+static inline void
+QCBORDecode_ExitArray(QCBORDecodeContext *pMe)
{
QCBORDecode_ExitBoundedMapOrArray(pMe, QCBOR_TYPE_ARRAY);
}
-static inline void QCBORDecode_ExitMap(QCBORDecodeContext *pMe)
+static inline void
+QCBORDecode_ExitMap(QCBORDecodeContext *pMe)
{
QCBORDecode_ExitBoundedMapOrArray(pMe, QCBOR_TYPE_MAP);
}
@@ -1831,7 +1960,7 @@
int64_t *pnValue,
QCBORItem *pItem);
-inline static void
+static inline void
QCBORDecode_GetInt64Convert(QCBORDecodeContext *pMe,
uint32_t uConvertTypes,
int64_t *pnValue)
@@ -1840,7 +1969,7 @@
QCBORDecode_GetInt64ConvertInternal(pMe, uConvertTypes, pnValue, &Item);
}
-inline static void
+static inline void
QCBORDecode_GetInt64ConvertInMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
uint32_t uConvertTypes,
@@ -1854,7 +1983,7 @@
&Item);
}
-inline static void
+static inline void
QCBORDecode_GetInt64ConvertInMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
uint32_t uConvertTypes,
@@ -1868,13 +1997,13 @@
&Item);
}
-inline static void
+static inline void
QCBORDecode_GetInt64(QCBORDecodeContext *pMe, int64_t *pnValue)
{
QCBORDecode_GetInt64Convert(pMe, QCBOR_CONVERT_TYPE_XINT64, pnValue);
}
-inline static void
+static inline void
QCBORDecode_GetInt64InMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
int64_t *pnValue)
@@ -1885,7 +2014,7 @@
pnValue);
}
-inline static void
+static inline void
QCBORDecode_GetInt64InMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
int64_t *pnValue)
@@ -1925,7 +2054,7 @@
QCBORItem *pItem);
-inline static void
+static inline void
QCBORDecode_GetDoubleConvert(QCBORDecodeContext *pMe,
uint32_t uConvertTypes,
double *pdValue)
@@ -1934,7 +2063,7 @@
QCBORDecode_GetDoubleConvertInternal(pMe, uConvertTypes, pdValue, &Item);
}
-inline static void
+static inline void
QCBORDecode_GetDoubleConvertInMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
uint32_t uConvertTypes,
@@ -1948,7 +2077,7 @@
&Item);
}
-inline static void
+static inline void
QCBORDecode_GetDoubleConvertInMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
uint32_t uConvertTypes,
@@ -1962,13 +2091,13 @@
&Item);
}
-inline static void
+static inline void
QCBORDecode_GetDouble(QCBORDecodeContext *pMe, double *pValue)
{
QCBORDecode_GetDoubleConvert(pMe, QCBOR_CONVERT_TYPE_FLOAT, pValue);
}
-inline static void
+static inline void
QCBORDecode_GetDoubleInMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
double *pdValue)
@@ -1979,7 +2108,7 @@
pdValue);
}
-inline static void
+static inline void
QCBORDecode_GetDoubleInMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
double *pdValue)
@@ -2016,29 +2145,33 @@
// Semi private
-void QCBORDecode_GetTaggedStringInternal(QCBORDecodeContext *pMe,
- TagSpecification TagSpec,
- UsefulBufC *pBstr);
+void
+QCBORDecode_GetTaggedStringInternal(QCBORDecodeContext *pMe,
+ TagSpecification TagSpec,
+ UsefulBufC *pBstr);
// Semi private
-void QCBORDecode_GetTaggedStringInMapN(QCBORDecodeContext *pMe,
- int64_t nLabel,
- TagSpecification TagSpec,
- UsefulBufC *pString);
+void
+QCBORDecode_GetTaggedStringInMapN(QCBORDecodeContext *pMe,
+ int64_t nLabel,
+ TagSpecification TagSpec,
+ UsefulBufC *pString);
// Semi private
-void QCBORDecode_GetTaggedStringInMapSZ(QCBORDecodeContext *pMe,
- const char * szLabel,
- TagSpecification TagSpec,
- UsefulBufC *pString);
+void
+QCBORDecode_GetTaggedStringInMapSZ(QCBORDecodeContext *pMe,
+ const char * szLabel,
+ TagSpecification TagSpec,
+ UsefulBufC *pString);
// Semi private
-QCBORError QCBORDecode_GetMIMEInternal(uint8_t uTagRequirement,
- const QCBORItem *pItem,
- UsefulBufC *pMessage,
- bool *pbIsTag257);
+QCBORError
+QCBORDecode_GetMIMEInternal(uint8_t uTagRequirement,
+ const QCBORItem *pItem,
+ UsefulBufC *pMessage,
+ bool *pbIsTag257);
@@ -2056,7 +2189,7 @@
QCBORDecode_GetTaggedStringInternal(pMe, TagSpec, pValue);
}
-inline static void
+static inline void
QCBORDecode_GetByteStringInMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
UsefulBufC *pBstr)
@@ -2070,7 +2203,7 @@
QCBORDecode_GetTaggedStringInMapN(pMe, nLabel, TagSpec, pBstr);
}
-inline static void
+static inline void
QCBORDecode_GetByteStringInMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
UsefulBufC *pBstr)
@@ -2100,7 +2233,7 @@
QCBORDecode_GetTaggedStringInternal(pMe, TagSpec, pValue);
}
-inline static void
+static inline void
QCBORDecode_GetTextStringInMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
UsefulBufC *pText)
@@ -2117,7 +2250,7 @@
QCBORDecode_GetTaggedStringInMapN(pMe, nLabel, TagSpec, pText);
}
-inline static void
+static inline void
QCBORDecode_GetTextStringInMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
UsefulBufC *pText)
@@ -2202,7 +2335,7 @@
QCBORDecode_GetTaggedStringInternal(pMe, TagSpec, pValue);
}
-inline static void
+static inline void
QCBORDecode_GetDateStringInMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
uint8_t uTagRequirement,
@@ -2218,7 +2351,7 @@
QCBORDecode_GetTaggedStringInMapN(pMe, nLabel, TagSpec, pText);
}
-inline static void
+static inline void
QCBORDecode_GetDateStringInMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
uint8_t uTagRequirement,
@@ -2249,7 +2382,7 @@
QCBORDecode_GetTaggedStringInternal(pMe, TagSpec, pValue);
}
-inline static void
+static inline void
QCBORDecode_GetDaysStringInMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
uint8_t uTagRequirement,
@@ -2265,7 +2398,7 @@
QCBORDecode_GetTaggedStringInMapN(pMe, nLabel, TagSpec, pText);
}
-inline static void
+static inline void
QCBORDecode_GetDaysStringInMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
uint8_t uTagRequirement,
@@ -2283,9 +2416,10 @@
-static inline void QCBORDecode_GetURI(QCBORDecodeContext *pMe,
- uint8_t uTagRequirement,
- UsefulBufC *pUUID)
+static inline void
+QCBORDecode_GetURI(QCBORDecodeContext *pMe,
+ uint8_t uTagRequirement,
+ UsefulBufC *pUUID)
{
const TagSpecification TagSpec =
{
@@ -2297,7 +2431,7 @@
QCBORDecode_GetTaggedStringInternal(pMe, TagSpec, pUUID);
}
-inline static void
+static inline void
QCBORDecode_GetURIInMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
uint8_t uTagRequirement,
@@ -2313,7 +2447,7 @@
QCBORDecode_GetTaggedStringInMapN(pMe, nLabel, TagSpec, pUUID);
}
-inline static void
+static inline void
QCBORDecode_GetURIInMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
uint8_t uTagRequirement,
@@ -2330,9 +2464,10 @@
}
-static inline void QCBORDecode_GetB64(QCBORDecodeContext *pMe,
- uint8_t uTagRequirement,
- UsefulBufC *pB64Text)
+static inline void
+QCBORDecode_GetB64(QCBORDecodeContext *pMe,
+ uint8_t uTagRequirement,
+ UsefulBufC *pB64Text)
{
const TagSpecification TagSpec =
{
@@ -2344,10 +2479,11 @@
QCBORDecode_GetTaggedStringInternal(pMe, TagSpec, pB64Text);
}
-inline static void QCBORDecode_GetB64InMapN(QCBORDecodeContext *pMe,
- int64_t nLabel,
- uint8_t uTagRequirement,
- UsefulBufC *pB64Text)
+static inline void
+QCBORDecode_GetB64InMapN(QCBORDecodeContext *pMe,
+ int64_t nLabel,
+ uint8_t uTagRequirement,
+ UsefulBufC *pB64Text)
{
const TagSpecification TagSpec =
{
@@ -2359,7 +2495,7 @@
QCBORDecode_GetTaggedStringInMapN(pMe, nLabel, TagSpec, pB64Text);
}
-inline static void
+static inline void
QCBORDecode_GetB64InMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
uint8_t uTagRequirement,
@@ -2390,7 +2526,7 @@
QCBORDecode_GetTaggedStringInternal(pMe, TagSpec, pB64Text);
}
-inline static void
+static inline void
QCBORDecode_GetB64URLInMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
uint8_t uTagRequirement,
@@ -2406,7 +2542,7 @@
QCBORDecode_GetTaggedStringInMapN(pMe, nLabel, TagSpec, pB64Text);
}
-inline static void
+static inline void
QCBORDecode_GetB64URLInMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
uint8_t uTagRequirement,
@@ -2423,9 +2559,10 @@
}
-static inline void QCBORDecode_GetRegex(QCBORDecodeContext *pMe,
- uint8_t uTagRequirement,
- UsefulBufC *pRegex)
+static inline void
+QCBORDecode_GetRegex(QCBORDecodeContext *pMe,
+ uint8_t uTagRequirement,
+ UsefulBufC *pRegex)
{
const TagSpecification TagSpec =
{
@@ -2477,7 +2614,7 @@
bool *pbIsTag257)
{
if(pMe->uLastError != QCBOR_SUCCESS) {
- // Already in error state, do nothing
+ /* Already in error state, do nothing */
return;
}
@@ -2546,7 +2683,7 @@
QCBORDecode_GetTaggedStringInternal(pMe, TagSpec, pUUID);
}
-inline static void
+static inline void
QCBORDecode_GetBinaryUUIDInMapN(QCBORDecodeContext *pMe,
int64_t nLabel,
uint8_t uTagRequirement,
@@ -2562,7 +2699,7 @@
QCBORDecode_GetTaggedStringInMapN(pMe, nLabel, TagSpec, pUUID);
}
-inline static void
+static inline void
QCBORDecode_GetBinaryUUIDInMapSZ(QCBORDecodeContext *pMe,
const char *szLabel,
uint8_t uTagRequirement,