Improve cbor_stream_decode interface

CHANGELOG.md

@@ -3,6 +3,9 @@ Next
 - BUILD BREAKING: Use BUILD_SHARED_LIBS to determine how to build libraries (fixed Windows linkage) [[#148]](https://github.com/PJK/libcbor/pull/148) (by [intelligide@](https://github.com/intelligide))
 - BREAKING: Fix `cbor_tag_item` not increasing the reference count on the tagged item reference it returns [[Fixes #109](https://github.com/PJK/libcbor/issues/109)] (discovered bt [JohnGilmour](https://github.com/JohnGilmour))
   - If you have previously relied on the broken behavior, you can use `cbor_move` to emulate as long as the returned handle is an "rvalue"
+- BREAKING: [`CBOR_DECODER_EBUFFER` removed from `cbor_decoder_status`](https://github.com/PJK/libcbor/pull/156)
+    - `cbor_stream_decode` will set `CBOR_DECODER_NEDATA` instead if the input buffer is empty
+- [Fix `cbor_stream_decode`](https://github.com/PJK/libcbor/pull/156) to set `cbor_decoder_result.required` to the minimum number of input bytes necessary to receive the next callback (as long as at least one byte was passed) (discovered by [woefulwabbit](https://github.com/woefulwabbit))
 
 0.7.0 (2020-04-25)
 ---------------------

src/cbor.c

@@ -82,8 +82,6 @@ cbor_item_t *cbor_load(cbor_data source, size_t source_size,
           result->error.code = CBOR_ERR_NOTENOUGHDATA;
           goto error;
         }
-      case CBOR_DECODER_EBUFFER:
-        /* Fallthrough */
       case CBOR_DECODER_ERROR:
         /* Reserved/malformated item */
         {

src/cbor/data.h

@@ -199,29 +199,52 @@ struct cbor_pair {
 struct cbor_load_result {
   /** Error indicator */
   struct cbor_error error;
-  /** Number of bytes read*/
+  /** Number of bytes read */
   size_t read;
 };
 
 /** Streaming decoder result - status */
 enum cbor_decoder_status {
-  CBOR_DECODER_FINISHED /** OK, finished */
-  ,
-  CBOR_DECODER_NEDATA /** Not enough data - mismatch with MTB */
-  ,
-  CBOR_DECODER_EBUFFER /** Buffer manipulation problem */
-  ,
-  CBOR_DECODER_ERROR /** Malformed or reserved MTB/value */
+  /** Decoding finished successfully (a callback has been invoked)
+   *
+   * Note that this does *not* mean that the buffer has been fully decoded;
+   * there may still be unread bytes for which no callback has been involved.
+   */
+  CBOR_DECODER_FINISHED,
+  /** Not enough data to invoke a callback */
+  CBOR_DECODER_NEDATA,
+  /** Bad data (reserved MTB, malformed value, etc.)  */
+  CBOR_DECODER_ERROR
 };
 
 /** Streaming decoder result */
 struct cbor_decoder_result {
-  /** Bytes read */
+  /** Input bytes read/consumed
+   *
+   * If this is less than the size of input buffer, the client will likely
+   * resume parsing starting at the next byte (e.g. `buffer + result.read`).
+   *
+   * Set to 0 if the #status is not #CBOR_DECODER_FINISHED.
+   */
   size_t read;
-  /** The result */
+
+  /** The decoding status */
   enum cbor_decoder_status status;
-  /** When status == CBOR_DECODER_NEDATA,
-   *  the minimum number of bytes required to continue parsing */
+
+  /** Number of bytes in the input buffer needed to resume parsing
+   *
+   * Set to 0 unless the result status is #CBOR_DECODER_NEDATA. If it is, then:
+   *  - If at least one byte was passed, #required will be set to the minimum
+   *    number of bytes needed to invoke a decoded callback on the current
+   *    prefix.
+   *
+   *    For example: Attempting to decode a 1B buffer containing `0x19` will
+   *    set #required to 3 as `0x19` signals a 2B integer item, so we need at
+   *    least 3B to continue (the `0x19` MTB byte and two bytes of data needed
+   *    to invoke #cbor_callbacks.uint16).
+   *
+   *  - If there was no data at all, #read will always be set to 1
+   */
   size_t required;
 };