[/
    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:using_http HTTP]

[warning
    像 Basic 这类更高层级的函数
    Authentication,  mime/multipart encoding, cookies, automatic handling
    of redirects, gzipped transfer encodings, caching, or proxying (to name
    a few) are not directly provided, but nothing stops users from creating
    these features using Beast's HTTP message types.
]

该库为程序员提供简洁高效的 HTTP 消息模型及其相关操作，包括使用 __Asio__ 对 HTTP/1 线路格式的消息进行同步、异步及面向缓冲区的解析与序列化。具体功能如下：

[variablelist
[
    [Message Containers]
    [
        Complete HTTP messages are modeled using the __message__ class,
        with possible user customizations.
    ]
][
    [Stream Reading]
    [[link beast.ref.boost__beast__http__read `read`]、[link beast.ref.boost__beast__http__read_header `read_header`]、[link beast.ref.boost__beast__http__read_some `read_some`]、[link beast.ref.boost__beast__http__async_read `async_read`]、[link beast.ref.boost__beast__http__async_read_header `async_read_header`] 以及 [link beast.ref.boost__beast__http__async_read_some `async_read_some`] 这些函数用于从 [link beast.concepts.streams 流] 中读取 HTTP/1 消息数据。
]
][
    [流式写入操作]
    [[link beast.ref.boost__beast__http__write `write`]、[link beast.ref.boost__beast__http__write_header `write_header`]、[link beast.ref.boost__beast__http__write_some `write_some`]、[link beast.ref.boost__beast__http__async_write `async_write`]、[link beast.ref.boost__beast__http__async_write_header `async_write_header`] 以及 [link beast.ref.boost__beast__http__async_write_some `async_write_some`] 这些函数用于将 HTTP/1 消息数据写入到 [link beast.concepts.streams 流] 中。]
][
    [序列化]
    [__serializer__ 用于生成与 __message__ 的 __rfc7230__ 线路表示形式相一致的八位字节缓冲区序列。]
][
    [解析]
    [__parser__ 用于尝试将一系列八位字节缓冲区转换为 __message__。]
]
]

操作 HTTP 消息的接口分为多个层次。最高层接口注重易用性，越往下层，提供的控制能力、可配置选项和灵活性就越强。最底层提供定制点，允许用户用自定义类型替换部分内部实现。各层组织方式如下：

[table
[[Level][Read/Write What][Description]]
[
    [[*6]]
    [__消息__][最顶层接口通过一次函数调用即可完成完整 HTTP 消息的发送或接收，旨在简化使用。相关函数包括：[link beast.ref.boost__beast__http__read.overload4 `read`]、[link beast.ref.boost__beast__http__write.overload4 `write`]、[link beast.ref.boost__beast__http__async_read.overload2 `async_read`] 以及 [link beast.ref.boost__beast__http__async_write.overload2 `async_write`]。]
][
    [[*5]]
    [__解析器__, __序列化器__][若需更多控制权，调用方可以自行管理所需的 __parser__ 或 __serializer__ 临时状态对象。这样便可以实现额外配置，例如在解析过程中限制消息组件的最大字节数，或控制输出时缓冲区的大小。以下函数通过使用解析器或序列化器来发送或接收完整消息：[link beast.ref.boost__beast__http__read.overload2 `read`]、[link beast.ref.boost__beast__http__write.overload2 `write`]、[link beast.ref.boost__beast__http__async_read.overload1 `async_read`] 以及 [link beast.ref.boost__beast__http__async_write.overload1 `async_write`]。]
][
    [[*4]]
    [__头部__][有时需要先发送或接收 HTTP 头部，例如在读取头部后根据其内容决定后续操作，然后再继续读取消息体。以下函数使用 __parser__ 或 __serializer__ 来读取或写入头部：[link beast.ref.boost__beast__http__read_header.overload2 `read_header`]、[link beast.ref.boost__beast__http__write_header.overload2 `write_header`]、[link beast.ref.boost__beast__http__async_read_header `async_read_header`] 以及 [link beast.ref.boost__beast__http__async_write_header `async_write_header`]。]
][
    [[*3]]
    [部分 __消息__][到目前为止，所有较高层次的流操作都针对完整的消息头部或完整消息进行。而在此层次，则可以实现消息的增量式发送与接收。这对资源受限的实现特别有用，可以在有限的存储空间内完成任务，或在设置超时等场景下提供更精细的控制。以下函数用于读取或写入限定量的数据，并返回实际传输的字节数：[link beast.ref.boost__beast__http__read_some.overload2 `read_some`]、[link beast.ref.boost__beast__http__write_some.overload2 `write_some`]、[link beast.ref.boost__beast__http__async_read_some `async_read_some`] 以及 [link beast.ref.boost__beast__http__async_write_some `async_write_some`]。]
][
    [[*2]]
    [
        [@https://tools.ietf.org/html/rfc7230#section-4.1 ['chunked-body]]
    ][到目前为止，解析和序列化操作会根据需要自动对消息体应用或移除分块传输编码。但在某些特定领域，需要对分块编码的消息体中的传入或传出数据块进行直接控制。在解析端，可以通过设置钩子来实现：使用 [link beast.ref.boost__beast__http__parser.on_chunk_header `on_chunk_header`] 和/或 [link beast.ref.boost__beast__http__parser.on_chunk_body `on_chunk_body`] 函数。在序列化端，调用方可以先发送消息头部，然后使用以下缓冲区序列适配器来控制每个数据块的内容，包括分块扩展和尾部部分：[link beast.ref.boost__beast__http__chunk_body `chunk_body`]、[link beast.ref.boost__beast__http__chunk_crlf `chunk_crlf`]、[link beast.ref.boost__beast__http__chunk_header `chunk_header`] 以及 [link beast.ref.boost__beast__http__chunk_last `chunk_last`]。]
][
    [[*1]]
    [缓冲区][若需最高级别的控制，可以完全绕过库的流算法，直接通过调用 __parser__ 或 __serializer__ 的成员函数来操作缓冲区。]
][
    [[*0]]
    [
        ['user-defined]
    ][除了常见的 __Stream__ 和 __DynamicBuffer__ 定制点外，用户自定义类型还可以在最底层替换库实现的部分组件。这些定制点包括：用于创建存储 HTTP 字段容器的 __Fields__、用于定义 HTTP 消息体容器及相关算法的 __Body__，以及用于实现自定义消息表示策略的 __basic_parser__ 子类。]
]]

[note
    本文档假定读者已具备一定的 Asio 使用经验，并
    the HTTP protocol specification described in __rfc7230__. Sample
    code and identifiers mentioned in this section is written as if
    these declarations are in effect:

    [http_snippet_1]
]

[include 01_primer.qbk]
[include 02_message.qbk]
[include 03_streams.qbk]
[include 04_serializer_streams.qbk]
[include 05_parser_streams.qbk]
[include 06_serializer_buffers.qbk]
[include 07_parser_buffers.qbk]
[include 08_chunked_encoding.qbk]
[include 09_custom_body.qbk]
[include 10_custom_parsers.qbk]

[endsect]