Document the abstract reader/writer interface

src/cbor.h

@@ -214,7 +214,7 @@ typedef enum CborEncoderAppendType
     CborEncoderAppendRawData = 2
 } CborEncoderAppendType;
 
-typedef CborError (*CborEncoderWriteFunction)(void *, const void *, size_t, CborEncoderAppendType);
+typedef CborError (*CborEncoderWriteFunction)(void *token, const void *data, size_t len, CborEncoderAppendType append);
 
 enum CborEncoderFlags
 {

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

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
@@ -345,6 +422,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));