125 lines
4.7 KiB
Plaintext
125 lines
4.7 KiB
Plaintext
[/
|
|
Copyright (c) 2016-2019 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)
|
|
|
|
Official repository: https://github.com/boostorg/beast
|
|
]
|
|
|
|
[section:BodyWriter BodyWriter]
|
|
|
|
A [*BodyWriter] provides an
|
|
[@https://en.wikipedia.org/wiki/Online_algorithm online algorithm]
|
|
to obtain a sequence of zero
|
|
or more buffers from a body during serialization. The implementation creates
|
|
an instance of this type when needed, and calls into it one or more times to
|
|
retrieve buffers holding body octets. The interface of [*BodyWriter] is
|
|
intended to obtain buffers for these scenarios:
|
|
|
|
* A body that does not entirely fit in memory.
|
|
* A body produced incrementally from coroutine output.
|
|
* A body represented by zero or more buffers already in memory.
|
|
* A body whose size is not known ahead of time.
|
|
* Body data generated dynamically from other threads.
|
|
* Body data computed algorithmically.
|
|
|
|
[heading Associated Types]
|
|
|
|
* [link beast.ref.boost__beast__http__is_body_writer `is_body_writer`]
|
|
* __Body__
|
|
|
|
[heading Requirements]
|
|
|
|
[warning
|
|
These requirements may undergo non-backward compatible
|
|
changes in subsequent versions.
|
|
]
|
|
|
|
In this table:
|
|
|
|
* `W` denotes a type meeting the requirements of [*BodyWriter].
|
|
* `B` denotes a __Body__ where
|
|
`std::is_same<W, B::writer>::value == true`.
|
|
* `a` denotes a value of type `W`.
|
|
* `h` denotes a const value of type `header<isRequest, Fields> const&`.
|
|
* `v` denotes a possibly const value of type `Body::value_type&`.
|
|
* `ec` is a value of type [link beast.ref.boost__beast__error_code `error_code&`].
|
|
* `W<T>` is the type `boost::optional<std::pair<T, bool>>`.
|
|
|
|
[table Valid expressions
|
|
[[Expression] [Type] [Semantics, Pre/Post-conditions]]
|
|
[
|
|
[`W::const_buffers_type`]
|
|
[]
|
|
[
|
|
A type which meets the requirements of __ConstBufferSequence__.
|
|
This is the type of buffer returned by `W::get`.
|
|
]
|
|
][
|
|
[`W{h,v};`]
|
|
[]
|
|
[
|
|
Constructible from `h` and `v`. The lifetime of `h` and `v`
|
|
are guaranteed to end no earlier than after the `W` is destroyed.
|
|
The writer shall not access the contents of `h` or `v` before
|
|
the first call to `init`, permitting lazy construction of the
|
|
message.
|
|
|
|
The constructor may optionally require that `h` and `v` are
|
|
`const` references, with these consequences:
|
|
|
|
* If `W` requires that `h` and `v` are const references, then
|
|
the corresponding serializer constructors for messages with this
|
|
body type will will accept a const reference to a message,
|
|
otherwise:
|
|
|
|
* If `W` requires that `h` and `v` are non-const references,
|
|
then the corresponding serializer constructors for messages with
|
|
this body type will require a non-const reference to a message.
|
|
]
|
|
][
|
|
[`a.init(ec)`]
|
|
[]
|
|
[
|
|
Called once to fully initialize the object before any calls to
|
|
`get`. The message body becomes valid before entering this function,
|
|
and remains valid until the writer is destroyed.
|
|
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.get(ec)`]
|
|
[`W<W::const_buffers_type>`]
|
|
[
|
|
Called one or more times after `init` succeeds. This function
|
|
returns `boost::none` if all buffers representing the body have
|
|
been returned in previous calls or if it sets `ec` to indicate an
|
|
error. Otherwise, if there are buffers remaining the function
|
|
should return a pair with the first element containing a non-zero
|
|
length buffer sequence representing the next set of octets in
|
|
the body, while the second element is a `bool` meaning `true`
|
|
if there may be additional buffers returned on a subsequent call,
|
|
or `false` if the buffer returned on this call is the last
|
|
buffer representing the body.
|
|
The function will ensure that `!ec` is `true` if there was
|
|
no error or set to the appropriate error code if there was one.
|
|
]
|
|
]]
|
|
|
|
[heading Exemplar]
|
|
|
|
[concept_BodyWriter]
|
|
|
|
[heading Models]
|
|
|
|
* [link beast.ref.boost__beast__http__basic_dynamic_body.writer `basic_dynamic_body::writer`]
|
|
* [link beast.ref.boost__beast__http__basic_file_body__writer `basic_file_body::writer`]
|
|
* [link beast.ref.boost__beast__http__basic_string_body.writer `basic_string_body::writer`]
|
|
* [link beast.ref.boost__beast__http__buffer_body.writer `buffer_body::writer`]
|
|
* [link beast.ref.boost__beast__http__empty_body.writer `empty_body::writer`]
|
|
* [link beast.ref.boost__beast__http__span_body.writer `span_body::writer`]
|
|
* [link beast.ref.boost__beast__http__vector_body.writer `vector_body::writer`]
|
|
|
|
[endsect]
|