1[/
2    Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
3
4    Distributed under the Boost Software License, Version 1.0. (See accompanying
5    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6
7    Official repository: https://github.com/boostorg/beast
8]
9
10[section:Fields Fields]
11
12[warning
13    The ['Fields] concept is deprecated and will be removed in
14    a future version. The information on this page is provided
15    for historical purposes only.
16]
17
18An instance of [*Fields] is a container for holding HTTP header fields
19and their values. The implementation also calls upon the container to
20store the request target and non-standard strings for method and obsolete
21reason phrase as needed. Types which meet these requirements can always
22be serialized.
23
24[heading Associated Types]
25
26* [link beast.ref.boost__beast__http__is_fields `is_fields`]
27* __FieldsWriter__
28
29[heading Requirements]
30
31In this table:
32
33* `F` denotes a type that meets the requirements of [*Fields].
34* `W` denotes a type meeting the requirements of __FieldsWriter__.
35* `a` denotes a value of type `F`.
36* `c` denotes a (possibly const) value of type `F`.
37* `b` is a value of type `bool`
38* `n` is a value of type `boost::optional<std::uint64_t>`.
39* `s` is a value of type [link beast.ref.boost__beast__string_view `string_view`].
40* `v` is a value of type `unsigned int` representing the HTTP-version.
41
42[table Valid expressions
43[[Expression] [Type] [Semantics, Pre/Post-conditions]]
44[
45    [`F::writer`]
46    [`W`]
47    [
48        A type which meets the requirements of __FieldsWriter__.
49    ]
50][
51    [`c.get_method_impl()`]
52    [`string_view`]
53    [
54        Returns the method text.
55        The implementation only calls this function for request
56        headers when retrieving the method text previously set
57        with a call to `set_method_impl` using a non-empty string.
58    ]
59][
60    [`c.get_target_impl()`]
61    [`string_view`]
62    [
63        Returns the target string.
64        The implementation only calls this function for request headers.
65    ]
66][
67    [`c.get_reason_impl()`]
68    [`string_view`]
69    [
70        Returns the obsolete request text.
71        The implementation only calls this for response headers when
72        retrieving the reason text previously set with a call to
73        `set_reason_impl` using a non-empty string.
74    ]
75][
76    [`c.get_chunked_impl()`]
77    [`bool`]
78    [
79        Returns `true` if the
80        [@https://tools.ietf.org/html/rfc7230#section-3.3.1 [*Transfer-Encoding]]
81        field value indicates that the payload is chunk encoded. Both
82        of these conditions must be true:
83        [itemized_list
84        [
85            The Transfer-Encoding field is present in the message.
86        ][
87            The last item in value of the field is "chunked".
88        ]]
89    ]
90][
91    [`c.get_keep_alive_impl(v)`]
92    [`bool`]
93    [
94        Returns `true` if the semantics of the
95        [@https://tools.ietf.org/html/rfc7230#section-6.1 [*Connection]]
96        field and version indicate that the connection should remain
97        open after the corresponding response is transmitted or received:
98
99        [itemized_list
100        [
101            If `(v < 11)` the function returns `true` if the "keep-alive"
102            token is present in the Connection field value. Otherwise the
103            function returns `false`.
104        ][
105            If `(v == 11)`, the function returns `false` if the "close"
106            token is present in the Connection field value. Otherwise the
107            function returns `true`.
108        ]]
109    ]
110][
111    [`c.has_content_length()`]
112    [`bool`]
113    [
114        Returns `true` if the
115        [@https://tools.ietf.org/html/rfc7230#section-3.3.2 [*Content-Length]]
116        field is present.
117    ]
118][
119    [`a.set_method_impl(s)`]
120    []
121    [
122        Stores a copy of `s` as the method text, or erases the previously
123        stored value if `s` is empty.
124        The implementation only calls this function for request headers.
125        This function may throw `std::invalid_argument` if the operation
126        is not supported by the container.
127    ]
128][
129    [`a.set_target_impl(s)`]
130    []
131    [
132        Stores a copy of `s` as the target, or erases the previously
133        stored value if `s` is empty.
134        The implementation only calls this function for request headers.
135        This function may throw `std::invalid_argument` if the operation
136        is not supported by the container.
137    ]
138][
139    [`a.set_reason_impl(s)`]
140    []
141    [
142        Stores a copy of `s` as the reason text, or erases the previously
143        stored value of the reason text if `s` is empty.
144        The implementation only calls this function for request headers.
145        This function may throw `std::invalid_argument` if the operation
146        is not supported by the container.
147    ]
148][
149    [`a.set_chunked_impl(b)`]
150    []
151    [
152        Adjusts the
153        [@https://tools.ietf.org/html/rfc7230#section-3.3.1 [*Transfer-Encoding]]
154        field value as follows:
155
156        [itemized_list
157        [
158            If `b` is `true`, the "chunked" token is appended
159            to the list of encodings if it does not already appear
160            last in the list.
161            If the Transfer-Encoding field is absent, the field will
162            be inserted to the container with the value "chunked".
163        ][
164            If `b` is `false, the "chunked" token is removed from the
165            list of encodings if it appears last in the list.
166            If the result of the removal leaves the list of encodings
167            empty, the Transfer-Encoding field shall not appear when
168            the associated __FieldsWriter__ serializes the fields.
169        ]]
170
171        If the result of adjusting the field value produces an empty
172        string, the field is removed from the container.
173    ]
174
175][
176    [`a.set_content_length_impl(n)`]
177    []
178    [
179        Adjusts the
180        [@https://tools.ietf.org/html/rfc7230#section-3.3.2 [*Content-Length]]
181        field value as follows:
182
183        [itemized_list
184        [
185            If `n` contains a value, the Content-Length field
186            will be set to the text representation of the value.
187            Any previous Content-Length fields are removed from
188            the container.
189        ][
190            If `n` does not contain a value, any present Content-Length
191            fields are removed from the container.
192        ]]
193    ]
194
195][
196    [`a.set_keep_alive_impl(v,b)`]
197    []
198    [
199        Adjusts the
200        [@https://tools.ietf.org/html/rfc7230#section-6.1 [*Connection]]
201        field value depending on the values of `v` and `b`. The field
202        value is treated as
203        [@https://tools.ietf.org/html/rfc7230#section-6.1 ['connection-option]]
204        (rfc7230).
205
206        [itemized_list
207        [
208            If `(v < 11 && b)`, then all "close" tokens present in the
209            value are removed, and the "keep-alive" token is added to
210            the value if it is not already present.
211        ][
212            If `(v < 11 && ! b)`, then all "close" and "keep-alive"
213            tokens present in the value are removed.
214
215        ][
216            If `(v == 11 && b)`, then all "keep-alive" and "close"
217            tokens present in the value are removed.
218        ][
219            If `(v == 11 && ! b)`, then all "keep-alive" tokens present
220            in the value are removed, and the "close" token is added to
221            the value if it is not already present.
222        ]]
223
224        If the result of adjusting the field value produces an empty
225        string, the field is removed from the container.
226    ]
227
228]]
229
230[heading Exemplar]
231
232[concept_Fields]
233
234[heading Models]
235
236* [link beast.ref.boost__beast__http__basic_fields `basic_fields`]
237* [link beast.ref.boost__beast__http__fields `fields`]
238
239[endsect]
240