Return std::size_t from Body::writer::put (API Change)

`put` returns the number of bytes actually transferred
from the input buffers.

Actions Required:

* Return the number of bytes actually transferred from the
  input buffers in user defined `Body::writer::put` functions.

example/common/file_body.hpp

@@ -255,7 +255,7 @@ public:
     // buffer sequences corresponding to the incoming body.
     //
     template<class ConstBufferSequence>
-    void
+    std::size_t
     put(ConstBufferSequence const& buffers, beast::error_code& ec);
 
     // This function is called when writing is complete.
@@ -307,16 +307,20 @@ writer(beast::http::message<isRequest, file_body, Fields>& m,
 // This will get called one or more times with body buffers
 //
 template<class ConstBufferSequence>
-void
+std::size_t
 file_body::writer::
 put(ConstBufferSequence const& buffers, beast::error_code& ec)
 {
+    // This function must return the total number of
+    // bytes transferred from the input buffers.
+    std::size_t bytes_transferred = 0;
+
     // Loop over all the buffers in the sequence,
     // and write each one to the file.
     for(boost::asio::const_buffer buffer : buffers)
     {
         // Write this buffer to the file
-        fwrite(
+        bytes_transferred += fwrite(
             boost::asio::buffer_cast<void const*>(buffer), 1,
             boost::asio::buffer_size(buffer),
             file_);
@@ -327,12 +331,14 @@ put(ConstBufferSequence const& buffers, beast::error_code& ec)
             // Convert the old-school `errno` into
             // an error code using the generic category.
             ec = beast::error_code{errno, beast::generic_category()};
-            return;
+            return bytes_transferred;
         }
     }
 
     // Indicate success
     ec = {};
+
+    return bytes_transferred;
 }
 
 // Called after writing is done when there's no error.

example/common/mutable_body.hpp

@@ -120,7 +120,7 @@ struct mutable_body
         }
 
         template<class ConstBufferSequence>
-        void
+        std::size_t
         put(ConstBufferSequence const& buffers,
                 beast::error_code& ec)
         {
@@ -135,10 +135,10 @@ struct mutable_body
             catch(std::length_error const&)
             {
                 ec = beast::http::error::buffer_overflow;
-                return;
+                return 0;
             }
             ec.assign(0, ec.category());
-            buffer_copy(boost::asio::buffer(
+            return buffer_copy(boost::asio::buffer(
                 &body_[0] + len, n), buffers);
         }
 

example/doc/http_examples.hpp

@@ -6,6 +6,7 @@
 //
 
 #include <beast.hpp>
+#include <iostream>
 
 /*  This file contains the functions and classes found in the documentation
 
@@ -917,12 +918,15 @@ class custom_parser
         content_length,         // Content length if known, else `boost::none`
         error_code& ec);        // The error returned to the caller, if any
 
-    /// Called for each piece of the body, if a body exists.
-    //
-    //  If present, the chunked Transfer-Encoding will be removed
-    //  before this callback is invoked.
-    //
-    void
+    /** Called for each piece of the body, if a body exists.
+      
+        If present, the chunked Transfer-Encoding will be removed
+        before this callback is invoked. The function returns
+        the number of bytes consumed from the input buffer.
+        Any input octets not consumed will be will be presented
+        on subsequent calls.
+    */
+    std::size_t
     on_data(
         string_view s,          // A portion of the body
         error_code& ec);        // The error returned to the caller, if any
@@ -990,11 +994,12 @@ on_body(boost::optional<std::uint64_t> const& content_length,
 }
 
 template<bool isRequest>
-void custom_parser<isRequest>::
+std::size_t custom_parser<isRequest>::
 on_data(string_view s, error_code& ec)
 {
     boost::ignore_unused(s);
     ec = {};
+    return s.size();
 }
 
 template<bool isRequest>
@@ -1013,5 +1018,47 @@ on_complete(error_code& ec)
     ec = {};
 }
 
+//------------------------------------------------------------------------------
+//
+// Example: Incremental Read
+//
+//------------------------------------------------------------------------------
+
+//[example_incremental_read
+
+/*  This function reads a message using a fixed size buffer to hold
+    portions of the body, and prints the body contents to a `std::ostream`.
+*/
+template<
+    bool isRequest,
+    class SyncReadStream,
+    class DynamicBuffer>
+void
+read_and_print_body(
+    std::ostream& os,
+    SyncReadStream& stream,
+    DynamicBuffer& buffer,
+    error_code& ec)
+{
+    parser<isRequest, buffer_body> p;
+    read_header(stream, buffer, p, ec);
+    if(ec)
+        return;
+    while(! p.is_done())
+    {
+        char buf[512];
+        p.get().body.data = buf;
+        p.get().body.size = sizeof(buf);
+        read(stream, buffer, p, ec);
+        if(ec == error::need_buffer)
+            ec.assign(0, ec.category());
+        if(ec)
+            return;
+        os.write(buf, sizeof(buf) - p.get().body.size);
+    }
+}
+
+//]
+
 } // http
 } // beast