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