]>
Commit | Line | Data |
---|---|---|
b32b8144 | 1 | // |
92f5a8d4 | 2 | // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) |
b32b8144 FG |
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 | #ifndef BOOST_BEAST_HTTP_READ_HPP | |
11 | #define BOOST_BEAST_HTTP_READ_HPP | |
12 | ||
13 | #include <boost/beast/core/detail/config.hpp> | |
14 | #include <boost/beast/core/error.hpp> | |
92f5a8d4 | 15 | #include <boost/beast/core/stream_traits.hpp> |
b32b8144 FG |
16 | #include <boost/beast/http/basic_parser.hpp> |
17 | #include <boost/beast/http/message.hpp> | |
18 | #include <boost/asio/async_result.hpp> | |
19 | ||
20 | namespace boost { | |
21 | namespace beast { | |
22 | namespace http { | |
23 | ||
92f5a8d4 TL |
24 | //------------------------------------------------------------------------------ |
25 | ||
b32b8144 FG |
26 | /** Read part of a message from a stream using a parser. |
27 | ||
92f5a8d4 TL |
28 | This function is used to read part of a message from a stream into an |
29 | instance of @ref basic_parser. The call will block until one of the | |
30 | following conditions is true: | |
b32b8144 FG |
31 | |
32 | @li A call to @ref basic_parser::put with a non-empty buffer sequence | |
92f5a8d4 | 33 | is successful. |
b32b8144 FG |
34 | |
35 | @li An error occurs. | |
36 | ||
92f5a8d4 TL |
37 | This operation is implemented in terms of one or more calls to the stream's |
38 | `read_some` function. The implementation may read additional bytes from | |
39 | the stream that lie past the end of the message being read. These additional | |
40 | bytes are stored in the dynamic buffer, which must be preserved for | |
41 | subsequent reads. | |
b32b8144 | 42 | |
92f5a8d4 TL |
43 | If the end of file error is received while reading from the stream, then |
44 | the error returned from this function will be: | |
b32b8144 | 45 | |
92f5a8d4 | 46 | @li @ref error::end_of_stream if no bytes were parsed, or |
b32b8144 | 47 | |
92f5a8d4 TL |
48 | @li @ref error::partial_message if any bytes were parsed but the |
49 | message was incomplete, otherwise: | |
b32b8144 | 50 | |
92f5a8d4 TL |
51 | @li A successful result. The next attempt to read will return |
52 | @ref error::end_of_stream | |
b32b8144 | 53 | |
92f5a8d4 TL |
54 | @param stream The stream from which the data is to be read. The type must |
55 | meet the <em>SyncReadStream</em> requirements. | |
b32b8144 | 56 | |
92f5a8d4 TL |
57 | @param buffer Storage for additional bytes read by the implementation from |
58 | the stream. This is both an input and an output parameter; on entry, the | |
59 | parser will be presented with any remaining data in the dynamic buffer's | |
60 | readable bytes sequence first. The type must meet the <em>DynamicBuffer</em> | |
61 | requirements. | |
b32b8144 FG |
62 | |
63 | @param parser The parser to use. | |
64 | ||
92f5a8d4 | 65 | @return The number of bytes transferred from the stream. |
b32b8144 FG |
66 | |
67 | @throws system_error Thrown on failure. | |
92f5a8d4 TL |
68 | |
69 | @note The function returns the total number of bytes transferred from the | |
70 | stream. This may be zero for the case where there is sufficient pre-existing | |
71 | message data in the dynamic buffer. | |
b32b8144 FG |
72 | */ |
73 | template< | |
74 | class SyncReadStream, | |
75 | class DynamicBuffer, | |
92f5a8d4 | 76 | bool isRequest> |
b32b8144 FG |
77 | std::size_t |
78 | read_some( | |
79 | SyncReadStream& stream, | |
80 | DynamicBuffer& buffer, | |
92f5a8d4 | 81 | basic_parser<isRequest>& parser); |
b32b8144 FG |
82 | |
83 | /** Read part of a message from a stream using a parser. | |
84 | ||
92f5a8d4 TL |
85 | This function is used to read part of a message from a stream into an |
86 | instance of @ref basic_parser. The call will block until one of the | |
87 | following conditions is true: | |
b32b8144 FG |
88 | |
89 | @li A call to @ref basic_parser::put with a non-empty buffer sequence | |
92f5a8d4 | 90 | is successful. |
b32b8144 FG |
91 | |
92 | @li An error occurs. | |
93 | ||
92f5a8d4 TL |
94 | This operation is implemented in terms of one or more calls to the stream's |
95 | `read_some` function. The implementation may read additional bytes from | |
96 | the stream that lie past the end of the message being read. These additional | |
97 | bytes are stored in the dynamic buffer, which must be preserved for | |
98 | subsequent reads. | |
b32b8144 | 99 | |
92f5a8d4 TL |
100 | If the end of file error is received while reading from the stream, then |
101 | the error returned from this function will be: | |
b32b8144 | 102 | |
92f5a8d4 | 103 | @li @ref error::end_of_stream if no bytes were parsed, or |
b32b8144 | 104 | |
92f5a8d4 TL |
105 | @li @ref error::partial_message if any bytes were parsed but the |
106 | message was incomplete, otherwise: | |
b32b8144 | 107 | |
92f5a8d4 TL |
108 | @li A successful result. The next attempt to read will return |
109 | @ref error::end_of_stream | |
b32b8144 | 110 | |
92f5a8d4 TL |
111 | @param stream The stream from which the data is to be read. The type must |
112 | support the <em>SyncReadStream</em> requirements. | |
b32b8144 | 113 | |
92f5a8d4 TL |
114 | @param buffer Storage for additional bytes read by the implementation from |
115 | the stream. This is both an input and an output parameter; on entry, the | |
116 | parser will be presented with any remaining data in the dynamic buffer's | |
117 | readable bytes sequence first. The type must meet the <em>DynamicBuffer</em> | |
118 | requirements. | |
b32b8144 FG |
119 | |
120 | @param parser The parser to use. | |
121 | ||
122 | @param ec Set to the error, if any occurred. | |
123 | ||
92f5a8d4 TL |
124 | @return The number of bytes transferred from the stream. |
125 | ||
126 | @note The function returns the total number of bytes transferred from the | |
127 | stream. This may be zero for the case where there is sufficient pre-existing | |
128 | message data in the dynamic buffer. | |
b32b8144 FG |
129 | */ |
130 | template< | |
131 | class SyncReadStream, | |
132 | class DynamicBuffer, | |
92f5a8d4 | 133 | bool isRequest> |
b32b8144 FG |
134 | std::size_t |
135 | read_some( | |
136 | SyncReadStream& stream, | |
137 | DynamicBuffer& buffer, | |
92f5a8d4 | 138 | basic_parser<isRequest>& parser, |
b32b8144 FG |
139 | error_code& ec); |
140 | ||
141 | /** Read part of a message asynchronously from a stream using a parser. | |
142 | ||
143 | This function is used to asynchronously read part of a message from | |
92f5a8d4 TL |
144 | a stream into an instance of @ref basic_parser. The function call |
145 | always returns immediately. The asynchronous operation will continue | |
146 | until one of the following conditions is true: | |
b32b8144 FG |
147 | |
148 | @li A call to @ref basic_parser::put with a non-empty buffer sequence | |
92f5a8d4 | 149 | is successful. |
b32b8144 FG |
150 | |
151 | @li An error occurs. | |
152 | ||
92f5a8d4 TL |
153 | This operation is implemented in terms of zero or more calls to the |
154 | next layer's `async_read_some` function, and is known as a <em>composed | |
155 | operation</em>. The program must ensure that the stream performs no other | |
156 | reads until this operation completes. The implementation may read additional | |
157 | bytes from the stream that lie past the end of the message being read. | |
158 | These additional bytes are stored in the dynamic buffer, which must be | |
159 | preserved for subsequent reads. | |
b32b8144 | 160 | |
92f5a8d4 TL |
161 | If the end of file error is received while reading from the stream, then |
162 | the error returned from this function will be: | |
b32b8144 | 163 | |
92f5a8d4 | 164 | @li @ref error::end_of_stream if no bytes were parsed, or |
b32b8144 | 165 | |
92f5a8d4 TL |
166 | @li @ref error::partial_message if any bytes were parsed but the |
167 | message was incomplete, otherwise: | |
b32b8144 | 168 | |
92f5a8d4 TL |
169 | @li A successful result. The next attempt to read will return |
170 | @ref error::end_of_stream | |
b32b8144 | 171 | |
92f5a8d4 TL |
172 | @param stream The stream from which the data is to be read. The type |
173 | must meet the <em>AsyncReadStream</em> requirements. | |
b32b8144 | 174 | |
92f5a8d4 TL |
175 | @param buffer Storage for additional bytes read by the implementation from |
176 | the stream. This is both an input and an output parameter; on entry, the | |
177 | parser will be presented with any remaining data in the dynamic buffer's | |
178 | readable bytes sequence first. The type must meet the <em>DynamicBuffer</em> | |
179 | requirements. The object must remain valid at least until the handler | |
180 | is called; ownership is not transferred. | |
b32b8144 | 181 | |
92f5a8d4 TL |
182 | @param parser The parser to use. The object must remain valid at least until |
183 | the handler is called; ownership is not transferred. | |
b32b8144 | 184 | |
92f5a8d4 TL |
185 | @param handler The completion handler to invoke when the operation |
186 | completes. The implementation takes ownership of the handler by | |
187 | performing a decay-copy. The equivalent function signature of | |
188 | the handler must be: | |
189 | @code | |
190 | void handler( | |
b32b8144 | 191 | error_code const& error, // result of operation |
92f5a8d4 TL |
192 | std::size_t bytes_transferred // the total number of bytes transferred from the stream |
193 | ); | |
194 | @endcode | |
b32b8144 FG |
195 | Regardless of whether the asynchronous operation completes |
196 | immediately or not, the handler will not be invoked from within | |
197 | this function. Invocation of the handler will be performed in a | |
92f5a8d4 | 198 | manner equivalent to using `net::post`. |
b32b8144 | 199 | |
92f5a8d4 TL |
200 | @note The completion handler will receive as a parameter the total number |
201 | of bytes transferred from the stream. This may be zero for the case where | |
202 | there is sufficient pre-existing message data in the dynamic buffer. | |
b32b8144 FG |
203 | */ |
204 | template< | |
205 | class AsyncReadStream, | |
206 | class DynamicBuffer, | |
92f5a8d4 TL |
207 | bool isRequest, |
208 | BOOST_BEAST_ASYNC_TPARAM2 ReadHandler = | |
209 | net::default_completion_token_t< | |
210 | executor_type<AsyncReadStream>>> | |
211 | BOOST_BEAST_ASYNC_RESULT2(ReadHandler) | |
b32b8144 FG |
212 | async_read_some( |
213 | AsyncReadStream& stream, | |
214 | DynamicBuffer& buffer, | |
92f5a8d4 TL |
215 | basic_parser<isRequest>& parser, |
216 | ReadHandler&& handler = | |
217 | net::default_completion_token_t< | |
218 | executor_type<AsyncReadStream>>{}); | |
b32b8144 FG |
219 | |
220 | //------------------------------------------------------------------------------ | |
221 | ||
92f5a8d4 | 222 | /** Read a complete message header from a stream using a parser. |
b32b8144 | 223 | |
92f5a8d4 TL |
224 | This function is used to read a complete message header from a stream |
225 | into an instance of @ref basic_parser. The call will block until one of the | |
226 | following conditions is true: | |
b32b8144 FG |
227 | |
228 | @li @ref basic_parser::is_header_done returns `true` | |
229 | ||
230 | @li An error occurs. | |
231 | ||
92f5a8d4 TL |
232 | This operation is implemented in terms of one or more calls to the stream's |
233 | `read_some` function. The implementation may read additional bytes from | |
234 | the stream that lie past the end of the message being read. These additional | |
235 | bytes are stored in the dynamic buffer, which must be preserved for | |
236 | subsequent reads. | |
b32b8144 | 237 | |
92f5a8d4 TL |
238 | If the end of file error is received while reading from the stream, then |
239 | the error returned from this function will be: | |
b32b8144 | 240 | |
92f5a8d4 | 241 | @li @ref error::end_of_stream if no bytes were parsed, or |
b32b8144 | 242 | |
92f5a8d4 TL |
243 | @li @ref error::partial_message if any bytes were parsed but the |
244 | message was incomplete, otherwise: | |
b32b8144 | 245 | |
92f5a8d4 TL |
246 | @li A successful result. The next attempt to read will return |
247 | @ref error::end_of_stream | |
b32b8144 | 248 | |
92f5a8d4 TL |
249 | @param stream The stream from which the data is to be read. The type must |
250 | meet the <em>SyncReadStream</em> requirements. | |
b32b8144 | 251 | |
92f5a8d4 TL |
252 | @param buffer Storage for additional bytes read by the implementation from |
253 | the stream. This is both an input and an output parameter; on entry, the | |
254 | parser will be presented with any remaining data in the dynamic buffer's | |
255 | readable bytes sequence first. The type must meet the <em>DynamicBuffer</em> | |
256 | requirements. | |
b32b8144 FG |
257 | |
258 | @param parser The parser to use. | |
259 | ||
92f5a8d4 | 260 | @return The number of bytes transferred from the stream. |
b32b8144 FG |
261 | |
262 | @throws system_error Thrown on failure. | |
263 | ||
92f5a8d4 TL |
264 | @note The function returns the total number of bytes transferred from the |
265 | stream. This may be zero for the case where there is sufficient pre-existing | |
266 | message data in the dynamic buffer. The implementation will call | |
267 | @ref basic_parser::eager with the value `false` on the parser passed in. | |
b32b8144 FG |
268 | */ |
269 | template< | |
270 | class SyncReadStream, | |
271 | class DynamicBuffer, | |
92f5a8d4 | 272 | bool isRequest> |
b32b8144 FG |
273 | std::size_t |
274 | read_header( | |
275 | SyncReadStream& stream, | |
276 | DynamicBuffer& buffer, | |
92f5a8d4 | 277 | basic_parser<isRequest>& parser); |
b32b8144 | 278 | |
92f5a8d4 | 279 | /** Read a complete message header from a stream using a parser. |
b32b8144 | 280 | |
92f5a8d4 TL |
281 | This function is used to read a complete message header from a stream |
282 | into an instance of @ref basic_parser. The call will block until one of the | |
283 | following conditions is true: | |
b32b8144 FG |
284 | |
285 | @li @ref basic_parser::is_header_done returns `true` | |
286 | ||
287 | @li An error occurs. | |
288 | ||
92f5a8d4 TL |
289 | This operation is implemented in terms of one or more calls to the stream's |
290 | `read_some` function. The implementation may read additional bytes from | |
291 | the stream that lie past the end of the message being read. These additional | |
292 | bytes are stored in the dynamic buffer, which must be preserved for | |
293 | subsequent reads. | |
b32b8144 | 294 | |
92f5a8d4 TL |
295 | If the end of file error is received while reading from the stream, then |
296 | the error returned from this function will be: | |
b32b8144 | 297 | |
92f5a8d4 | 298 | @li @ref error::end_of_stream if no bytes were parsed, or |
b32b8144 | 299 | |
92f5a8d4 TL |
300 | @li @ref error::partial_message if any bytes were parsed but the |
301 | message was incomplete, otherwise: | |
b32b8144 | 302 | |
92f5a8d4 TL |
303 | @li A successful result. The next attempt to read will return |
304 | @ref error::end_of_stream | |
b32b8144 | 305 | |
92f5a8d4 TL |
306 | @param stream The stream from which the data is to be read. The type must |
307 | meet the <em>SyncReadStream</em> requirements. | |
b32b8144 | 308 | |
92f5a8d4 TL |
309 | @param buffer Storage for additional bytes read by the implementation from |
310 | the stream. This is both an input and an output parameter; on entry, the | |
311 | parser will be presented with any remaining data in the dynamic buffer's | |
312 | readable bytes sequence first. The type must meet the <em>DynamicBuffer</em> | |
313 | requirements. | |
b32b8144 FG |
314 | |
315 | @param parser The parser to use. | |
316 | ||
317 | @param ec Set to the error, if any occurred. | |
318 | ||
92f5a8d4 | 319 | @return The number of bytes transferred from the stream. |
b32b8144 | 320 | |
92f5a8d4 TL |
321 | @note The function returns the total number of bytes transferred from the |
322 | stream. This may be zero for the case where there is sufficient pre-existing | |
323 | message data in the dynamic buffer. The implementation will call | |
324 | @ref basic_parser::eager with the value `false` on the parser passed in. | |
b32b8144 FG |
325 | */ |
326 | template< | |
327 | class SyncReadStream, | |
328 | class DynamicBuffer, | |
92f5a8d4 | 329 | bool isRequest> |
b32b8144 FG |
330 | std::size_t |
331 | read_header( | |
332 | SyncReadStream& stream, | |
333 | DynamicBuffer& buffer, | |
92f5a8d4 | 334 | basic_parser<isRequest>& parser, |
b32b8144 FG |
335 | error_code& ec); |
336 | ||
92f5a8d4 | 337 | /** Read a complete message header asynchronously from a stream using a parser. |
b32b8144 | 338 | |
92f5a8d4 TL |
339 | This function is used to asynchronously read a complete message header from |
340 | a stream into an instance of @ref basic_parser. The function call always | |
341 | returns immediately. The asynchronous operation will continue until one of | |
342 | the following conditions is true: | |
b32b8144 FG |
343 | |
344 | @li @ref basic_parser::is_header_done returns `true` | |
345 | ||
346 | @li An error occurs. | |
347 | ||
92f5a8d4 TL |
348 | This operation is implemented in terms of zero or more calls to the |
349 | next layer's `async_read_some` function, and is known as a <em>composed | |
350 | operation</em>. The program must ensure that the stream performs no other | |
351 | reads until this operation completes. The implementation may read additional | |
352 | bytes from the stream that lie past the end of the message being read. | |
353 | These additional bytes are stored in the dynamic buffer, which must be | |
354 | preserved for subsequent reads. | |
b32b8144 | 355 | |
92f5a8d4 TL |
356 | If the end of file error is received while reading from the stream, then |
357 | the error returned from this function will be: | |
b32b8144 | 358 | |
92f5a8d4 | 359 | @li @ref error::end_of_stream if no bytes were parsed, or |
b32b8144 | 360 | |
92f5a8d4 TL |
361 | @li @ref error::partial_message if any bytes were parsed but the |
362 | message was incomplete, otherwise: | |
b32b8144 | 363 | |
92f5a8d4 TL |
364 | @li A successful result. The next attempt to read will return |
365 | @ref error::end_of_stream | |
b32b8144 | 366 | |
92f5a8d4 TL |
367 | @param stream The stream from which the data is to be read. The type |
368 | must meet the <em>AsyncReadStream</em> requirements. | |
b32b8144 | 369 | |
92f5a8d4 TL |
370 | @param buffer Storage for additional bytes read by the implementation from |
371 | the stream. This is both an input and an output parameter; on entry, the | |
372 | parser will be presented with any remaining data in the dynamic buffer's | |
373 | readable bytes sequence first. The type must meet the <em>DynamicBuffer</em> | |
374 | requirements. The object must remain valid at least until the handler | |
375 | is called; ownership is not transferred. | |
b32b8144 | 376 | |
92f5a8d4 TL |
377 | @param parser The parser to use. The object must remain valid at least until |
378 | the handler is called; ownership is not transferred. | |
379 | ||
380 | @param handler The completion handler to invoke when the operation | |
381 | completes. The implementation takes ownership of the handler by | |
382 | performing a decay-copy. The equivalent function signature of | |
383 | the handler must be: | |
384 | @code | |
385 | void handler( | |
386 | error_code const& error, // result of operation | |
387 | std::size_t bytes_transferred // the total number of bytes transferred from the stream | |
388 | ); | |
389 | @endcode | |
b32b8144 FG |
390 | Regardless of whether the asynchronous operation completes |
391 | immediately or not, the handler will not be invoked from within | |
392 | this function. Invocation of the handler will be performed in a | |
92f5a8d4 | 393 | manner equivalent to using `net::post`. |
b32b8144 | 394 | |
92f5a8d4 TL |
395 | @note The completion handler will receive as a parameter the total number |
396 | of bytes transferred from the stream. This may be zero for the case where | |
397 | there is sufficient pre-existing message data in the dynamic buffer. The | |
398 | implementation will call @ref basic_parser::eager with the value `false` | |
399 | on the parser passed in. | |
b32b8144 FG |
400 | */ |
401 | template< | |
402 | class AsyncReadStream, | |
403 | class DynamicBuffer, | |
92f5a8d4 TL |
404 | bool isRequest, |
405 | BOOST_BEAST_ASYNC_TPARAM2 ReadHandler = | |
406 | net::default_completion_token_t< | |
407 | executor_type<AsyncReadStream>>> | |
408 | BOOST_BEAST_ASYNC_RESULT2(ReadHandler) | |
b32b8144 FG |
409 | async_read_header( |
410 | AsyncReadStream& stream, | |
411 | DynamicBuffer& buffer, | |
92f5a8d4 TL |
412 | basic_parser<isRequest>& parser, |
413 | ReadHandler&& handler = | |
414 | net::default_completion_token_t< | |
415 | executor_type<AsyncReadStream>>{}); | |
b32b8144 FG |
416 | |
417 | //------------------------------------------------------------------------------ | |
418 | ||
419 | /** Read a complete message from a stream using a parser. | |
420 | ||
92f5a8d4 TL |
421 | This function is used to read a complete message from a stream into an |
422 | instance of @ref basic_parser. The call will block until one of the | |
423 | following conditions is true: | |
b32b8144 FG |
424 | |
425 | @li @ref basic_parser::is_done returns `true` | |
426 | ||
427 | @li An error occurs. | |
428 | ||
92f5a8d4 TL |
429 | This operation is implemented in terms of one or more calls to the stream's |
430 | `read_some` function. The implementation may read additional bytes from | |
431 | the stream that lie past the end of the message being read. These additional | |
432 | bytes are stored in the dynamic buffer, which must be preserved for | |
433 | subsequent reads. | |
b32b8144 | 434 | |
92f5a8d4 TL |
435 | If the end of file error is received while reading from the stream, then |
436 | the error returned from this function will be: | |
b32b8144 | 437 | |
92f5a8d4 | 438 | @li @ref error::end_of_stream if no bytes were parsed, or |
b32b8144 | 439 | |
92f5a8d4 TL |
440 | @li @ref error::partial_message if any bytes were parsed but the |
441 | message was incomplete, otherwise: | |
b32b8144 | 442 | |
92f5a8d4 TL |
443 | @li A successful result. The next attempt to read will return |
444 | @ref error::end_of_stream | |
b32b8144 | 445 | |
92f5a8d4 TL |
446 | @param stream The stream from which the data is to be read. The type must |
447 | meet the <em>SyncReadStream</em> requirements. | |
b32b8144 | 448 | |
92f5a8d4 TL |
449 | @param buffer Storage for additional bytes read by the implementation from |
450 | the stream. This is both an input and an output parameter; on entry, the | |
451 | parser will be presented with any remaining data in the dynamic buffer's | |
452 | readable bytes sequence first. The type must meet the <em>DynamicBuffer</em> | |
453 | requirements. | |
b32b8144 FG |
454 | |
455 | @param parser The parser to use. | |
456 | ||
92f5a8d4 | 457 | @return The number of bytes transferred from the stream. |
b32b8144 FG |
458 | |
459 | @throws system_error Thrown on failure. | |
460 | ||
92f5a8d4 TL |
461 | @note The function returns the total number of bytes transferred from the |
462 | stream. This may be zero for the case where there is sufficient pre-existing | |
463 | message data in the dynamic buffer. The implementation will call | |
464 | @ref basic_parser::eager with the value `true` on the parser passed in. | |
b32b8144 FG |
465 | */ |
466 | template< | |
467 | class SyncReadStream, | |
468 | class DynamicBuffer, | |
92f5a8d4 | 469 | bool isRequest> |
b32b8144 FG |
470 | std::size_t |
471 | read( | |
472 | SyncReadStream& stream, | |
473 | DynamicBuffer& buffer, | |
92f5a8d4 | 474 | basic_parser<isRequest>& parser); |
b32b8144 FG |
475 | |
476 | /** Read a complete message from a stream using a parser. | |
477 | ||
92f5a8d4 TL |
478 | This function is used to read a complete message from a stream into an |
479 | instance of @ref basic_parser. The call will block until one of the | |
480 | following conditions is true: | |
b32b8144 FG |
481 | |
482 | @li @ref basic_parser::is_done returns `true` | |
483 | ||
484 | @li An error occurs. | |
485 | ||
92f5a8d4 TL |
486 | This operation is implemented in terms of one or more calls to the stream's |
487 | `read_some` function. The implementation may read additional bytes from | |
488 | the stream that lie past the end of the message being read. These additional | |
489 | bytes are stored in the dynamic buffer, which must be preserved for | |
490 | subsequent reads. | |
b32b8144 | 491 | |
92f5a8d4 TL |
492 | If the end of file error is received while reading from the stream, then |
493 | the error returned from this function will be: | |
b32b8144 | 494 | |
92f5a8d4 | 495 | @li @ref error::end_of_stream if no bytes were parsed, or |
b32b8144 | 496 | |
92f5a8d4 TL |
497 | @li @ref error::partial_message if any bytes were parsed but the |
498 | message was incomplete, otherwise: | |
b32b8144 | 499 | |
92f5a8d4 TL |
500 | @li A successful result. The next attempt to read will return |
501 | @ref error::end_of_stream | |
b32b8144 | 502 | |
92f5a8d4 TL |
503 | @param stream The stream from which the data is to be read. The type must |
504 | meet the <em>SyncReadStream</em> requirements. | |
b32b8144 | 505 | |
92f5a8d4 TL |
506 | @param buffer Storage for additional bytes read by the implementation from |
507 | the stream. This is both an input and an output parameter; on entry, the | |
508 | parser will be presented with any remaining data in the dynamic buffer's | |
509 | readable bytes sequence first. The type must meet the <em>DynamicBuffer</em> | |
510 | requirements. | |
b32b8144 FG |
511 | |
512 | @param parser The parser to use. | |
513 | ||
514 | @param ec Set to the error, if any occurred. | |
515 | ||
92f5a8d4 | 516 | @return The number of bytes transferred from the stream. |
b32b8144 | 517 | |
92f5a8d4 TL |
518 | @note The function returns the total number of bytes transferred from the |
519 | stream. This may be zero for the case where there is sufficient pre-existing | |
520 | message data in the dynamic buffer. The implementation will call | |
521 | @ref basic_parser::eager with the value `true` on the parser passed in. | |
b32b8144 FG |
522 | */ |
523 | template< | |
524 | class SyncReadStream, | |
525 | class DynamicBuffer, | |
92f5a8d4 | 526 | bool isRequest> |
b32b8144 FG |
527 | std::size_t |
528 | read( | |
529 | SyncReadStream& stream, | |
530 | DynamicBuffer& buffer, | |
92f5a8d4 | 531 | basic_parser<isRequest>& parser, |
b32b8144 FG |
532 | error_code& ec); |
533 | ||
92f5a8d4 | 534 | /** Read a complete message asynchronously from a stream using a parser. |
b32b8144 FG |
535 | |
536 | This function is used to asynchronously read a complete message from a | |
92f5a8d4 TL |
537 | stream into an instance of @ref basic_parser. The function call always |
538 | returns immediately. The asynchronous operation will continue until one | |
539 | of the following conditions is true: | |
b32b8144 FG |
540 | |
541 | @li @ref basic_parser::is_done returns `true` | |
542 | ||
543 | @li An error occurs. | |
544 | ||
92f5a8d4 TL |
545 | This operation is implemented in terms of zero or more calls to the |
546 | next layer's `async_read_some` function, and is known as a <em>composed | |
547 | operation</em>. The program must ensure that the stream performs no other | |
548 | reads until this operation completes. The implementation may read additional | |
549 | bytes from the stream that lie past the end of the message being read. | |
550 | These additional bytes are stored in the dynamic buffer, which must be | |
551 | preserved for subsequent reads. | |
b32b8144 | 552 | |
92f5a8d4 TL |
553 | If the end of file error is received while reading from the stream, then |
554 | the error returned from this function will be: | |
b32b8144 | 555 | |
92f5a8d4 | 556 | @li @ref error::end_of_stream if no bytes were parsed, or |
b32b8144 | 557 | |
92f5a8d4 TL |
558 | @li @ref error::partial_message if any bytes were parsed but the |
559 | message was incomplete, otherwise: | |
b32b8144 | 560 | |
92f5a8d4 TL |
561 | @li A successful result. The next attempt to read will return |
562 | @ref error::end_of_stream | |
b32b8144 | 563 | |
92f5a8d4 TL |
564 | @param stream The stream from which the data is to be read. The type |
565 | must meet the <em>AsyncReadStream</em> requirements. | |
b32b8144 | 566 | |
92f5a8d4 TL |
567 | @param buffer Storage for additional bytes read by the implementation from |
568 | the stream. This is both an input and an output parameter; on entry, the | |
569 | parser will be presented with any remaining data in the dynamic buffer's | |
570 | readable bytes sequence first. The type must meet the <em>DynamicBuffer</em> | |
571 | requirements. The object must remain valid at least until the handler | |
572 | is called; ownership is not transferred. | |
b32b8144 | 573 | |
92f5a8d4 TL |
574 | @param parser The parser to use. The object must remain valid at least until |
575 | the handler is called; ownership is not transferred. | |
576 | ||
577 | @param handler The completion handler to invoke when the operation | |
578 | completes. The implementation takes ownership of the handler by | |
579 | performing a decay-copy. The equivalent function signature of | |
580 | the handler must be: | |
581 | @code | |
582 | void handler( | |
583 | error_code const& error, // result of operation | |
584 | std::size_t bytes_transferred // the total number of bytes transferred from the stream | |
585 | ); | |
586 | @endcode | |
b32b8144 FG |
587 | Regardless of whether the asynchronous operation completes |
588 | immediately or not, the handler will not be invoked from within | |
589 | this function. Invocation of the handler will be performed in a | |
92f5a8d4 | 590 | manner equivalent to using `net::post`. |
b32b8144 | 591 | |
92f5a8d4 TL |
592 | @note The completion handler will receive as a parameter the total number |
593 | of bytes transferred from the stream. This may be zero for the case where | |
594 | there is sufficient pre-existing message data in the dynamic buffer. The | |
595 | implementation will call @ref basic_parser::eager with the value `true` | |
596 | on the parser passed in. | |
b32b8144 FG |
597 | */ |
598 | template< | |
599 | class AsyncReadStream, | |
600 | class DynamicBuffer, | |
92f5a8d4 TL |
601 | bool isRequest, |
602 | BOOST_BEAST_ASYNC_TPARAM2 ReadHandler = | |
603 | net::default_completion_token_t< | |
604 | executor_type<AsyncReadStream>>> | |
605 | BOOST_BEAST_ASYNC_RESULT2(ReadHandler) | |
b32b8144 FG |
606 | async_read( |
607 | AsyncReadStream& stream, | |
608 | DynamicBuffer& buffer, | |
92f5a8d4 TL |
609 | basic_parser<isRequest>& parser, |
610 | ReadHandler&& handler = | |
611 | net::default_completion_token_t< | |
612 | executor_type<AsyncReadStream>>{}); | |
b32b8144 FG |
613 | |
614 | //------------------------------------------------------------------------------ | |
615 | ||
616 | /** Read a complete message from a stream. | |
617 | ||
92f5a8d4 TL |
618 | This function is used to read a complete message from a stream into an |
619 | instance of @ref message. The call will block until one of the following | |
620 | conditions is true: | |
b32b8144 | 621 | |
92f5a8d4 | 622 | @li The entire message is read in. |
b32b8144 FG |
623 | |
624 | @li An error occurs. | |
625 | ||
92f5a8d4 TL |
626 | This operation is implemented in terms of one or more calls to the stream's |
627 | `read_some` function. The implementation may read additional bytes from | |
628 | the stream that lie past the end of the message being read. These additional | |
629 | bytes are stored in the dynamic buffer, which must be preserved for | |
630 | subsequent reads. | |
b32b8144 | 631 | |
92f5a8d4 TL |
632 | If the end of file error is received while reading from the stream, then |
633 | the error returned from this function will be: | |
b32b8144 | 634 | |
92f5a8d4 | 635 | @li @ref error::end_of_stream if no bytes were parsed, or |
b32b8144 | 636 | |
92f5a8d4 TL |
637 | @li @ref error::partial_message if any bytes were parsed but the |
638 | message was incomplete, otherwise: | |
b32b8144 | 639 | |
92f5a8d4 TL |
640 | @li A successful result. The next attempt to read will return |
641 | @ref error::end_of_stream | |
b32b8144 | 642 | |
92f5a8d4 TL |
643 | @param stream The stream from which the data is to be read. The type must |
644 | meet the <em>SyncReadStream</em> requirements. | |
b32b8144 | 645 | |
92f5a8d4 TL |
646 | @param buffer Storage for additional bytes read by the implementation from |
647 | the stream. This is both an input and an output parameter; on entry, the | |
648 | parser will be presented with any remaining data in the dynamic buffer's | |
649 | readable bytes sequence first. The type must meet the <em>DynamicBuffer</em> | |
650 | requirements. | |
b32b8144 | 651 | |
92f5a8d4 TL |
652 | @param msg The container in which to store the message contents. This |
653 | message container should not have previous contents, otherwise the behavior | |
654 | is undefined. The type must be meet the <em>MoveAssignable</em> and | |
655 | <em>MoveConstructible</em> requirements. | |
b32b8144 | 656 | |
92f5a8d4 | 657 | @return The number of bytes transferred from the stream. |
b32b8144 FG |
658 | |
659 | @throws system_error Thrown on failure. | |
92f5a8d4 TL |
660 | |
661 | @note The function returns the total number of bytes transferred from the | |
662 | stream. This may be zero for the case where there is sufficient pre-existing | |
663 | message data in the dynamic buffer. The implementation will call | |
664 | @ref basic_parser::eager with the value `true` on the parser passed in. | |
b32b8144 FG |
665 | */ |
666 | template< | |
667 | class SyncReadStream, | |
668 | class DynamicBuffer, | |
669 | bool isRequest, class Body, class Allocator> | |
670 | std::size_t | |
671 | read( | |
672 | SyncReadStream& stream, | |
673 | DynamicBuffer& buffer, | |
674 | message<isRequest, Body, basic_fields<Allocator>>& msg); | |
675 | ||
676 | /** Read a complete message from a stream. | |
677 | ||
92f5a8d4 TL |
678 | This function is used to read a complete message from a stream into an |
679 | instance of @ref message. The call will block until one of the following | |
680 | conditions is true: | |
b32b8144 | 681 | |
92f5a8d4 | 682 | @li The entire message is read in. |
b32b8144 FG |
683 | |
684 | @li An error occurs. | |
685 | ||
92f5a8d4 TL |
686 | This operation is implemented in terms of one or more calls to the stream's |
687 | `read_some` function. The implementation may read additional bytes from | |
688 | the stream that lie past the end of the message being read. These additional | |
689 | bytes are stored in the dynamic buffer, which must be preserved for | |
690 | subsequent reads. | |
b32b8144 | 691 | |
92f5a8d4 TL |
692 | If the end of file error is received while reading from the stream, then |
693 | the error returned from this function will be: | |
b32b8144 | 694 | |
92f5a8d4 | 695 | @li @ref error::end_of_stream if no bytes were parsed, or |
b32b8144 | 696 | |
92f5a8d4 TL |
697 | @li @ref error::partial_message if any bytes were parsed but the |
698 | message was incomplete, otherwise: | |
b32b8144 | 699 | |
92f5a8d4 TL |
700 | @li A successful result. The next attempt to read will return |
701 | @ref error::end_of_stream | |
b32b8144 | 702 | |
92f5a8d4 TL |
703 | @param stream The stream from which the data is to be read. The type must |
704 | meet the <em>SyncReadStream</em> requirements. | |
b32b8144 | 705 | |
92f5a8d4 TL |
706 | @param buffer Storage for additional bytes read by the implementation from |
707 | the stream. This is both an input and an output parameter; on entry, the | |
708 | parser will be presented with any remaining data in the dynamic buffer's | |
709 | readable bytes sequence first. The type must meet the <em>DynamicBuffer</em> | |
710 | requirements. | |
b32b8144 | 711 | |
92f5a8d4 TL |
712 | @param msg The container in which to store the message contents. This |
713 | message container should not have previous contents, otherwise the behavior | |
714 | is undefined. The type must be meet the <em>MoveAssignable</em> and | |
715 | <em>MoveConstructible</em> requirements. | |
b32b8144 FG |
716 | |
717 | @param ec Set to the error, if any occurred. | |
718 | ||
92f5a8d4 TL |
719 | @return The number of bytes transferred from the stream. |
720 | ||
721 | @note The function returns the total number of bytes transferred from the | |
722 | stream. This may be zero for the case where there is sufficient pre-existing | |
723 | message data in the dynamic buffer. The implementation will call | |
724 | @ref basic_parser::eager with the value `true` on the parser passed in. | |
b32b8144 FG |
725 | */ |
726 | template< | |
727 | class SyncReadStream, | |
728 | class DynamicBuffer, | |
729 | bool isRequest, class Body, class Allocator> | |
730 | std::size_t | |
731 | read( | |
732 | SyncReadStream& stream, | |
733 | DynamicBuffer& buffer, | |
734 | message<isRequest, Body, basic_fields<Allocator>>& msg, | |
735 | error_code& ec); | |
736 | ||
92f5a8d4 | 737 | /** Read a complete message asynchronously from a stream. |
b32b8144 FG |
738 | |
739 | This function is used to asynchronously read a complete message from a | |
92f5a8d4 TL |
740 | stream into an instance of @ref message. The function call always returns |
741 | immediately. The asynchronous operation will continue until one of the | |
742 | following conditions is true: | |
b32b8144 | 743 | |
92f5a8d4 | 744 | @li The entire message is read in. |
b32b8144 FG |
745 | |
746 | @li An error occurs. | |
747 | ||
92f5a8d4 TL |
748 | This operation is implemented in terms of zero or more calls to the |
749 | next layer's `async_read_some` function, and is known as a <em>composed | |
750 | operation</em>. The program must ensure that the stream performs no other | |
751 | reads until this operation completes. The implementation may read additional | |
752 | bytes from the stream that lie past the end of the message being read. | |
753 | These additional bytes are stored in the dynamic buffer, which must be | |
754 | preserved for subsequent reads. | |
755 | ||
756 | If the end of file error is received while reading from the stream, then | |
757 | the error returned from this function will be: | |
758 | ||
759 | @li @ref error::end_of_stream if no bytes were parsed, or | |
760 | ||
761 | @li @ref error::partial_message if any bytes were parsed but the | |
762 | message was incomplete, otherwise: | |
763 | ||
764 | @li A successful result. The next attempt to read will return | |
765 | @ref error::end_of_stream | |
766 | ||
767 | @param stream The stream from which the data is to be read. The type | |
768 | must meet the <em>AsyncReadStream</em> requirements. | |
769 | ||
770 | @param buffer Storage for additional bytes read by the implementation from | |
771 | the stream. This is both an input and an output parameter; on entry, the | |
772 | parser will be presented with any remaining data in the dynamic buffer's | |
773 | readable bytes sequence first. The type must meet the <em>DynamicBuffer</em> | |
774 | requirements. The object must remain valid at least until the handler | |
775 | is called; ownership is not transferred. | |
776 | ||
777 | @param msg The container in which to store the message contents. This | |
778 | message container should not have previous contents, otherwise the behavior | |
779 | is undefined. The type must be meet the <em>MoveAssignable</em> and | |
780 | <em>MoveConstructible</em> requirements. The object must remain valid | |
781 | at least until the handler is called; ownership is not transferred. | |
782 | ||
783 | @param handler The completion handler to invoke when the operation | |
784 | completes. The implementation takes ownership of the handler by | |
785 | performing a decay-copy. The equivalent function signature of | |
786 | the handler must be: | |
787 | @code | |
788 | void handler( | |
789 | error_code const& error, // result of operation | |
790 | std::size_t bytes_transferred // the total number of bytes transferred from the stream | |
791 | ); | |
792 | @endcode | |
b32b8144 FG |
793 | Regardless of whether the asynchronous operation completes |
794 | immediately or not, the handler will not be invoked from within | |
795 | this function. Invocation of the handler will be performed in a | |
92f5a8d4 TL |
796 | manner equivalent to using `net::post`. |
797 | ||
798 | @note The completion handler will receive as a parameter the total number | |
799 | of bytes transferred from the stream. This may be zero for the case where | |
800 | there is sufficient pre-existing message data in the dynamic buffer. The | |
801 | implementation will call @ref basic_parser::eager with the value `true` | |
802 | on the parser passed in. | |
b32b8144 FG |
803 | */ |
804 | template< | |
805 | class AsyncReadStream, | |
806 | class DynamicBuffer, | |
807 | bool isRequest, class Body, class Allocator, | |
92f5a8d4 TL |
808 | BOOST_BEAST_ASYNC_TPARAM2 ReadHandler = |
809 | net::default_completion_token_t< | |
810 | executor_type<AsyncReadStream>>> | |
811 | BOOST_BEAST_ASYNC_RESULT2(ReadHandler) | |
b32b8144 FG |
812 | async_read( |
813 | AsyncReadStream& stream, | |
814 | DynamicBuffer& buffer, | |
815 | message<isRequest, Body, basic_fields<Allocator>>& msg, | |
92f5a8d4 TL |
816 | ReadHandler&& handler = |
817 | net::default_completion_token_t< | |
818 | executor_type<AsyncReadStream>>{}); | |
b32b8144 FG |
819 | |
820 | } // http | |
821 | } // beast | |
822 | } // boost | |
823 | ||
92f5a8d4 | 824 | #include <boost/beast/http/impl/read.hpp> |
b32b8144 FG |
825 | |
826 | #endif |