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