240 lines
7.6 KiB
Plaintext
240 lines
7.6 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:Fields Fields]
|
|
|
|
[warning
|
|
The ['Fields] concept is deprecated and will be removed in
|
|
a future version. The information on this page is provided
|
|
for historical purposes only.
|
|
]
|
|
|
|
An instance of [*Fields] is a container for holding HTTP header fields
|
|
and their values. The implementation also calls upon the container to
|
|
store the request target and non-standard strings for method and obsolete
|
|
reason phrase as needed. Types which meet these requirements can always
|
|
be serialized.
|
|
|
|
[heading Associated Types]
|
|
|
|
* [link beast.ref.boost__beast__http__is_fields `is_fields`]
|
|
* __FieldsWriter__
|
|
|
|
[heading Requirements]
|
|
|
|
In this table:
|
|
|
|
* `F` denotes a type that meets the requirements of [*Fields].
|
|
* `W` denotes a type meeting the requirements of __FieldsWriter__.
|
|
* `a` denotes a value of type `F`.
|
|
* `c` denotes a (possibly const) value of type `F`.
|
|
* `b` is a value of type `bool`
|
|
* `n` is a value of type `boost::optional<std::uint64_t>`.
|
|
* `s` is a value of type [link beast.ref.boost__beast__string_view `string_view`].
|
|
* `v` is a value of type `unsigned int` representing the HTTP-version.
|
|
|
|
[table Valid expressions
|
|
[[Expression] [Type] [Semantics, Pre/Post-conditions]]
|
|
[
|
|
[`F::writer`]
|
|
[`W`]
|
|
[
|
|
A type which meets the requirements of __FieldsWriter__.
|
|
]
|
|
][
|
|
[`c.get_method_impl()`]
|
|
[`string_view`]
|
|
[
|
|
Returns the method text.
|
|
The implementation only calls this function for request
|
|
headers when retrieving the method text previously set
|
|
with a call to `set_method_impl` using a non-empty string.
|
|
]
|
|
][
|
|
[`c.get_target_impl()`]
|
|
[`string_view`]
|
|
[
|
|
Returns the target string.
|
|
The implementation only calls this function for request headers.
|
|
]
|
|
][
|
|
[`c.get_reason_impl()`]
|
|
[`string_view`]
|
|
[
|
|
Returns the obsolete request text.
|
|
The implementation only calls this for response headers when
|
|
retrieving the reason text previously set with a call to
|
|
`set_reason_impl` using a non-empty string.
|
|
]
|
|
][
|
|
[`c.get_chunked_impl()`]
|
|
[`bool`]
|
|
[
|
|
Returns `true` if the
|
|
[@https://tools.ietf.org/html/rfc7230#section-3.3.1 [*Transfer-Encoding]]
|
|
field value indicates that the payload is chunk encoded. Both
|
|
of these conditions must be true:
|
|
[itemized_list
|
|
[
|
|
The Transfer-Encoding field is present in the message.
|
|
][
|
|
The last item in value of the field is "chunked".
|
|
]]
|
|
]
|
|
][
|
|
[`c.get_keep_alive_impl(v)`]
|
|
[`bool`]
|
|
[
|
|
Returns `true` if the semantics of the
|
|
[@https://tools.ietf.org/html/rfc7230#section-6.1 [*Connection]]
|
|
field and version indicate that the connection should remain
|
|
open after the corresponding response is transmitted or received:
|
|
|
|
[itemized_list
|
|
[
|
|
If `(v < 11)` the function returns `true` if the "keep-alive"
|
|
token is present in the Connection field value. Otherwise the
|
|
function returns `false`.
|
|
][
|
|
If `(v == 11)`, the function returns `false` if the "close"
|
|
token is present in the Connection field value. Otherwise the
|
|
function returns `true`.
|
|
]]
|
|
]
|
|
][
|
|
[`c.has_content_length()`]
|
|
[`bool`]
|
|
[
|
|
Returns `true` if the
|
|
[@https://tools.ietf.org/html/rfc7230#section-3.3.2 [*Content-Length]]
|
|
field is present.
|
|
]
|
|
][
|
|
[`a.set_method_impl(s)`]
|
|
[]
|
|
[
|
|
Stores a copy of `s` as the method text, or erases the previously
|
|
stored value if `s` is empty.
|
|
The implementation only calls this function for request headers.
|
|
This function may throw `std::invalid_argument` if the operation
|
|
is not supported by the container.
|
|
]
|
|
][
|
|
[`a.set_target_impl(s)`]
|
|
[]
|
|
[
|
|
Stores a copy of `s` as the target, or erases the previously
|
|
stored value if `s` is empty.
|
|
The implementation only calls this function for request headers.
|
|
This function may throw `std::invalid_argument` if the operation
|
|
is not supported by the container.
|
|
]
|
|
][
|
|
[`a.set_reason_impl(s)`]
|
|
[]
|
|
[
|
|
Stores a copy of `s` as the reason text, or erases the previously
|
|
stored value of the reason text if `s` is empty.
|
|
The implementation only calls this function for request headers.
|
|
This function may throw `std::invalid_argument` if the operation
|
|
is not supported by the container.
|
|
]
|
|
][
|
|
[`a.set_chunked_impl(b)`]
|
|
[]
|
|
[
|
|
Adjusts the
|
|
[@https://tools.ietf.org/html/rfc7230#section-3.3.1 [*Transfer-Encoding]]
|
|
field value as follows:
|
|
|
|
[itemized_list
|
|
[
|
|
If `b` is `true`, the "chunked" token is appended
|
|
to the list of encodings if it does not already appear
|
|
last in the list.
|
|
If the Transfer-Encoding field is absent, the field will
|
|
be inserted to the container with the value "chunked".
|
|
][
|
|
If `b` is `false, the "chunked" token is removed from the
|
|
list of encodings if it appears last in the list.
|
|
If the result of the removal leaves the list of encodings
|
|
empty, the Transfer-Encoding field shall not appear when
|
|
the associated __FieldsWriter__ serializes the fields.
|
|
]]
|
|
|
|
If the result of adjusting the field value produces an empty
|
|
string, the field is removed from the container.
|
|
]
|
|
|
|
][
|
|
[`a.set_content_length_impl(n)`]
|
|
[]
|
|
[
|
|
Adjusts the
|
|
[@https://tools.ietf.org/html/rfc7230#section-3.3.2 [*Content-Length]]
|
|
field value as follows:
|
|
|
|
[itemized_list
|
|
[
|
|
If `n` contains a value, the Content-Length field
|
|
will be set to the text representation of the value.
|
|
Any previous Content-Length fields are removed from
|
|
the container.
|
|
][
|
|
If `n` does not contain a value, any present Content-Length
|
|
fields are removed from the container.
|
|
]]
|
|
]
|
|
|
|
][
|
|
[`a.set_keep_alive_impl(v,b)`]
|
|
[]
|
|
[
|
|
Adjusts the
|
|
[@https://tools.ietf.org/html/rfc7230#section-6.1 [*Connection]]
|
|
field value depending on the values of `v` and `b`. The field
|
|
value is treated as
|
|
[@https://tools.ietf.org/html/rfc7230#section-6.1 ['connection-option]]
|
|
(rfc7230).
|
|
|
|
[itemized_list
|
|
[
|
|
If `(v < 11 && b)`, then all "close" tokens present in the
|
|
value are removed, and the "keep-alive" token is added to
|
|
the value if it is not already present.
|
|
][
|
|
If `(v < 11 && ! b)`, then all "close" and "keep-alive"
|
|
tokens present in the value are removed.
|
|
|
|
][
|
|
If `(v == 11 && b)`, then all "keep-alive" and "close"
|
|
tokens present in the value are removed.
|
|
][
|
|
If `(v == 11 && ! b)`, then all "keep-alive" tokens present
|
|
in the value are removed, and the "close" token is added to
|
|
the value if it is not already present.
|
|
]]
|
|
|
|
If the result of adjusting the field value produces an empty
|
|
string, the field is removed from the container.
|
|
]
|
|
|
|
]]
|
|
|
|
[heading Exemplar]
|
|
|
|
[concept_Fields]
|
|
|
|
[heading Models]
|
|
|
|
* [link beast.ref.boost__beast__http__basic_fields `basic_fields`]
|
|
* [link beast.ref.boost__beast__http__fields `fields`]
|
|
|
|
[endsect]
|