| Home | Libraries | People | FAQ | More

#### buffered_read_stream

A Stream with attached DynamicBuffer to buffer reads.

##### Synopsis

Defined in header `<boost/beast/core/buffered_read_stream.hpp>`

    template<
        class Stream,
        class DynamicBuffer>
    class buffered_read_stream

##### Types

Name | Description
--- | ---
buffer_type | The type of the internal buffer.
lowest_layer_type | The type of the lowest layer.
next_layer_type | The type of the next layer.

##### Member Functions

Name | Description
--- | ---
async_read_some | Start an asynchronous read.
async_write_some | Start an asynchronous write.
buffer | Access the internal buffer.
buffered_read_stream | Move constructor. Construct the wrapping stream.
capacity | Set the maximum buffer size.
get_executor | Get the executor associated with the object.
lowest_layer | Get a reference to the lowest layer. Get a const reference to the lowest layer.
next_layer | Get a reference to the next layer. Get a const reference to the next layer.
operator= | Move assignment.
read_some | Read some data from the stream.
write_some | Write some data to the stream.

##### Description

This wraps a Stream implementation so that calls to write are passed through to the underlying stream, while calls to read will first consume the input sequence stored in a DynamicBuffer which is part of the object.

The use-case for this class is different than that of the `boost::asio::buffered_readstream`. It is designed to facilitate the use of `boost::asio::read_until`, and to allow buffers acquired during detection of handshakes to be made transparently available to callers. A hypothetical implementation of the buffered version of `boost::asio::ssl::stream::async_handshake` could make use of this wrapper.

Uses:

- Transparently leave untouched input acquired in calls to `boost::asio::read_until` behind for subsequent callers.
- "Preload" a stream with handshake input data acquired from other sources.

Example:

    // Process the next HTTP header on the stream,
    // leaving excess bytes behind for the next call.
    //
    template<class DynamicBuffer>
    void process_http_message(
        buffered_read_stream<DynamicBuffer>& stream)
    {
        // Read up to and including the end of the HTTP
        // header, leaving the sequence in the stream's
        // buffer. read_until may read past the end of the
        // headers; the return value will include only the
        // part up to the end of the delimiter.
        //
        std::size_t bytes_transferred =
            boost::asio::read_until(
                stream.next_layer(), stream.buffer(), "\r\n\r\n");

        // Use buffers_prefix() to limit the input
        // sequence to only the data up to and including
        // the trailing "\r\n\r\n".
        //
        auto header_buffers = buffers_prefix(
            bytes_transferred, stream.buffer().data());

        ...

        // Discard the portion of the input corresponding
        // to the HTTP headers.
        //
        stream.buffer().consume(bytes_transferred);

        // Everything we read from the stream
        // is part of the content-body.
    }

##### Template Parameters

Type | Description
--- | ---
`Stream` | The type of stream to wrap.
`DynamicBuffer` | The type of stream buffer to use.

Convenience header `<boost/beast/core.hpp>`