[/
    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] 提供一种在线算法，用于将包含已解析消息体八位字节的零个或多个缓冲区序列传输到消息容器中。__parser__ 在需要时创建该类型的实例，并零次或多次调用它以传输缓冲区。[*BodyReader] 的接口设计用于允许将缓冲区转换为这些表示形式的场景：

* 将消息体存储在动态缓冲区中
* 将消息体存储在使用自定义分配器的用户定义容器中
* 在存储前对传入的消息体数据进行转换，例如：
  to compress it first.
* 将消息体数据保存到文件

[heading 关联类型]

* [link beast.ref.boost__beast__http__is_body_reader `is_body_reader`]
* __Body__

[heading 要求]

[warning
    这些要求可能发生不向后兼容的变更
    changes in subsequent versions.
]

在下表中：

R 表示满足 [*BodyReader] 要求的类型。

B 表示一个 Body 类型，其中
      `std::is_same<R, B::reader>::value == true`.
* `a` 表示类型为 `R` 的值。
* `b` 是一个类型满足 __ConstBufferSequence__ 要求的对象。
* `h` 表示类型为 `header<isRequest, Fields>&` 的值。
* `v` 表示类型为 `Body::value_type&` 的值。
* `n` 表示类型为 `boost::optional<std::uint64_t>` 的值。
* `ec` 表示类型为 [link beast.ref.boost__beast__error_code `error_code&`] 的值。

[table 有效表达式
[[表达式] [类型] [语义、前置条件与后置条件]]
[
    [`R{h,v};`]
    []
    [可从 `h` 和 `v` 构造。`h` 和 `v` 的生命周期保证不早于 `R` 销毁前结束。读取器在首次调用 `init` 之前不应访问 `h` 或 `v` 的内容，以支持消息的延迟构造。]
][
    [`a.init(n, ec)`]
    []
    [在调用 put 之前调用一次，以完全初始化对象。消息体在进入该函数前有效，并持续有效直到读取器销毁为止。n 的值在已知时表示消息体的内容长度，否则为 boost::none。[*BodyReader] 的实现可使用此信息优化内存分配。

该函数在无错误时确保 !ec 为 true，否则将 ec 设置为对应的错误码。]
][
    [`a.put(b,ec)`]
    [`std::size_t`]
    [调用此函数以将 `b` 指定的部分或全部缓冲区追加到消息体表示中。返回从 `b` 插入的字节数。如果插入的字节数少于输入总量，剩余部分将在下一次调用 `put` 时传入。该函数在无错误时确保 `!ec` 为 `true`，否则将 `ec` 设置为对应的错误码。]
][
    [`a.finish(ec)`]
    []
    [该函数在无更多消息体八位字节时调用。该函数在无错误时确保 `!ec` 为 `true`，否则将 `ec` 设置为对应的错误码。]
][
    [`is_body_reader<B>`]
    [`std::true_type`]
    [若 `B` 存在，则为 `std::true_type` 的别名，否则为 `std::false_type` 的别名。]
]]

[heading 示例]

[concept_BodyReader]

[heading 模型]

* [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]