EQ2EMu/EQ2/source/depends/boost_1_72_0/libs/beast/doc/qbk/04_http/02_message.qbk

[/
    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 Message Containers]

Beast provides a single class template __message__ and some aliases which
model HTTP/1 and
[@https://tools.ietf.org/html/rfc7540 HTTP/2]
messages:

[table Message
[[Name][Description]]
[[
    __message__
][
    ```
    /// An HTTP message
    template<
        bool isRequest,             // `true` for requests, `false` for responses
        class Body,                 // Controls the container and algorithms used for the body
        class Fields = fields>      // The type of container to store the fields
    class message;
    ```
]]
[[
    [link beast.ref.boost__beast__http__request `request`]
][
    ```
    /// A typical HTTP request
    template<class Body, class Fields = fields>
    using request = message<true, Body, Fields>;
    ```
]]
[[
    [link beast.ref.boost__beast__http__response `response`]
][
    ```
    /// A typical HTTP response
    template<class Body, class Fields = fields>
    using response = message<false, Body, Fields>;
    ```
]]
]

The container offers value semantics including move and copy if supported
by __Body__ and __Fields__. User defined template function parameters can
accept any message, or can use partial specialization to accept just
requests or responses. The default __fields__ is a provided associative
container using the standard allocator and supporting modification and
inspection of fields. As per __rfc7230__, a non-case-sensitive comparison
is used for field names. User defined types for fields are possible.
The `Body` type determines the type of the container used to represent the
body as well as the algorithms for transferring buffers to and from the
container. The library comes with a collection of common body types. As
with fields, user defined body types are possible.

Sometimes it is desired to only work with a header. Beast provides a single
class template __header__ and some aliases to model HTTP/1 and HTTP/2 headers:

[table Header
[[Name][Description]]
[[
    __header__
][
    ```
    /// An HTTP header
    template<
        bool isRequest,             // `true` for requests, `false` for responses
        class Fields = fields>      // The type of container to store the fields
    class header;
    ```
]]
[[
    [link beast.ref.boost__beast__http__request_header `request_header`]
][
    ```
    /// A typical HTTP request header
    template<class Fields>
    using request_header = header<true, Fields>;
    ```
]]
[[
    [link beast.ref.boost__beast__http__response_header `response_header`]
][
    ```
    /// A typical HTTP response header
    template<class Fields>
    using response_header = header<false, Fields>;
    ```
]]
]

Requests and responses share the version, fields, and body but have
a few members unique to the type. This is implemented by declaring the
header classes as partial specializations of `isRequest`. __message__
is derived from __header__; a message may be passed as an argument to
a function taking a suitably typed header as a parameter. Additionally,
`header` is publicly derived from `Fields`; a message inherits all the
member functions of `Fields`. This diagram shows the inheritance
relationship between header and message, along with some of the
notable differences in members in each partial specialization:

[$beast/images/message.png [width 730px] [height 459px]]

[heading:body Body Types]

Beast defines the __Body__ concept, which determines both the type of
the [link beast.ref.boost__beast__http__message.body `message::body`] member
(as seen in the diagram above) and may also include algorithms for
transferring buffers in and out. These algorithms are used during
parsing and serialization. Users may define their own body types which
meet the requirements, or use the ones that come with the library:

[table
[[Name][Description]]
[[
    [link beast.ref.boost__beast__http__buffer_body `buffer_body`]
][
    A body whose
    [link beast.ref.boost__beast__http__buffer_body__value_type `value_type`]
    holds a raw pointer and size to a caller-provided buffer.
    This allows for serialization of body data coming from
    external sources, and incremental parsing of message body
    content using a fixed size buffer.
]]
[[
    [link beast.ref.boost__beast__http__dynamic_body `dynamic_body`]

    [link beast.ref.boost__beast__http__basic_dynamic_body `basic_dynamic_body`]
][
    A body whose `value_type` is a __DynamicBuffer__. It inherits
    the insertion complexity of the underlying choice of dynamic buffer.
    Messages with this body type may be serialized and parsed.
]]
[[
    [link beast.ref.boost__beast__http__empty_body `empty_body`]
][
    A special body with an empty `value_type` indicating that the
    message has no body. Messages with this body may be serialized
    and parsed; however, body octets received while parsing a message
    with this body will generate a unique error.
]]
[[
    [link beast.ref.boost__beast__http__file_body `file_body`]

    [link beast.ref.boost__beast__http__basic_file_body `basic_file_body`]
][
    This body is represented by a file opened for either reading or
    writing. Messages with this body may be serialized and parsed.
    HTTP algorithms will use the open file for reading and writing,
    for streaming and incremental sends and receives.
]]
[[
    [link beast.ref.boost__beast__http__span_body `span_body`]
][
    A body whose `value_type` is a
    [link beast.ref.boost__beast__span `span`],
    a non-owning reference to a single linear buffer of bytes.
    Messages with this body type may be serialized and parsed.
]]
[[
    [link beast.ref.boost__beast__http__string_body `string_body`]

    [link beast.ref.boost__beast__http__basic_string_body `basic_string_body`]
][
    A body whose `value_type` is `std::basic_string` or `std::string`.
    Insertion complexity is amortized constant time, while capacity
    grows geometrically. Messages with this body type may be serialized
    and parsed. This is the type of body used in the examples.
]]
[[
    [link beast.ref.boost__beast__http__vector_body `vector_body`]
][
    A body whose `value_type` is `std::vector`. Insertion complexity
    is amortized constant time, while capacity grows geometrically.
    Messages with this body type may be serialized and parsed.
]]
]

[heading Usage]

These examples show how to create and fill in request and response
objects: Here we build an
[@https://tools.ietf.org/html/rfc7231#section-4.3.1 HTTP GET]
request with an empty message body:

[table Create Request
[[Statements] [Serialized Result]]
[[
    [http_snippet_2]
][
```
    GET /index.htm HTTP/1.1\r\n
    Accept: text/html\r\n
    User-Agent: Beast\r\n
    \r\n
```
]]
]

In this code we create an HTTP response with a status code indicating success.
This message has a body with a non-zero length. The function
[link beast.ref.boost__beast__http__message.prepare_payload `message::prepare_payload`]
automatically sets the Content-Length or Transfer-Encoding field
depending on the content and type of the `body` member. Use of this function
is optional; these fields may also be set explicitly.

[table Create Response
[[Statements] [Serialized Result]]
[[
    [http_snippet_3]
][
```
    HTTP/1.1 200 OK\r\n
    Server: Beast\r\n
    Content-Length: 13\r\n
    \r\n
    Hello, world!
```
]]
]

The implementation will automatically fill in the obsolete
[@https://tools.ietf.org/html/rfc7230#section-3.1.2 reason-phrase]
from the status code when serializing a message. Or it may
be set directly using
[link beast.ref.boost__beast__http__header.reason.overload2 `header::reason`].

[endsect]