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