minor doc and style fix ups for encoder
diff --git a/inc/qcbor.h b/inc/qcbor.h
index c945757..7b684be 100644
--- a/inc/qcbor.h
+++ b/inc/qcbor.h
@@ -982,18 +982,20 @@
This outputs a floating-point number with CBOR major type 7.
- This will selectively encode the double-precision floating point number as either
- double-precision, single-precision or half-precision. It will always encode infinity, NaN and 0
- has 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.
+ This will selectively encode the double-precision floating point
+ number as either double-precision, single-precision or
+ half-precision. It will always encode infinity, NaN and 0 has 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.
- 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 2 bytes, half that of
+ single-precision, one quarter of double-precision
- This automatically reduces the size of encoded messages a lot, maybe even by four if most of values are
- 0, infinity or NaN.
+ This automatically reduces the size of encoded messages a lot, maybe
+ even by four if most of values are 0, infinity or NaN.
On decode, these will always be returned as a double.
@@ -1327,24 +1329,24 @@
Arrays are the basic CBOR aggregate or structure type. Call this
function to start or open an array. Then call the various 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.
+ 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
- OpenArray again before calling CloseArray. While CBOR has no limit
- on nesting, this implementation does in order to keep it smaller and
- simpler. The limit is QCBOR_MAX_ARRAY_NESTING. This is the max
- number of times this can be called without calling
+ QCBOREncode_OpenArray() again before calling CloseArray. While CBOR
+ has no limit on nesting, this implementation does in order to keep it
+ smaller and simpler. The limit is QCBOR_MAX_ARRAY_NESTING. This is
+ the max number of times this can be called without calling
QCBOREncode_CloseArray(). QCBOREncode_Finish() will return
- QCBOR_ERR_ARRAY_TOO_LONG when it is called as this function just sets
- an error state and returns no value when this occurs.
+ 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 32,767 items to an array or map, incorrect CBOR will
- be produced by this encoder.
+ If you try to add more than QCBOR_MAX_ITEMS_IN_ARRAY items to a
+ single array or map, 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 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.
*/
@@ -1361,19 +1363,19 @@
@param[in] pCtx The context to add to.
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().
+ 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 QCBOR_ERR_TOO_MANY_CLOSES will be returned when
- QCBOREncode_Finish() is called.
+ If this has been called more times than QCBOREncode_OpenArray(), then
+ 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, QCBOR_ERR_CLOSE_MISMATCH will be returned when QCBOREncode_Finish()
+ If this is called and it is not an array that is currently open,
+ QCBOR_ERR_CLOSE_MISMATCH will be returned when QCBOREncode_Finish()
is called.
*/
static void QCBOREncode_CloseArray(QCBOREncodeContext *pCtx);
@@ -1384,7 +1386,8 @@
@param[in] pCtx The context to add to.
- See QCBOREncode_OpenArray() for more information.
+ 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.
@@ -1392,9 +1395,8 @@
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.
+ typically, integers as this gives the most compact output. They might
+ also be text strings which gives readability and translation to JSON.
Every QCBOREncode_AddXXX() call has once version that is "InMap" for
adding items to maps with string labels and on that is "InMapN" that
@@ -1421,8 +1423,8 @@
@param[in] pCtx The context to add to.
- The closes a map opened by QCBOREncode_OpenMap(). It reduces
- nesting level by one.
+ The 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
@@ -1456,19 +1458,19 @@
another encoding (e.g. the COSE to-be-signed bytes, the
Sig_structure) potentially saving a lot of memory.
- When constructing cryptographically signed CBOR objects, maps or arrays, they
- typically are encoded
- normally and then wrapped as a byte string. The COSE standard for example
- does this. The wrapping is simply treating the encoded CBOR map
- as a byte string.
+ When constructing cryptographically signed CBOR objects, maps or
+ arrays, they typically are encoded normally and then wrapped as a
+ byte string. The COSE standard for example does this. The wrapping is
+ simply treating the encoded CBOR map as a byte string.
- The stated purpose of this wrapping is to prevent code relaying the signed data
- but not verifying it from tampering with the signed data thus making
- the signature unverifiable. It is also quite beneficial for the
- signature verification code. Standard CBOR parsers usually do not give
- access to partially parsed CBOR as would be need to check the signature
- of some CBOR. With this wrapping, standard CBOR parsers can be used
- to get to all the data needed for a signature verification.
+ The stated purpose of this wrapping is to prevent code relaying the
+ signed data but not verifying it from tampering with the signed data
+ thus making the signature unverifiable. It is also quite beneficial
+ for the signature verification code. Standard CBOR parsers usually do
+ not give access to partially parsed CBOR as would be need to check
+ the signature of some CBOR. With this wrapping, standard CBOR parsers
+ can be used to get to all the data needed for a signature
+ verification.
*/
static void QCBOREncode_BstrWrap(QCBOREncodeContext *pCtx);
@@ -1510,7 +1512,7 @@
/**
- Add some already-encoded CBOR bytes.
+ @brief Add some already-encoded CBOR bytes.
@param[in] pCtx The context to add to.
@param[in] Encoded The already-encoded CBOR to add to the context.
@@ -1536,7 +1538,7 @@
/**
- Get the encoded result.
+ @brief Get the encoded result.
@param[in] pCtx The context to finish encoding with.
@param[out] pEncodedCBOR Pointer and length of encoded CBOR.
@@ -1568,7 +1570,7 @@
/**
- Get the encoded CBOR and error status.
+ @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.
diff --git a/src/qcbor_encode.c b/src/qcbor_encode.c
index 94448b5..5bab661 100644
--- a/src/qcbor_encode.c
+++ b/src/qcbor_encode.c
@@ -161,10 +161,10 @@
until Finish is called. The CBOR errors are in me->uError.
UsefulOutBuf also tracks whether the buffer is full or not in its
context. Once either of these errors is set they are never
- cleared. Only Init() resets them. Or said another way, they must
+ cleared. Only QCBOREncode_Init() resets them. Or said another way, they must
never be cleared or we'll tell the caller all is good when it is not.
- Only one error code is reported by Finish() even if there are
+ Only one error code is reported by QCBOREncode_Finish() even if there are
multiple errors. The last one set wins. The caller might have to fix
one error to reveal the next one they have to fix. This is OK.
@@ -177,34 +177,29 @@
number of items in an array. It would save a lot of code, it is
extremely unlikely that any one will every put 65,000 items in an
array, and the only bad thing that would happen is the CBOR would be
- bogus. Once we prove that is the only consequence, then we can make
- the change.
+ bogus.
Since this does not parse any input, you could in theory remove all
error checks in this code if you knew the caller called it
correctly. Maybe someday CDDL or some such language will be able to
generate the code to call this and the calling code would always be
correct. This could also automatically size some of the data
- structures like array/map nesting resulting in some good memory
+ structures like array/map nesting resulting in some stack memory
savings.
- Errors returned here fall into three categories:
+ Errors returned here fall into two categories:
Sizes
- QCBOR_ERR_BUFFER_TOO_LARGE -- A buffer passed in > UINT32_MAX
+ QCBOR_ERR_BUFFER_TOO_LARGE -- Encoded output exceeded UINT32_MAX
QCBOR_ERR_BUFFER_TOO_SMALL -- output buffer too small
- QCBOR_ERR_ARRAY_NESTING_TOO_DEEP -- Too many opens without closes
+ QCBOR_ERR_ARRAY_NESTING_TOO_DEEP -- Array/map nesting > QCBOR_MAX_ARRAY_NESTING1
QCBOR_ERR_ARRAY_TOO_LONG -- Too many things added to an array/map
Nesting constructed incorrectly
QCBOR_ERR_TOO_MANY_CLOSES -- more close calls than opens
QCBOR_ERR_CLOSE_MISMATCH -- Type of close does not match open
QCBOR_ERR_ARRAY_OR_MAP_STILL_OPEN -- Finish called without enough closes
-
- Bad data
- QCBOR_ERR_BAD_SIMPLE -- Simple value integer not valid
-
*/
@@ -276,7 +271,7 @@
{
/*
This code does endian conversion without hton or knowing the
- endianness of the machine using masks and shifts. this avoids the
+ endianness of the machine using masks and shifts. This avoids the
dependency on hton and the mess of figuring out how to find the
machine's endianness.
@@ -317,7 +312,7 @@
until all bits from uNumber have been encoded
and the minimum encoding size is reached.
Minimum encoding size is for floating point
- numbers with zero bytes correctly.
+ numbers with zero bytes.
*/
static const uint8_t aIterate[] = {1,1,2,4};
uint8_t i;
@@ -340,8 +335,6 @@
}
-
-
/*
Append the type and number info to the end of the buffer.
@@ -361,6 +354,7 @@
+
/*
Public functions for closing arrays and maps. See header qcbor.h
*/
@@ -410,7 +404,7 @@
*/
void QCBOREncode_AddBuffer(QCBOREncodeContext *me, uint8_t uMajorType, UsefulBufC Bytes)
{
- if(!me->uError) {
+ if(me->uError == QCBOR_SUCCESS) {
// If it is not Raw CBOR, add the type and the length
if(uMajorType != CBOR_MAJOR_NONE_TYPE_RAW) {
AppendEncodedTypeAndNumber(me, uMajorType, Bytes.len);
@@ -434,8 +428,6 @@
}
-
-
/*
Semi-private function. It is exposed to user of the interface,
but they will usually call one of the inline wrappers rather than this.
@@ -482,7 +474,7 @@
{
// Add one item to the nesting level we are in for the new map or array
me->uError = Nesting_Increment(&(me->nesting));
- if(!me->uError) {
+ if(me->uError == QCBOR_SUCCESS) {
size_t uEndPosition = UsefulOutBuf_GetEndPosition(&(me->OutBuf));
if(uEndPosition >= UINT32_MAX-sizeof(uint64_t)) {
me->uError = QCBOR_ERR_BUFFER_TOO_LARGE;
@@ -502,7 +494,7 @@
uint8_t uMajorType,
UsefulBufC *pWrappedCBOR)
{
- if(!me->uError) {
+ if(me->uError == QCBOR_SUCCESS) {
if(!Nesting_IsInNest(&(me->nesting))) {
me->uError = QCBOR_ERR_TOO_MANY_CLOSES;
} else if(Nesting_GetMajorType(&(me->nesting)) != uMajorType) {
@@ -550,6 +542,7 @@
+
/*
Public functions to finish and get the encoded result. See header qcbor.h
*/
@@ -614,7 +607,7 @@
6 QCBOREncode_AddTag
7 QCBOREncode_AddDouble, QCBOREncode_AddType7
- Object code sizes on X86 with LLVM compiler and -Os (Dec 14, 2018)
+ Object code sizes on X86 with LLVM compiler and -Os (Dec 30, 2018)
_QCBOREncode_Init 69
_QCBOREncode_AddUInt64 76
diff --git a/test/qcbor_encode_tests.c b/test/qcbor_encode_tests.c
index fcded50..9728a90 100644
--- a/test/qcbor_encode_tests.c
+++ b/test/qcbor_encode_tests.c
@@ -1972,6 +1972,8 @@
return -9;
}
+ /* QCBOR_ERR_ARRAY_TOO_LONG is not tested here as
+ it would require a 64KB of RAM to test */
return 0;
}