From 0a5c787992901b0847af013554c99d12612a0463 Mon Sep 17 00:00:00 2001 From: Stuart Longland Date: Wed, 30 Jun 2021 16:20:10 +1000 Subject: [PATCH 1/6] cborparser: Document `cbor_parser_init_reader`. Describe the input parameters for the function and how they are used as best we understand from on-paper analysis of the C code. --- src/cborparser.c | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/cborparser.c b/src/cborparser.c index 31c8d8bf..0c7f6407 100644 --- a/src/cborparser.c +++ b/src/cborparser.c @@ -345,6 +345,23 @@ CborError cbor_parser_init(const uint8_t *buffer, size_t size, uint32_t flags, C return preparse_value(it); } +/** + * Initializes the CBOR parser for parsing a document that is read by an + * abstract reader interface defined by \a ops. The iterator to the first + * element is returned in \a it. + * + * The \a parser structure needs to remain valid throughout the decoding + * process. It is not thread-safe to share one CborParser among multiple + * threads iterating at the same time, but the object can be copied so multiple + * threads can iterate. + * + * The \a ops structure defines functions that implement the read process from + * the buffer given, see \ref CborParserOperations for further details. + * + * The \a token is passed as the first argument to all + * \ref CborParserOperations methods, and may be used to pass additional + * context information to the reader implementation. + */ CborError cbor_parser_init_reader(const struct CborParserOperations *ops, CborParser *parser, CborValue *it, void *token) { memset(parser, 0, sizeof(*parser)); From 6820d654d5b5cbcc80df0281c25ecc8b7ddbaeed Mon Sep 17 00:00:00 2001 From: Stuart Longland Date: Wed, 30 Jun 2021 17:41:45 +1000 Subject: [PATCH 2/6] cbor: Document the reader interface. --- src/cbor.h | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/src/cbor.h b/src/cbor.h index d5570265..aae547c1 100644 --- a/src/cbor.h +++ b/src/cbor.h @@ -319,11 +319,80 @@ enum CborParserIteratorFlags }; struct CborValue; + +/** + * Defines an interface for abstract document readers. This structure is used + * in conjunction with \ref cbor_parser_init_reader to define how the various + * required operations are to be implemented. + */ struct CborParserOperations { + /** + * Determines whether \a len bytes may be read from the reader. This is + * called before \ref read_bytes and \ref transfer_bytes to ensure it is safe + * to read the requested number of bytes from the reader. + * + * \param token An opaque object passed to \ref cbor_parser_init_reader + * that may be used to pass context information between the + * \ref CborParserOperations methods. + * + * \param len The number of bytes sought. + * + * \retval true \a len bytes may be read from the reader. + * \retval false Insufficient data is available to be read at this time. + */ bool (*can_read_bytes)(void *token, size_t len); + + /** + * Reads \a len bytes from the reader starting at \a offset bytes from + * the current read position and copies them to \a dst. The read pointer + * is *NOT* modified by this operation. + * + * \param token An opaque object passed to \ref cbor_parser_init_reader + * that may be used to pass context information between the + * \ref CborParserOperations methods. + * + * \param dst The buffer the read bytes will be copied to. + * + * \param offset The starting position for the read relative to the + * current read position. + * + * \param len The number of bytes sought. + */ void *(*read_bytes)(void *token, void *dst, size_t offset, size_t len); + + /** + * Skips past \a len bytes from the reader without reading them. The read + * pointer is advanced in the process. + * + * \param token An opaque object passed to \ref cbor_parser_init_reader + * that may be used to pass context information between the + * \ref CborParserOperations methods. + * + * \param len The number of bytes skipped. + */ void (*advance_bytes)(void *token, size_t len); + + /** + * Overwrite the user-supplied pointer \a userptr with the address where the + * data indicated by \a offset is located, then advance the read pointer + * \a len bytes beyond that point. + * + * This routine is used for accessing strings embedded in CBOR documents + * (both text and binary strings). + * + * \param token An opaque object passed to \ref cbor_parser_init_reader + * that may be used to pass context information between the + * \ref CborParserOperations methods. + * + * \param userptr The pointer that will be updated to reference the location + * of the data in the buffer. + * + * \param offset The starting position for the read relative to the + * current read position. + * + * \param len The number of bytes sought. + */ CborError (*transfer_string)(void *token, const void **userptr, size_t offset, size_t len); }; From cacf527341fdebf40afe811d468b5bbd8a8854e4 Mon Sep 17 00:00:00 2001 From: Stuart Longland Date: Sat, 3 Jul 2021 11:56:13 +1000 Subject: [PATCH 3/6] cborencoder: Document the write callback function. What is not known, is what the significance is of `CborEncoderAppendType`. It basically tells the writer the nature of the data being written, but the default implementation ignores this and just blindly appends it no matter what. That raises the question of why it's important enough that the writer function needs to know about it. --- src/cbor.h | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/src/cbor.h b/src/cbor.h index aae547c1..491932ab 100644 --- a/src/cbor.h +++ b/src/cbor.h @@ -214,7 +214,20 @@ typedef enum CborEncoderAppendType CborEncoderAppendRawData = 2 } CborEncoderAppendType; -typedef CborError (*CborEncoderWriteFunction)(void *, const void *, size_t, CborEncoderAppendType); +/** + * Writer interface call-back function. When there is data to be written to + * the CBOR document, this routine will be called. The \a token parameter is + * taken from the \a token argument provided to \ref cbor_encoder_init_writer + * and may be used in any way the writer function sees fit. + * + * The \a data parameter contains a pointer to the raw bytes to be copied to + * the output buffer, with \a len specifying how long the payload is, which + * can be as small as a single byte or an entire (byte or text) string. + * + * The \a append parameter informs the writer function whether it is writing + * a string or general CBOR data. + */ +typedef CborError (*CborEncoderWriteFunction)(void *token, const void *data, size_t len, CborEncoderAppendType append); enum CborEncoderFlags { From 134864402ce792330bf8d67acf526d0e36726db9 Mon Sep 17 00:00:00 2001 From: Stuart Longland Date: Wed, 8 Sep 2021 08:22:53 +1000 Subject: [PATCH 4/6] cbor.h, cborparser.c: Migrate parser documentation. Not 100% sure of the syntax for documenting struct-members outside of the struct as I'm too used to doing it inline, hopefully this works as expected. :-) --- src/cbor.h | 69 +------------------------------------------ src/cborparser.c | 77 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+), 68 deletions(-) diff --git a/src/cbor.h b/src/cbor.h index 491932ab..1ccf974f 100644 --- a/src/cbor.h +++ b/src/cbor.h @@ -333,79 +333,12 @@ enum CborParserIteratorFlags struct CborValue; -/** - * Defines an interface for abstract document readers. This structure is used - * in conjunction with \ref cbor_parser_init_reader to define how the various - * required operations are to be implemented. - */ + struct CborParserOperations { - /** - * Determines whether \a len bytes may be read from the reader. This is - * called before \ref read_bytes and \ref transfer_bytes to ensure it is safe - * to read the requested number of bytes from the reader. - * - * \param token An opaque object passed to \ref cbor_parser_init_reader - * that may be used to pass context information between the - * \ref CborParserOperations methods. - * - * \param len The number of bytes sought. - * - * \retval true \a len bytes may be read from the reader. - * \retval false Insufficient data is available to be read at this time. - */ bool (*can_read_bytes)(void *token, size_t len); - - /** - * Reads \a len bytes from the reader starting at \a offset bytes from - * the current read position and copies them to \a dst. The read pointer - * is *NOT* modified by this operation. - * - * \param token An opaque object passed to \ref cbor_parser_init_reader - * that may be used to pass context information between the - * \ref CborParserOperations methods. - * - * \param dst The buffer the read bytes will be copied to. - * - * \param offset The starting position for the read relative to the - * current read position. - * - * \param len The number of bytes sought. - */ void *(*read_bytes)(void *token, void *dst, size_t offset, size_t len); - - /** - * Skips past \a len bytes from the reader without reading them. The read - * pointer is advanced in the process. - * - * \param token An opaque object passed to \ref cbor_parser_init_reader - * that may be used to pass context information between the - * \ref CborParserOperations methods. - * - * \param len The number of bytes skipped. - */ void (*advance_bytes)(void *token, size_t len); - - /** - * Overwrite the user-supplied pointer \a userptr with the address where the - * data indicated by \a offset is located, then advance the read pointer - * \a len bytes beyond that point. - * - * This routine is used for accessing strings embedded in CBOR documents - * (both text and binary strings). - * - * \param token An opaque object passed to \ref cbor_parser_init_reader - * that may be used to pass context information between the - * \ref CborParserOperations methods. - * - * \param userptr The pointer that will be updated to reference the location - * of the data in the buffer. - * - * \param offset The starting position for the read relative to the - * current read position. - * - * \param len The number of bytes sought. - */ CborError (*transfer_string)(void *token, const void **userptr, size_t offset, size_t len); }; diff --git a/src/cborparser.c b/src/cborparser.c index 0c7f6407..a796bd0b 100644 --- a/src/cborparser.c +++ b/src/cborparser.c @@ -132,6 +132,83 @@ * \endif */ +/** + * \struct CborParserOperations + * + * Defines an interface for abstract document readers. This structure is used + * in conjunction with \ref cbor_parser_init_reader to define how the various + * required operations are to be implemented. + * + * + * \var CborParserOperations::can_read_bytes + * + * Determines whether \a len bytes may be read from the reader. This is + * called before \ref read_bytes and \ref transfer_bytes to ensure it is safe + * to read the requested number of bytes from the reader. + * + * \param token An opaque object passed to \ref cbor_parser_init_reader + * that may be used to pass context information between the + * \ref CborParserOperations methods. + * + * \param len The number of bytes sought. + * + * \retval true \a len bytes may be read from the reader. + * \retval false Insufficient data is available to be read at this time. + * + * + * \var CborParserOperations::read_bytes + * + * Reads \a len bytes from the reader starting at \a offset bytes from + * the current read position and copies them to \a dst. The read pointer + * is *NOT* modified by this operation. + * + * \param token An opaque object passed to \ref cbor_parser_init_reader + * that may be used to pass context information between the + * \ref CborParserOperations methods. + * + * \param dst The buffer the read bytes will be copied to. + * + * \param offset The starting position for the read relative to the + * current read position. + * + * \param len The number of bytes sought. + * + * + * \var CborParserOperations::advance_bytes + * + * Skips past \a len bytes from the reader without reading them. The read + * pointer is advanced in the process. + * + * \param token An opaque object passed to \ref cbor_parser_init_reader + * that may be used to pass context information between the + * \ref CborParserOperations methods. + * + * \param len The number of bytes skipped. + * + * + * \var CborParserOperations::transfer_string + * + * Overwrite the user-supplied pointer \a userptr with the address where the + * data indicated by \a offset is located, then advance the read pointer + * \a len bytes beyond that point. + * + * This routine is used for accessing strings embedded in CBOR documents + * (both text and binary strings). + * + * \param token An opaque object passed to \ref cbor_parser_init_reader + * that may be used to pass context information between the + * \ref CborParserOperations methods. + * + * \param userptr The pointer that will be updated to reference the location + * of the data in the buffer. + * + * \param offset The starting position for the read relative to the + * current read position. + * + * \param len The number of bytes sought. + */ + + static uint64_t extract_number_and_advance(CborValue *it) { /* This function is only called after we've verified that the number From a02319b0e01b0b7fce725c5cb644b3297ab260fc Mon Sep 17 00:00:00 2001 From: Stuart Longland Date: Wed, 8 Sep 2021 08:11:20 +1000 Subject: [PATCH 5/6] cbor.h, cborencoder.c: Migrate documentation for encoder functions --- src/cbor.h | 13 ------------- src/cborencoder.c | 17 +++++++++++++++++ 2 files changed, 17 insertions(+), 13 deletions(-) diff --git a/src/cbor.h b/src/cbor.h index 1ccf974f..6d34847a 100644 --- a/src/cbor.h +++ b/src/cbor.h @@ -214,19 +214,6 @@ typedef enum CborEncoderAppendType CborEncoderAppendRawData = 2 } CborEncoderAppendType; -/** - * Writer interface call-back function. When there is data to be written to - * the CBOR document, this routine will be called. The \a token parameter is - * taken from the \a token argument provided to \ref cbor_encoder_init_writer - * and may be used in any way the writer function sees fit. - * - * The \a data parameter contains a pointer to the raw bytes to be copied to - * the output buffer, with \a len specifying how long the payload is, which - * can be as small as a single byte or an entire (byte or text) string. - * - * The \a append parameter informs the writer function whether it is writing - * a string or general CBOR data. - */ typedef CborError (*CborEncoderWriteFunction)(void *token, const void *data, size_t len, CborEncoderAppendType append); enum CborEncoderFlags diff --git a/src/cborencoder.c b/src/cborencoder.c index b21c1da8..0f4bf03e 100644 --- a/src/cborencoder.c +++ b/src/cborencoder.c @@ -187,6 +187,23 @@ * Structure used to encode to CBOR. */ +/** + * \file cbor.h + * \typedef CborEncoderWriteFunction + * + * Writer interface call-back function. When there is data to be written to + * the CBOR document, this routine will be called. The \a token parameter is + * taken from the \a token argument provided to \ref cbor_encoder_init_writer + * and may be used in any way the writer function sees fit. + * + * The \a data parameter contains a pointer to the raw bytes to be copied to + * the output buffer, with \a len specifying how long the payload is, which + * can be as small as a single byte or an entire (byte or text) string. + * + * The \a append parameter informs the writer function whether it is writing + * a string or general CBOR data. + */ + /** * Initializes a CborEncoder structure \a encoder by pointing it to buffer \a * buffer of size \a size. The \a flags field is currently unused and must be From 929920423439790e8511b3e241e7b473b4209a2b Mon Sep 17 00:00:00 2001 From: Stuart Longland Date: Sat, 25 Apr 2026 10:42:10 +1000 Subject: [PATCH 6/6] cbor.h: Remove empty whitespace These crept in after documentation was added then subsequently removed. --- src/cbor.h | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/cbor.h b/src/cbor.h index 6d34847a..5d28314e 100644 --- a/src/cbor.h +++ b/src/cbor.h @@ -319,8 +319,6 @@ enum CborParserIteratorFlags }; struct CborValue; - - struct CborParserOperations { bool (*can_read_bytes)(void *token, size_t len);