Beast Logo

PrevUpHomeNext

Writer requirements

A Writer serializes the message body. The implementation creates an instance of this type when serializing a message, and calls into it zero or more times to provide buffers containing the data. The interface of Writer is intended to allow serialization in these scenarios:

In this table:

Table 9. Writer requirements

operation

type

semantics, pre/post-conditions

X a(m);

a is constructible from m. The lifetime of m is guaranteed to end no earlier than after a is destroyed. This function must be noexcept.

a.init(ec)

void

Called immediately after construction. If the function sets an error code in ec, the serialization is aborted and the error is propagated to the caller. This function must be noexcept.

a.content_length()

std::uint64_t

If this member is present, it is called after initialization and before calls to provide buffers. The serialized message will have the Content-Length field set to the value returned from this function. If this member is absent, the serialized message body will be chunk-encoded for HTTP versions 1.1 and later, else the serialized message body will be sent unmodified, with the error boost::asio::error::eof returned to the caller, to notify they should close the connection to indicate the end of the message. This function must be noexcept.

a.write(ec, wf)

bool

Called repeatedly after init succeeds. wf is a function object which takes as its single parameter any value meeting the requirements of ConstBufferSequence. Buffers provided to this write function must remain valid until the next member function of writer is invoked (which may be the destructor). This function returns true to indicate all message body data has been written, or false if there is more body data.


[Note] Note

Definitions for required Writer member functions should be declared inline so the generated code can become part of the implementation.

Exemplar:

struct writer
{
public:
    /** Construct the writer.

        The msg object is guaranteed to exist for the lifetime of the writer.

        Exceptions:
            No-throw guarantee.

        @param msg The message whose body is to be written.
    */
    template<bool isRequest, class Body, class Headers>
    explicit
    writer(message<isRequest, Body, Headers> const& msg) noexcept;

    /** Initialize the writer.

        Called once immediately after construction.
        The writer can perform initialization which may fail.

        @param ec Contains the error code if any errors occur.
    */
    void
    init(error_code& ec) noexcept;

    /** Returns the content length.

        If this member is present, the implementation will set the
        Content-Length field accordingly. If absent, the implementation will
        use chunk-encoding or terminate the connection to indicate the end
        of the message.
    */
    std::uint64_t
    content_length() noexcept;

    /** Write zero or one buffer representing the message body.

        Postconditions:

            If return value is `true`:
                * Callee made zero or one calls to `write`.
                * There is no more data remaining to write.

            If return value is `false`:
                * Callee does not take ownership of resume.
                * Callee made one call to `write`.

        @param ec Set to indicate an error. This will cause an
        asynchronous write operation to complete with the error.

        @param write A functor the writer will call to provide the next
        set of buffers. Ownership of the buffers is not transferred,
        the writer must guarantee that the buffers remain valid until the
        next member function is invoked, which may be the destructor.

        @return `true` if there is no more data to send,
                `false` when there may be more data.
    */
    template<class WriteFunction>
    bool
    write(
        error_code&,
        WriteFunction&& wf) noexcept;
};

PrevUpHomeNext