120 lines
4.3 KiB
Plaintext
120 lines
4.3 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:BodyReader BodyReader]
|
|
|
|
A [*BodyReader] 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 [*BodyReader]
|
|
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
|
|
|
|
[heading Associated Types]
|
|
|
|
* [link beast.ref.boost__beast__http__is_body_reader `is_body_reader`]
|
|
* __Body__
|
|
|
|
[heading Requirements]
|
|
|
|
[warning
|
|
These requirements may undergo non-backward compatible
|
|
changes in subsequent versions.
|
|
]
|
|
|
|
In this table:
|
|
|
|
* `R` denotes a type meeting the requirements of [*BodyReader].
|
|
* `B` denotes a __Body__ where
|
|
`std::is_same<R, B::reader>::value == true`.
|
|
* `a` denotes a value of type `R`.
|
|
* `b` is an object whose type meets the requirements of __ConstBufferSequence__
|
|
* `h` denotes a value of type `header<isRequest, Fields>&`.
|
|
* `v` denotes a value of type `Body::value_type&`.
|
|
* `n` is a value of type `boost::optional<std::uint64_t>`.
|
|
* `ec` is a value of type [link beast.ref.boost__beast__error_code `error_code&`].
|
|
|
|
[table Valid expressions
|
|
[[Expression] [Type] [Semantics, Pre/Post-conditions]]
|
|
[
|
|
[`R{h,v};`]
|
|
[]
|
|
[
|
|
Constructible from `h` and `v`. The lifetime of `h` and `v`
|
|
is guaranteed to end no earlier than after the `R` is destroyed.
|
|
The reader shall not access the contents of `h` or `v` before
|
|
the first call to `init`, permitting lazy construction of the
|
|
message.
|
|
]
|
|
][
|
|
[`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 reader 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 [*BodyReader] 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_reader<B>`]
|
|
[`std::true_type`]
|
|
[
|
|
An alias for `std::true_type` for `B`, otherwise an alias
|
|
for `std::false_type`.
|
|
]
|
|
]]
|
|
|
|
[heading Exemplar]
|
|
|
|
[concept_BodyReader]
|
|
|
|
[heading Models]
|
|
|
|
* [link beast.ref.boost__beast__http__basic_dynamic_body.reader `basic_dynamic_body::reader`]
|
|
* [link beast.ref.boost__beast__http__basic_file_body__reader `basic_file_body::reader`]
|
|
* [link beast.ref.boost__beast__http__basic_string_body.reader `basic_string_body::reader`]
|
|
* [link beast.ref.boost__beast__http__buffer_body.reader `buffer_body::reader`]
|
|
* [link beast.ref.boost__beast__http__empty_body.reader `empty_body::reader`]
|
|
* [link beast.ref.boost__beast__http__span_body.reader `span_body::reader`]
|
|
* [link beast.ref.boost__beast__http__vector_body.reader `vector_body::reader`]
|
|
|
|
[endsect]
|