123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124 |
- [/
- 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]
|