Beast Logo

PrevUpHomeNext

BodyWriter

A BodyWriter provides an online algorithm to transfer a series of zero or more buffers containing parsed body octets into a message container. The parser creates an instance of this type when needed, and calls into it zero or more times to transfer buffers. The interface of BodyWriter is intended to allow the conversion of buffers into these scenarios for representation:

Associated Types
Requirements

In this table:

Table 32. Valid expressions

Expression

Type

Semantics, Pre/Post-conditions

W(m);

Constructible from m. The lifetime of m is guaranteed to end no earlier than after the W is destroyed. The constructor will be called after a complete header is stored in m, and before parsing body octets for messages indicating that a body is present The writer shall not access the contents of m before the first call to init, permitting lazy construction of the message.

The function will ensure that !ec is true if there was no error or set to the appropriate error code if there was one.

a.init(n, ec)

Called once to fully initialize the object before any calls to put. The message body is valid before entering this function, and remains valid until the writer is destroyed. The value of n will be set to the content length of the body if known, otherwise n will be equal to boost::none. Implementations of BodyWriter may use this information to optimize allocation.

The function will ensure that !ec is true if there was no error or set to the appropriate error code if there was one.

a.put(b,ec)

std::size_t

This function is called to append some or all of the buffers specified by b into the body representation. The number of bytes inserted from b is returned. If the number of bytes inserted is less than the total input, the remainder of the input will be presented in the next call to put. The function will ensure that !ec is true if there was no error or set to the appropriate error code if there was one.

a.finish(ec)

This function is called when no more body octets are remaining. The function will ensure that !ec is true if there was no error or set to the appropriate error code if there was one.

is_body_writer<B>

std::true_type

An alias for std::true_type for B, otherwise an alias for std::false_type.


Exemplar
struct BodyWriter
{
    /** Construct the writer.

        @param msg The message whose body is to be stored.
    */
    template<bool isRequest, class Body, class Fields>
    explicit
    BodyWriter(message<isRequest, Body, Fields>& msg);

    /** Initialize the writer

        This is called after construction and before the first
        call to `put`. The message is valid and complete upon
        entry.

        @param ec Set to the error, if any occurred.
    */
    void
    init(
        boost::optional<std::uint64_t> const& content_length,
        error_code& ec)
    {
        boost::ignore_unused(content_length);

        // The specification requires this to indicate "no error"
        ec.assign(0, ec.category());
    }

    /** Store buffers.

        This is called zero or more times with parsed body octets.

        @param buffers The constant buffer sequence to store.

        @param ec Set to the error, if any occurred.

        @return The number of bytes transferred from the input buffers.
    */
    template<class ConstBufferSequence>
    std::size_t
    put(ConstBufferSequence const& buffers, error_code& ec)
    {
        // The specification requires this to indicate "no error"
        ec = {};

        return boost::asio::buffer_size(buffers);
    }

    /** Called when the body is complete.

        @param ec Set to the error, if any occurred.
    */
    void
    finish(error_code& ec)
    {
        // The specification requires this to indicate "no error"
        ec = {};
    }
};
Models

PrevUpHomeNext