Add read, async_read for message_headers:

fix #172, fix #173

This provides overloads of read and async_read to allow
reading message_headers objects.

include/beast/http/read.hpp

@@ -15,6 +15,144 @@
 namespace beast {
 namespace http {
 
+/** Read HTTP/1 message headers from a stream.
+
+    This function is used to synchronously read message headers from
+    the stream. The call blocks until one of the following conditions
+    is true:
+
+    @li The complete message headers are read in.
+
+    @li An error occurs in the stream or parser.
+
+    This function is implemented in terms of one or more calls
+    to the stream's `read_some` function. The implementation may
+    read additional octets that lie past the end of the message
+    headers being parsed. This additional data is stored in the
+    stream buffer, which may be used in subsequent calls.
+
+    @param stream The stream from which the data is to be read.
+    The type must support the @b `SyncReadStream` concept.
+
+    @param dynabuf A @b `DynamicBuffer` holding additional bytes
+    read by the implementation from the stream. This is both
+    an input and an output parameter; on entry, any data in the
+    stream buffer's input sequence will be given to the parser
+    first.
+
+    @param msg An object used to store the message headers.
+    Any contents will be overwritten. The type must support
+    copy assignment or move assignment.
+
+    @throws system_error Thrown on failure.
+*/
+template<class SyncReadStream, class DynamicBuffer,
+    bool isRequest, class Headers>
+void
+read(SyncReadStream& stream, DynamicBuffer& dynabuf,
+    message_headers<isRequest, Headers>& msg);
+
+/** Read HTTP/1 message headers from a stream.
+
+    This function is used to synchronously read message headers from
+    the stream. The call blocks until one of the following conditions
+    is true:
+
+    @li The complete message headers are read in.
+
+    @li An error occurs in the stream or parser.
+
+    This function is implemented in terms of one or more calls
+    to the stream's `read_some` function. The implementation may
+    read additional octets that lie past the end of the message
+    headers being parsed. This additional data is stored in the
+    stream buffer, which may be used in subsequent calls.
+
+    If the message being received contains a message body, it
+    is the callers responsibility to cause the body to be read
+    in before attempting to read the next message.
+
+    @param stream The stream from which the data is to be read.
+    The type must support the @b `SyncReadStream` concept.
+
+    @param dynabuf A @b `DynamicBuffer` holding additional bytes
+    read by the implementation from the stream. This is both
+    an input and an output parameter; on entry, any data in the
+    stream buffer's input sequence will be given to the parser
+    first.
+
+    @param msg An object used to store the message headers.
+    Any contents will be overwritten. The type must support
+    copy assignment or move assignment.
+
+    @param ec Set to the error, if any occurred.
+*/
+template<class SyncReadStream, class DynamicBuffer,
+    bool isRequest, class Headers>
+void
+read(SyncReadStream& stream, DynamicBuffer& dynabuf,
+    message_headers<isRequest, Headers>& msg,
+        error_code& ec);
+
+/** Start an asynchronous operation to read HTTP/1 message headers from a stream.
+
+    This function is used to asynchronously read a message from the
+    stream. The function call always returns immediately. The asynchronous
+    operation will continue until one of the following conditions is true:
+
+    @li A complete message is read in.
+
+    @li An error occurs in the stream or parser.
+
+    This operation is implemented in terms of one or more calls to
+    the next layer's `async_read_some` function, and is known as a
+    <em>composed operation</em>. The program must ensure that the
+    stream performs no other operations until this operation completes.
+    The implementation may read additional octets that lie past the
+    end of the message headers being parsed. This additional data is
+    stored in the stream buffer, which may be used in subsequent calls.
+
+    If the message being received contains a message body, it
+    is the callers responsibility to cause the body to be read
+    in before attempting to read the next message.
+
+    @param stream The stream to read the message from.
+    The type must support the @b `AsyncReadStream` concept.
+
+    @param dynabuf A @b `DynamicBuffer` holding additional bytes
+    read by the implementation from the stream. This is both
+    an input and an output parameter; on entry, any data in the
+    stream buffer's input sequence will be given to the parser
+    first.
+
+    @param msg An object used to store the message. Any contents
+    will be overwritten. The type must support copy assignment or
+    move assignment.
+
+    @param handler The handler to be called when the request completes.
+    Copies will be made of the handler as required. The equivalent
+    function signature of the handler must be:
+    @code void handler(
+        error_code const& error // result of operation
+    ); @endcode
+    Regardless of whether the asynchronous operation completes
+    immediately or not, the handler will not be invoked from within
+    this function. Invocation of the handler will be performed in a
+    manner equivalent to using `boost::asio::io_service::post`.
+*/
+template<class AsyncReadStream, class DynamicBuffer,
+    bool isRequest, class Body, class Headers,
+        class ReadHandler>
+#if GENERATING_DOCS
+void_or_deduced
+#else
+typename async_completion<
+    ReadHandler, void(error_code)>::result_type
+#endif
+async_read(AsyncReadStream& stream, DynamicBuffer& dynabuf,
+    message_headers<isRequest, Headers>& msg,
+        ReadHandler&& handler);
+
 /** Read a HTTP/1 message from a stream.
 
     This function is used to synchronously read a message from
@@ -41,7 +179,8 @@ namespace http {
     first.
 
     @param msg An object used to store the message. Any
-    contents will be overwritten.
+    contents will be overwritten. The type must support
+    copy assignment or move assignment.
 
     @throws system_error Thrown on failure.
 */
@@ -77,7 +216,8 @@ read(SyncReadStream& stream, DynamicBuffer& dynabuf,
     first.
 
     @param msg An object used to store the message. Any
-    contents will be overwritten.
+    contents will be overwritten. The type must support
+    copy assignment or move assignment.
 
     @param ec Set to the error, if any occurred.
 */
@@ -98,10 +238,13 @@ read(SyncReadStream& stream, DynamicBuffer& dynabuf,
 
     @li An error occurs in the stream or parser.
 
-    This operation is implemented in terms of one or more calls to the
-    next layer's `async_read_some` function, and is known as a
-    <em>composed operation</em>. The program must ensure that the stream
-    performs no other operations until this operation completes.
+    This operation is implemented in terms of one or more calls to
+    the next layer's `async_read_some` function, and is known as a
+    <em>composed operation</em>. The program must ensure that the
+    stream performs no other operations until this operation completes.
+    The implementation may read additional octets that lie past the
+    end of the message being parsed. This additional data is stored
+    in the stream buffer, which may be used in subsequent calls.
 
     @param stream The stream to read the message from.
     The type must support the @b `AsyncReadStream` concept.
@@ -113,7 +256,8 @@ read(SyncReadStream& stream, DynamicBuffer& dynabuf,
     first.
 
     @param msg An object used to store the message. Any contents
-    will be overwritten.
+    will be overwritten. The type must support copy assignment or
+    move assignment.
 
     @param handler The handler to be called when the request completes.
     Copies will be made of the handler as required. The equivalent