Tests and documentation for CBOR Sequences (#46)
CBOR Sequences, RFC 8742, were always supported. This PR just adds documentation explaining how. It also adds regression tests.
diff --git a/inc/qcbor/qcbor_decode.h b/inc/qcbor/qcbor_decode.h
index 9499e7f..f799517 100644
--- a/inc/qcbor/qcbor_decode.h
+++ b/inc/qcbor/qcbor_decode.h
@@ -49,6 +49,12 @@
/**
+ @file qcbor_decode.h
+
+ This describes CBOR decoding.
+*/
+
+/**
The decode mode options.
*/
typedef enum {
@@ -812,12 +818,35 @@
@param[in] pCtx The context to check.
- @return An error or @ref QCBOR_SUCCESS.
-
- This tells you if all the bytes given to QCBORDecode_Init() have been
- consumed and whether all maps and arrays were closed. The decode is
- considered to be incorrect or incomplete if not and an error will be
- returned.
+ @retval QCBOR_ERR_ARRAY_OR_MAP_STILL_OPEN The CBOR is not well-formed
+ as some map or array was not closed off. This should always be treated as an
+ unrecoverable error.
+
+ @retval QCBOR_ERR_EXTRA_BYTES The CBOR was decoded correctly and
+ all maps and arrays are closed, but some of the bytes in the input were not consumed.
+ This may or may not be considered an error.
+
+ @retval QCBOR_SUCCES There were no errors and all bytes were
+ consumed.
+
+ This should always be called to determine if all maps and arrays
+ where correctly closed and that the CBOR was well-formed.
+
+ This calls the destructor for the string allocator, if one is in use.
+
+ Some CBOR protocols use a CBOR sequence [RFC 8742]
+ (https://tools.ietf.org/html/rfc8742) . A CBOR sequence typically
+ doesn't start out with a map or an array. The end of the CBOR is
+ determined in some other way, perhaps by external framing, or by the
+ occurrence of some particular CBOR data item or such. The buffer given
+ to decode must start out with valid CBOR, but it can have extra bytes
+ at the end that are not CBOR or CBOR that is to be ignored.
+
+ QCBORDecode_Finish() should still be called when decoding CBOR
+ Sequences to check that the input decoded was well-formed. If the
+ input was well-formed and there are extra bytes at the end @ref
+ QCBOR_ERR_EXTRA_BYTES will be returned. This can be considered a
+ successful decode.
*/
QCBORError QCBORDecode_Finish(QCBORDecodeContext *pCtx);
diff --git a/inc/qcbor/qcbor_encode.h b/inc/qcbor/qcbor_encode.h
index 31fda52..46fa578 100644
--- a/inc/qcbor/qcbor_encode.h
+++ b/inc/qcbor/qcbor_encode.h
@@ -210,6 +210,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.
@anchor Tags-Overview
Any CBOR data item can be tagged to add semantics, define a new data