Doc & comment fixes for encoder (#253)
Documentation and code comment fixes for the encoder. No semantic changes.
* Update version indicators to 1.4
* Documentation and comment fixes
* Update urls
* Fix references in qcbor_common.h
---------
Co-authored-by: Laurence Lundblade <lgl@securitytheory.com>
diff --git a/inc/qcbor/qcbor_common.h b/inc/qcbor/qcbor_common.h
index 2d630fe..43d3a3d 100644
--- a/inc/qcbor/qcbor_common.h
+++ b/inc/qcbor/qcbor_common.h
@@ -120,36 +120,36 @@
* are types defined in RFC 8949 and some additional ones
* in the IANA CBOR tags registry.
*/
-/** See QCBOREncode_AddDateString(). */
+/** See QCBOREncode_AddTDateString(). */
#define CBOR_TAG_DATE_STRING 0
-/** See QCBOREncode_AddDateEpoch(). */
+/** See QCBOREncode_AddTDateEpoch(). */
#define CBOR_TAG_DATE_EPOCH 1
-/** See QCBOREncode_AddPositiveBignum(). */
+/** See QCBOREncode_AddTPositiveBignum(). */
#define CBOR_TAG_POS_BIGNUM 2
-/** See QCBOREncode_AddNegativeBignum(). */
+/** See QCBOREncode_AddTNegativeBignum(). */
#define CBOR_TAG_NEG_BIGNUM 3
/** CBOR tag for a two-element array representing a fraction with a
* mantissa and base-10 scaling factor. See
- * QCBOREncode_AddDecimalFraction() and @ref expAndMantissa. */
+ * QCBOREncode_AddTDecimalFraction() and @ref expAndMantissa. */
#define CBOR_TAG_DECIMAL_FRACTION 4
/** CBOR tag for a two-element array representing a fraction with a
- * mantissa and base-2 scaling factor. See QCBOREncode_AddBigFloat()
+ * mantissa and base-2 scaling factor. See QCBOREncode_AddTBigFloat()
* and @ref expAndMantissa. */
#define CBOR_TAG_BIGFLOAT 5
/** Not Decoded by QCBOR. Tag for COSE format encryption with no
- * recipient identification. See [RFC 8152, COSE]
- * (https://tools.ietf.org/html/rfc8152). No API is provided for this
- * tag. */
+ * recipient identification. See [RFC 9052, COSE]
+ * (https://www.rfc-editor.org/rfc/rfc9052.html). No API is provided
+ * for this tag. */
#define CBOR_TAG_COSE_ENCRYPT0 16
#define CBOR_TAG_COSE_ENCRYPTO 16
/** Not Decoded by QCBOR. Tag for COSE format MAC'd data with no
- * recipient identification. See [RFC 8152, COSE]
- * (https://tools.ietf.org/html/rfc8152). No API is provided for this
+ * recipient identification. See [RFC 9052, COSE]
+ * (https://www.rfc-editor.org/rfc/rfc9052.html). No API is provided for this
* tag. */
#define CBOR_TAG_COSE_MAC0 17
/** Tag for COSE format single signature signing. No API is provided
- * for this tag. See [RFC 8152, COSE]
- * (https://tools.ietf.org/html/rfc8152). */
+ * for this tag. See [RFC 9052, COSE]
+ * (https://www.rfc-editor.org/rfc/rfc9052.html). */
#define CBOR_TAG_COSE_SIGN1 18
/** A hint that the following byte string should be encoded in
* Base64URL when converting to JSON or similar text-based
@@ -164,12 +164,12 @@
* QCBOREncode_AddBytes(). */
#define CBOR_TAG_ENC_AS_B64 22
/** A hint that the following byte string should be encoded in base-16
- * format per [RFC 4648] (https://tools.ietf.org/html/rfc4648) when
- * converting to JSON or similar text-based
- * representations. Essentially, Base-16 encoding is the standard
- * case- insensitive hex encoding and may be referred to as
- * "hex". Call @c QCBOREncode_AddTag(pCtx,CBOR_TAG_ENC_AS_B16) before
- * the call to QCBOREncode_AddBytes(). */
+ * format per [RFC 4648]
+ * (https://www.rfc-editor.org/rfc/rfc4648.html) when converting to
+ * JSON or similar text-based representations. Essentially, Base-16
+ * encoding is the standard case- insensitive hex encoding and may be
+ * referred to as "hex". Call @c QCBOREncode_AddTag(pCtx,CBOR_TAG_ENC_AS_B16)
+ * before the call to QCBOREncode_AddBytes(). */
#define CBOR_TAG_ENC_AS_B16 23
/** See QCBORDecode_EnterBstrWrapped()). */
#define CBOR_TAG_CBOR 24
@@ -186,40 +186,40 @@
/** See QCBOREncode_AddBinaryUUID(). */
#define CBOR_TAG_BIN_UUID 37
/** The data is a CBOR Web Token per [RFC 8392]
- * (https://tools.ietf.org/html/rfc8932). No API is provided for this
+ * (https://www.rfc-editor.org/rfc/rfc8392.html). No API is provided for this
* tag. */
#define CBOR_TAG_CWT 61
-/** Tag for COSE format encryption. See [RFC 8152, COSE]
- * (https://tools.ietf.org/html/rfc8152). No API is provided for this
+/** Tag for COSE format encryption. See [RFC 9052, COSE]
+ * (https://www.rfc-editor.org/rfc/rfc9052.html). No API is provided for this
* tag. */
#define CBOR_TAG_CBOR_SEQUENCE 63
-/** Not Decoded by QCBOR. Tag for COSE format encrypt. See [RFC 8152, COSE]
- * (https://tools.ietf.org/html/rfc8152). No API is provided for this
+/** Not Decoded by QCBOR. Tag for COSE format encrypt. See [RFC 9052, COSE]
+ * (https://www.rfc-editor.org/rfc/rfc9052.html). No API is provided for this
* tag. */
#define CBOR_TAG_COSE_ENCRYPT 96
#define CBOR_TAG_ENCRYPT 96
-/** Not Decoded by QCBOR. Tag for COSE format MAC. See [RFC 8152, COSE]
- (https://tools.ietf.org/html/rfc8152). No API is provided for this
+/** Not Decoded by QCBOR. Tag for COSE format MAC. See [RFC 9052, COSE]
+ * (https://www.rfc-editor.org/rfc/rfc9052.html). No API is provided for this
tag. */
#define CBOR_TAG_COSE_MAC 97
#define CBOR_TAG_MAC 97
-/** Not Decoded by QCBOR. Tag for COSE format signed data. See [RFC 8152, COSE]
- (https://tools.ietf.org/html/rfc8152). No API is provided for this
+/** Not Decoded by QCBOR. Tag for COSE format signed data. See [RFC 9052, COSE]
+ * (https://www.rfc-editor.org/rfc/rfc9052.html). No API is provided for this
tag. */
#define CBOR_TAG_COSE_SIGN 98
#define CBOR_TAG_SIGN 98
/** Tag for date counted by days from Jan 1 1970 per [RFC 8943]
- * (https://tools.ietf.org/html/rfc8943). See
+ * (https://www.rfc-editor.org/rfc/rfc8943.html). See
* QCBOREncode_AddTDaysEpoch(). */
#define CBOR_TAG_DAYS_EPOCH 100
/** Not Decoded by QCBOR. World geographic coordinates. See ISO 6709, [RFC 5870]
- * (https://tools.ietf.org/html/rfc5870) and WGS-84. No API is
+ * (https://www.rfc-editor.org/rfc/rfc5870.html) and WGS-84. No API is
* provided for this tag. */
#define CBOR_TAG_GEO_COORD 103
/** Binary MIME.*/
#define CBOR_TAG_BINARY_MIME 257
/** Tag for date string without time or time zone per [RFC 8943]
- * (https://tools.ietf.org/html/rfc8943). See
+ * (https://www.rfc-editor.org/rfc/rfc8943.html). See
* QCBOREncode_AddTDaysString(). */
#define CBOR_TAG_DAYS_STRING 1004
/** The magic number, self-described CBOR. No API is provided for this
diff --git a/inc/qcbor/qcbor_encode.h b/inc/qcbor/qcbor_encode.h
index f3ea182..c3008d4 100644
--- a/inc/qcbor/qcbor_encode.h
+++ b/inc/qcbor/qcbor_encode.h
@@ -57,10 +57,11 @@
* # 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.
+ * defined in [RFC 8949] (https://www.rfc-editor.org/rfc/rfc8949.html).
+ * More information is at http://cbor.io. This is a near-complete
+ * implementation of the specification. [RFC 8742]
+ * (https://www.rfc-editor.org/rfc/rfc8742.html) 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
@@ -222,12 +223,13 @@
* 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.
+ * 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://www.rfc-editor.org/rfc/rfc8742.html). 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,
@@ -412,7 +414,7 @@
/**
- * Initialize the encoder to prepare to encode some CBOR.
+ * Initialize the encoder.
*
* @param[in,out] pCtx The encoder context to initialize.
* @param[in] Storage The buffer into which the encoded result
@@ -488,21 +490,20 @@
* 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
+ * If you pass a smaller integer, like @c int16_t or a small value,
+ * like 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.
+ * an integer is 0. See [RFC 8949 Appendix A]
+ * (https://www.rfc-editor.org/rfc/rfc8949.html#section-appendix.a)
+ * for more examples of CBOR encoding. This compact encoding is
+ * preferred serialization CBOR as per [RFC 8949 section 4.1]
+ * (https://www.rfc-editor.org/rfc/rfc8949.html#section-4.1)
*
* 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).
+ * number of bytes based on the value.
*
* If the encoding context is in an error state, this will do
* nothing. If an error occurs when adding this integer, the internal
@@ -515,10 +516,10 @@
QCBOREncode_AddInt64(QCBOREncodeContext *pCtx, int64_t nNum);
static void
-QCBOREncode_AddInt64ToMap(QCBOREncodeContext *pCtx, const char *szLabel, int64_t uNum);
+QCBOREncode_AddInt64ToMap(QCBOREncodeContext *pCtx, const char *szLabel, int64_t nNum);
static void
-QCBOREncode_AddInt64ToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, int64_t uNum);
+QCBOREncode_AddInt64ToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, int64_t nNum);
/**
@@ -551,9 +552,9 @@
* @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.
+ * The text passed in must be unencoded UTF-8 according to
+ * [RFC 3629] (https://www.rfc-editor.org/rfc/rfc3629.html). 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.
@@ -618,30 +619,29 @@
* @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 encodes and outputs a double-precision 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
+ * single-precision or half-precision. Infinity, NaN and zero 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
+ * Half-precision floating-point numbers take up two bytes, half that
+ * of single-precision, one quarter of double-precision. Preferred
+ * serialization can therefore reduce message size down to one quarter
+ * of the original if most of the values are zero, infinity or NaN.
*
- * This automatically reduces the size of encoded CBOR, maybe even by
- * four if most of values are 0, infinity or NaN.
+ * When decoded, QCBOR returns these values as double-precision even
+ * if they were encoded as single or half-precision.
*
- * 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
+ * It is possible to disable preferred serialization when compiling
+ * QCBOR. In that case, this operates the same as
* QCBOREncode_AddDoubleNoPreferred().
*
* Error handling is the same as QCBOREncode_AddInt64().
@@ -662,11 +662,12 @@
/**
* @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] pCtx The encoding context to add the single to.
* @param[in] fNum The single-precision number to add.
*
* This is identical to QCBOREncode_AddDouble() except the input is
- * single-precision.
+ * single-precision. The preferred serialization output will be either
+ * single-precision or half-precision.
*
* See also QCBOREncode_AddDouble(), QCBOREncode_AddDoubleNoPreferred(),
* and QCBOREncode_AddFloatNoPreferred() and @ref Floating-Point.
@@ -727,7 +728,7 @@
static void
QCBOREncode_AddFloatNoPreferredToMapN(QCBOREncodeContext *pCtx, int64_t nLabel, float fNum);
-#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
+#endif /* ! USEFULBUF_DISABLE_ALL_FLOAT */
/**
@@ -834,7 +835,7 @@
* @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).
+ * [RFC 8943] (https://www.rfc-editor.org/rfc/rfc8943.html).
*
* The preferred integer serialization rules apply here so the date
* will be encoded in a minimal number of bytes. Until about the year
@@ -958,7 +959,8 @@
* @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.
+ * (https://www.rfc-editor.org/rfc/rfc4122.html) 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.
@@ -994,105 +996,106 @@
/**
* @brief Add a positive big number to the encoded output.
*
- * @param[in] pCtx The encoding context to add the big number to.
+ * @param[in] pCtx The encoding context.
* @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.
+ * @param[in] BigNumber 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).
+ * @c BigNumber makes up an aribtrary precision integer in
+ * network/big-endian byte order. The first byte is the most
+ * significant.
*
- * 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.
+ * It is encoded as CBOR major type 2, a binary string, possibly with
+ * tag @ref CBOR_TAG_POS_BIGNUM. See [RFC 8949 section 3.4.3]
+ * (https://www.rfc-editor.org/rfc/rfc8949.html#section-3.4.3). No
+ * processing, such as removal of leading zeros, is perfomed.
*
- * Often big numbers are used to represent cryptographic keys,
- * however, COSE which defines representations for keys chose not to
- * use this particular type.
+ * Sometimes big numbers are used to represent parts of cryptographic
+ * keys, however, COSE which defines representations for keys does,
+ * not use this particular type.
*/
static void
QCBOREncode_AddTPositiveBignum(QCBOREncodeContext *pCtx,
uint8_t uTagRequirement,
- UsefulBufC Bytes);
+ UsefulBufC BigNumber);
static void
QCBOREncode_AddTPositiveBignumToMapSZ(QCBOREncodeContext *pCtx,
const char *szLabel,
uint8_t uTagRequirement,
- UsefulBufC Bytes);
+ UsefulBufC BigNumber);
static void
QCBOREncode_AddTPositiveBignumToMapN(QCBOREncodeContext *pCtx,
int64_t nLabel,
uint8_t uTagRequirement,
- UsefulBufC Bytes);
+ UsefulBufC BigNumber);
static void
QCBOREncode_AddPositiveBignum(QCBOREncodeContext *pCtx,
- UsefulBufC Bytes);
+ UsefulBufC BigNumber);
static void
QCBOREncode_AddPositiveBignumToMap(QCBOREncodeContext *pCtx,
const char *szLabel,
- UsefulBufC Bytes);
+ UsefulBufC BigNumber);
static void
QCBOREncode_AddPositiveBignumToMapN(QCBOREncodeContext *pCtx,
int64_t nLabel,
- UsefulBufC Bytes);
+ UsefulBufC BigNumber);
/**
* @brief Add a negative big number to the encoded output.
*
- * @param[in] pCtx The encoding context to add the big number to.
+ * @param[in] pCtx The encoding context.
* @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.
+ * @param[in] BigNumber 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).
+ * @c BigNumber makes up an aribtrary precision integer in
+ * network/big-endian byte order. The first byte is the most
+ * significant.
*
- * 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.
+ * It is encoded as CBOR major type 2, a binary string, possibly with
+ * tag @ref CBOR_TAG_NEG_BIGNUM. See [RFC 8949 section 3.4.3]
+ * (https://www.rfc-editor.org/rfc/rfc8949.html#section-3.4.3). No
+ * processing, such as removal of leading zeros or the required offset
+ * of 1 for negative values, is perfomed.
*/
static void
QCBOREncode_AddTNegativeBignum(QCBOREncodeContext *pCtx,
uint8_t uTagRequirement,
- UsefulBufC Bytes);
+ UsefulBufC BigNumber);
static void
QCBOREncode_AddTNegativeBignumToMapSZ(QCBOREncodeContext *pCtx,
const char *szLabel,
uint8_t uTagRequirement,
- UsefulBufC Bytes);
+ UsefulBufC BigNumber);
static void
QCBOREncode_AddTNegativeBignumToMapN(QCBOREncodeContext *pCtx,
int64_t nLabel,
uint8_t uTagRequirement,
- UsefulBufC Bytes);
+ UsefulBufC BigNumber);
static void
QCBOREncode_AddNegativeBignum(QCBOREncodeContext *pCtx,
- UsefulBufC Bytes);
+ UsefulBufC BigNumber);
static void
QCBOREncode_AddNegativeBignumToMap(QCBOREncodeContext *pCtx,
const char *szLabel,
- UsefulBufC Bytes);
+ UsefulBufC BigNumber);
static void
QCBOREncode_AddNegativeBignumToMapN(QCBOREncodeContext *pCtx,
int64_t nLabel,
- UsefulBufC Bytes);
+ UsefulBufC BigNumber);
#ifndef QCBOR_DISABLE_EXP_AND_MANTISSA
@@ -1370,7 +1373,7 @@
UsefulBufC Mantissa,
bool bIsNegative,
int64_t nBase2Exponent);
-#endif /* QCBOR_DISABLE_EXP_AND_MANTISSA */
+#endif /* ! QCBOR_DISABLE_EXP_AND_MANTISSA */
/**
@@ -1382,7 +1385,7 @@
* @param[in] URI Pointer and length of the URI.
*
* The format of URI must be per [RFC 3986]
- * (https://tools.ietf.org/html/rfc3986).
+ * (https://www.rfc-editor.org/rfc/rfc3986.html).
*
* It is output as CBOR major type 3, a text string, with tag @ref
* CBOR_TAG_URI indicating the text string is a URI.
@@ -1434,7 +1437,7 @@
* @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).
+ * (https://www.rfc-editor.org/rfc/rfc4648.html).
*
* It is output as CBOR major type 3, a text string, with tag @ref
* CBOR_TAG_B64 indicating the text string is Base64 encoded.
@@ -1442,7 +1445,7 @@
static void
QCBOREncode_AddTB64Text(QCBOREncodeContext *pCtx,
uint8_t uTagRequirement,
- UsefulBufC B64Text);
+ UsefulBufC B64Text);
static void
QCBOREncode_AddTB64TextToMapSZ(QCBOREncodeContext *pCtx,
@@ -1481,8 +1484,8 @@
* @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).
+ * The text content is base64URL encoded text as per
+ * [RFC 4648] (https://www.rfc-editor.org/rfc/rfc4648.html).
*
* It is output as CBOR major type 3, a text string, with tag
* @ref CBOR_TAG_B64URL indicating the text string is a Base64url
@@ -1577,7 +1580,7 @@
* @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.
+ * (https://www.rfc-editor.org/rfc/rfc2045.html) 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
@@ -1637,11 +1640,11 @@
* @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).
+ * The string szDate should be in the form of
+ * [RFC 3339] (https://www.rfc-editor.org/rfc/rfc3339.html) as defined
+ * by section 3.3 in [RFC 4287] (https://www.rfc-editor.org/rfc/rfc4287.html).
+ * This is as described in section 3.4.1 in [RFC 8949]
+ * (https://www.rfc-editor.org/rfc/rfc8949.html#section3.1.4).
*
* Note that this function doesn't validate the format of the date
* string at all. If you add an incorrect format date string, the
@@ -1694,10 +1697,10 @@
* @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
+ * [RFC 8943] (https://www.rfc-editor.org/rfc/rfc8943.html), 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
+ * [RFC 3339] (https://www.rfc-editor.org/rfc/rfc3339.html). Examples of this
* are "1985-04-12" and "1937-01-01". The time and the time zone are
* never included.
*
@@ -1779,7 +1782,7 @@
*
* Note that this value will not translate to JSON.
*
- * This Undef doesn't have any special meaning in CBOR such as a
+ * "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().
@@ -1924,8 +1927,8 @@
* 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.
+ * See the [RFC 8949] (https://www.rfc-editor.org/rfc/rfc8949.html)
+ * for a lot more information on creating maps.
*/
static void
QCBOREncode_OpenMap(QCBOREncodeContext *pCtx);
@@ -2042,11 +2045,11 @@
* 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.
+ * cryptographically hashed, as part of a [RFC 9052, COSE]
+ * (https://www.rfc-editor.org/rfc/rfc9052.html) 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
@@ -2085,8 +2088,8 @@
*
* 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)
+ * this data can be hashed (e.g., with SHA-256) as part of a
+ * [RFC 9052, COSE] (https://www.rfc-editor.org/rfc/rfc9052.html)
* 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
@@ -2119,7 +2122,7 @@
*
* @param[in] pCtx The encoding context.
*
- * This cancels QCBOREncode_BstrWrap() making tghe encoding as if it
+ * This cancels QCBOREncode_BstrWrap() making the encoding as if it
* were never called.
*
* WARNING: This does not work on QCBOREncode_BstrWrapInMap()
@@ -2141,8 +2144,7 @@
* @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
+ * be complete with no arrays or maps that are incomplete. 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
@@ -2366,7 +2368,7 @@
/**
- * Encode the "head" of a CBOR data item.
+ * @brief 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.
@@ -2394,7 +2396,7 @@
* 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
+ * needs to be 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.
@@ -2543,19 +2545,19 @@
static inline void
QCBOREncode_AddInt64ToMap(QCBOREncodeContext *pMe,
const char *szLabel,
- const int64_t uNum)
+ const int64_t nNum)
{
QCBOREncode_AddSZString(pMe, szLabel);
- QCBOREncode_AddInt64(pMe, uNum);
+ QCBOREncode_AddInt64(pMe, nNum);
}
static inline void
QCBOREncode_AddInt64ToMapN(QCBOREncodeContext *pMe,
const int64_t nLabel,
- const int64_t uNum)
+ const int64_t nNum)
{
QCBOREncode_AddInt64(pMe, nLabel);
- QCBOREncode_AddInt64(pMe, uNum);
+ QCBOREncode_AddInt64(pMe, nNum);
}
@@ -2635,10 +2637,6 @@
}
-
-/*
- * Public functions for adding a tag. See qcbor/qcbor_encode.h
- */
static inline void
QCBOREncode_AddTag(QCBOREncodeContext *pMe, const uint64_t uTag)
{
@@ -2647,6 +2645,7 @@
+
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
static inline void
@@ -2673,7 +2672,7 @@
QCBOREncode_Private_AddPreferredDouble(pMe, dNum);
#else /* QCBOR_DISABLE_PREFERRED_FLOAT */
QCBOREncode_AddDoubleNoPreferred(pMe, dNum);
-#endif /* QCBOR_DISABLE_PREFERRED_FLOAT */
+#endif /* ! QCBOR_DISABLE_PREFERRED_FLOAT */
}
static inline void
@@ -2702,7 +2701,7 @@
QCBOREncode_Private_AddPreferredFloat(pMe, fNum);
#else /* QCBOR_DISABLE_PREFERRED_FLOAT */
QCBOREncode_AddFloatNoPreferred(pMe, fNum);
-#endif /* QCBOR_DISABLE_PREFERRED_FLOAT */
+#endif /* ! QCBOR_DISABLE_PREFERRED_FLOAT */
}
static inline void
@@ -2758,7 +2757,7 @@
QCBOREncode_AddInt64(pMe, nLabel);
QCBOREncode_AddFloatNoPreferred(pMe, dNum);
}
-#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
+#endif /* ! USEFULBUF_DISABLE_ALL_FLOAT */
@@ -2897,9 +2896,6 @@
}
-/*
- * Public functions for adding only a byte string length. See qcbor/qcbor_encode.h
- */
static inline void
QCBOREncode_AddBytesLenOnly(QCBOREncodeContext *pMe, const UsefulBufC Bytes)
{
@@ -3469,7 +3465,7 @@
bIsNegative,
nBase2Exponent);
}
-#endif /* QCBOR_DISABLE_EXP_AND_MANTISSA */
+#endif /* ! QCBOR_DISABLE_EXP_AND_MANTISSA */
static inline void
@@ -3844,7 +3840,7 @@
pMe->uError = QCBOR_ERR_ENCODE_UNSUPPORTED;
return;
}
-#endif /* !QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
+#endif /* ! QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
QCBOREncode_Private_AddType7(pMe, 0, uNum);
}
diff --git a/src/qcbor_encode.c b/src/qcbor_encode.c
index 218e12c..3986cbb 100644
--- a/src/qcbor_encode.c
+++ b/src/qcbor_encode.c
@@ -1,35 +1,35 @@
-/*==============================================================================
- Copyright (c) 2016-2018, The Linux Foundation.
- Copyright (c) 2018-2024, 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-2024, 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.
+ * ========================================================================= */
#include "qcbor/qcbor_encode.h"
@@ -114,7 +114,7 @@
if(1 >= QCBOR_MAX_ITEMS_IN_ARRAY - pNesting->pCurrentNesting->uCount) {
return QCBOR_ERR_ARRAY_TOO_LONG;
}
-#endif /* !QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
+#endif /* ! QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
pNesting->pCurrentNesting->uCount++;
@@ -440,7 +440,7 @@
nAdditionalInfo = CBOR_SIMPLE_BREAK;
} else
-#endif /* !QCBOR_DISABLE_INDEFINITE_LENGTH_ARRAYS */
+#endif /* ! QCBOR_DISABLE_INDEFINITE_LENGTH_ARRAYS */
if (uArgument < CBOR_TWENTY_FOUR && uMinLen == 0) {
/* Simple case where argument is < 24 */
nAdditionalInfo = (int)uArgument;
@@ -519,7 +519,7 @@
}
#else
(void)Nesting_Increment(&(pMe->nesting));
-#endif /* !QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
+#endif /* ! QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
}
@@ -570,7 +570,7 @@
/*
- * Public functions for adding signed integers. See qcbor/qcbor_encode.h
+ * Public function for adding signed integers. See qcbor/qcbor_encode.h
*/
void
QCBOREncode_AddInt64(QCBOREncodeContext *pMe, const int64_t nNum)
@@ -620,7 +620,7 @@
/*
- * Public functions for adding raw encoded CBOR. See qcbor/qcbor_encode.h
+ * Public function for adding raw encoded CBOR. See qcbor/qcbor_encode.h
*/
void
QCBOREncode_AddEncoded(QCBOREncodeContext *pMe, const UsefulBufC Encoded)
@@ -663,7 +663,7 @@
const IEEE754_union uNum = IEEE754_SingleToHalf(fNum);
QCBOREncode_Private_AddType7(pMe, (uint8_t)uNum.uSize, uNum.uValue);
}
-#endif /* !QCBOR_DISABLE_PREFERRED_FLOAT */
+#endif /* ! QCBOR_DISABLE_PREFERRED_FLOAT */
#ifndef QCBOR_DISABLE_EXP_AND_MANTISSA
@@ -727,7 +727,7 @@
}
QCBOREncode_CloseArray(pMe);
}
-#endif /* QCBOR_DISABLE_EXP_AND_MANTISSA */
+#endif /* ! QCBOR_DISABLE_EXP_AND_MANTISSA */
/**
@@ -797,7 +797,7 @@
*/
QCBOREncode_Private_OpenMapOrArray(pMe, uMajorType);
}
-#endif
+#endif /* ! QCBOR_DISABLE_INDEFINITE_LENGTH_ARRAYS */
/**
@@ -832,7 +832,7 @@
return true;
}
-#else /* !QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
+#else /* ! QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
/* None of these checks are performed if the encode guards are
* turned off as they all relate to correct calling.
*
@@ -842,14 +842,14 @@
(void)uMajorType;
(void)pMe;
-#endif /* !QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
+#endif /* ! QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
return false;
}
/**
- * @brief Insert the CBOR head for a map, array or wrapped bstr
+ * @brief Insert the CBOR head for a map, array or wrapped bstr.
*
* @param pMe QCBOR encoding context.
* @param uMajorType One of CBOR_MAJOR_TYPE_XXXX.
@@ -911,7 +911,7 @@
/*
- * Public functions for closing bstr wrapping. See qcbor/qcbor_encode.h
+ * Public function for closing bstr wrapping. See qcbor/qcbor_encode.h
*/
void
QCBOREncode_CloseBstrWrap2(QCBOREncodeContext *pMe,
@@ -975,7 +975,7 @@
* security hole, so no extra code or state is added to handle this
* condition.
*/
-#endif /* QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
+#endif /* ! QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
Nesting_Decrease(&(pMe->nesting));
Nesting_Decrement(&(pMe->nesting));
@@ -997,7 +997,7 @@
pMe->uError = QCBOR_ERR_OPEN_BYTE_STRING;
return;
}
-#endif /* QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
+#endif /* ! QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
QCBOREncode_Private_OpenMapOrArray(pMe, CBOR_MAJOR_NONE_TYPE_OPEN_BSTR);
}
@@ -1020,7 +1020,6 @@
#ifndef QCBOR_DISABLE_INDEFINITE_LENGTH_ARRAYS
-
/**
* @brief Semi-private method to close a map, array with indefinite length
*
@@ -1042,7 +1041,7 @@
QCBOREncode_Private_AppendCBORHead(pMe, CBOR_MAJOR_NONE_TYPE_SIMPLE_BREAK, CBOR_SIMPLE_BREAK, 0);
Nesting_Decrease(&(pMe->nesting));
}
-#endif
+#endif /* ! QCBOR_DISABLE_INDEFINITE_LENGTH_ARRAYS */
/*
@@ -1060,7 +1059,7 @@
pMe->uError = QCBOR_ERR_ARRAY_OR_MAP_STILL_OPEN;
goto Done;
}
-#endif /* QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
+#endif /* ! QCBOR_DISABLE_ENCODE_USAGE_GUARDS */
*pEncodedCBOR = UsefulOutBuf_OutUBuf(&(pMe->OutBuf));
@@ -1070,7 +1069,7 @@
/*
- * Public functions to get size of the encoded result. See qcbor/qcbor_encode.h
+ * Public function to get size of the encoded result. See qcbor/qcbor_encode.h
*/
QCBORError
QCBOREncode_FinishGetSize(QCBOREncodeContext *pMe, size_t *puEncodedLen)