forked from boostorg/beast
146 lines
4.3 KiB
Plaintext
146 lines
4.3 KiB
Plaintext
[/
|
|
Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com)
|
|
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
]
|
|
|
|
[section:BodyWriter 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:
|
|
|
|
* Storing a body in a dynamic buffer
|
|
* Storing a body in a user defined container with a custom allocator
|
|
* Transformation of incoming body data before storage, for example
|
|
to compress it first.
|
|
* Saving body data to a file
|
|
|
|
In the table below:
|
|
|
|
* `X` denotes a type meeting the requirements of [*BodyWriter].
|
|
|
|
* `B` denotes a __Body__ where
|
|
`std::is_same<X, B::writer>::value == true`.
|
|
|
|
* `a` denotes a value of type `X`.
|
|
|
|
* `length` is a value of type `boost::optional<std::uint64_t>`.
|
|
|
|
* `b` is an object whose type meets the requirements of __ConstBufferSequence__
|
|
|
|
* `m` denotes a value of type `message&` where
|
|
`std::is_same<decltype(m.body), Body::value_type>::value == true`.
|
|
|
|
* `ec` is a value of type [link beast.ref.beast__error_code `error_code&`].
|
|
|
|
[table Writer requirements
|
|
[[expression] [type] [semantics, pre/post-conditions]]
|
|
[
|
|
[`X(m);`]
|
|
[]
|
|
[
|
|
Constructible from `m`. The lifetime of `m` is guaranteed
|
|
to end no earlier than after the `X` is destroyed. The constructor
|
|
will be called the complete header is stored in `m`, and before
|
|
parsing body octets for messages indicating that a body is present.
|
|
]
|
|
][
|
|
[`a.init(length,ec)`]
|
|
[]
|
|
[
|
|
This function is called after construction and before any body
|
|
octets are presented to the writer. The value of `length` will
|
|
be set to the content length of the body if known, otherwise
|
|
`length` 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)`]
|
|
[]
|
|
[
|
|
This function is called to append the buffers specified by `b`
|
|
into the body representation.
|
|
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`.
|
|
]
|
|
]
|
|
]
|
|
|
|
[note
|
|
Definitions for required [*BodyReader] member functions may
|
|
be declared inline so the generated code can become part of
|
|
the implementation.
|
|
]
|
|
|
|
Exemplar:
|
|
```
|
|
struct writer
|
|
{
|
|
/** Construct the writer.
|
|
|
|
@param msg The message whose body is to be stored.
|
|
*/
|
|
template<bool isRequest, class Body, class Fields>
|
|
explicit
|
|
writer(message<isRequest, Body, Fields>& msg);
|
|
|
|
/** Initialization.
|
|
|
|
Called once immediately before storing any buffers.
|
|
|
|
@param content_length The content length if known, else `boost::none`.
|
|
|
|
@param ec Set to the error, if any occurred.
|
|
*/
|
|
void
|
|
init(boost::optional<std::uint64_t> content_length, error_code& ec)
|
|
{
|
|
// The specification requires this to indicate "no error"
|
|
ec = {};
|
|
}
|
|
|
|
/** 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.
|
|
*/
|
|
template<class ConstBufferSequence>
|
|
void
|
|
put(ConstBufferSequence const& buffers, error_code& ec);
|
|
|
|
/** Called when the body is complete.
|
|
|
|
@param ec Set to the error, if any occurred.
|
|
*/
|
|
void
|
|
finish(error_code& ec);
|
|
};
|
|
```
|
|
|
|
[endsect]
|