Add discussion of line ending convention for type 3
diff --git a/inc/qcbor/qcbor_decode.h b/inc/qcbor/qcbor_decode.h
index 5c2e3f5..f19d7b9 100644
--- a/inc/qcbor/qcbor_decode.h
+++ b/inc/qcbor/qcbor_decode.h
@@ -179,8 +179,9 @@
#define QCBOR_TYPE_MAP 5
/** 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. Data is in @c
- val.string. */
+/** 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. */
#define QCBOR_TYPE_TEXT_STRING 7
/** Type for a positive big number. Data is in @c val.bignum, a
pointer and a length. */
diff --git a/inc/qcbor/qcbor_encode.h b/inc/qcbor/qcbor_encode.h
index 0171112..8f4f1cf 100644
--- a/inc/qcbor/qcbor_encode.h
+++ b/inc/qcbor/qcbor_encode.h
@@ -488,6 +488,23 @@
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);
@@ -1280,6 +1297,9 @@
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,
diff --git a/inc/qcbor/qcbor_spiffy_decode.h b/inc/qcbor/qcbor_spiffy_decode.h
index ae66a3b..9ea8d13 100644
--- a/inc/qcbor/qcbor_spiffy_decode.h
+++ b/inc/qcbor/qcbor_spiffy_decode.h
@@ -465,6 +465,9 @@
See @ref Decode-Errors for discussion on how error handling works. 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);
@@ -1408,6 +1411,9 @@
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,