1//
2// read.hpp
3// ~~~~~~~~
4//
5// Copyright (c) 2003-2024 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6//
7// Distributed under the Boost Software License, Version 1.0. (See accompanying
8// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
9//
10
11#ifndef BOOST_ASIO_READ_HPP
12#define BOOST_ASIO_READ_HPP
13
14#if defined(_MSC_VER) && (_MSC_VER >= 1200)
15# pragma once
16#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17
18#include <boost/asio/detail/config.hpp>
19#include <cstddef>
20#include <boost/asio/async_result.hpp>
21#include <boost/asio/buffer.hpp>
22#include <boost/asio/completion_condition.hpp>
23#include <boost/asio/error.hpp>
24
25#if !defined(BOOST_ASIO_NO_EXTENSIONS)
26# include <boost/asio/basic_streambuf_fwd.hpp>
27#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
28
29#include <boost/asio/detail/push_options.hpp>
30
31namespace boost {
32namespace asio {
33namespace detail {
34
35template <typename> class initiate_async_read;
36#if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
37template <typename> class initiate_async_read_dynbuf_v1;
38#endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
39template <typename> class initiate_async_read_dynbuf_v2;
40
41} // namespace detail
42
43/**
44 * @defgroup read boost::asio::read
45 *
46 * @brief The @c read function is a composed operation that reads a certain
47 * amount of data from a stream before returning.
48 */
49/*@{*/
50
51/// Attempt to read a certain amount of data from a stream before returning.
52/**
53 * This function is used to read a certain number of bytes of data from a
54 * stream. The call will block until one of the following conditions is true:
55 *
56 * @li The supplied buffers are full. That is, the bytes transferred is equal to
57 * the sum of the buffer sizes.
58 *
59 * @li An error occurred.
60 *
61 * This operation is implemented in terms of zero or more calls to the stream's
62 * read_some function.
63 *
64 * @param s The stream from which the data is to be read. The type must support
65 * the SyncReadStream concept.
66 *
67 * @param buffers One or more buffers into which the data will be read. The sum
68 * of the buffer sizes indicates the maximum number of bytes to read from the
69 * stream.
70 *
71 * @returns The number of bytes transferred.
72 *
73 * @throws boost::system::system_error Thrown on failure.
74 *
75 * @par Example
76 * To read into a single data buffer use the @ref buffer function as follows:
77 * @code boost::asio::read(s, boost::asio::buffer(data, size)); @endcode
78 * See the @ref buffer documentation for information on reading into multiple
79 * buffers in one go, and how to use it with arrays, boost::array or
80 * std::vector.
81 *
82 * @note This overload is equivalent to calling:
83 * @code boost::asio::read(
84 * s, buffers,
85 * boost::asio::transfer_all()); @endcode
86 */
87template <typename SyncReadStream, typename MutableBufferSequence>
88std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
89 constraint_t<
90 is_mutable_buffer_sequence<MutableBufferSequence>::value
91 > = 0);
92
93/// Attempt to read a certain amount of data from a stream before returning.
94/**
95 * This function is used to read a certain number of bytes of data from a
96 * stream. The call will block until one of the following conditions is true:
97 *
98 * @li The supplied buffers are full. That is, the bytes transferred is equal to
99 * the sum of the buffer sizes.
100 *
101 * @li An error occurred.
102 *
103 * This operation is implemented in terms of zero or more calls to the stream's
104 * read_some function.
105 *
106 * @param s The stream from which the data is to be read. The type must support
107 * the SyncReadStream concept.
108 *
109 * @param buffers One or more buffers into which the data will be read. The sum
110 * of the buffer sizes indicates the maximum number of bytes to read from the
111 * stream.
112 *
113 * @param ec Set to indicate what error occurred, if any.
114 *
115 * @returns The number of bytes transferred.
116 *
117 * @par Example
118 * To read into a single data buffer use the @ref buffer function as follows:
119 * @code boost::asio::read(s, boost::asio::buffer(data, size), ec); @endcode
120 * See the @ref buffer documentation for information on reading into multiple
121 * buffers in one go, and how to use it with arrays, boost::array or
122 * std::vector.
123 *
124 * @note This overload is equivalent to calling:
125 * @code boost::asio::read(
126 * s, buffers,
127 * boost::asio::transfer_all(), ec); @endcode
128 */
129template <typename SyncReadStream, typename MutableBufferSequence>
130std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
131 boost::system::error_code& ec,
132 constraint_t<
133 is_mutable_buffer_sequence<MutableBufferSequence>::value
134 > = 0);
135
136/// Attempt to read a certain amount of data from a stream before returning.
137/**
138 * This function is used to read a certain number of bytes of data from a
139 * stream. The call will block until one of the following conditions is true:
140 *
141 * @li The supplied buffers are full. That is, the bytes transferred is equal to
142 * the sum of the buffer sizes.
143 *
144 * @li The completion_condition function object returns 0.
145 *
146 * This operation is implemented in terms of zero or more calls to the stream's
147 * read_some function.
148 *
149 * @param s The stream from which the data is to be read. The type must support
150 * the SyncReadStream concept.
151 *
152 * @param buffers One or more buffers into which the data will be read. The sum
153 * of the buffer sizes indicates the maximum number of bytes to read from the
154 * stream.
155 *
156 * @param completion_condition The function object to be called to determine
157 * whether the read operation is complete. The signature of the function object
158 * must be:
159 * @code std::size_t completion_condition(
160 * // Result of latest read_some operation.
161 * const boost::system::error_code& error,
162 *
163 * // Number of bytes transferred so far.
164 * std::size_t bytes_transferred
165 * ); @endcode
166 * A return value of 0 indicates that the read operation is complete. A non-zero
167 * return value indicates the maximum number of bytes to be read on the next
168 * call to the stream's read_some function.
169 *
170 * @returns The number of bytes transferred.
171 *
172 * @throws boost::system::system_error Thrown on failure.
173 *
174 * @par Example
175 * To read into a single data buffer use the @ref buffer function as follows:
176 * @code boost::asio::read(s, boost::asio::buffer(data, size),
177 * boost::asio::transfer_at_least(32)); @endcode
178 * See the @ref buffer documentation for information on reading into multiple
179 * buffers in one go, and how to use it with arrays, boost::array or
180 * std::vector.
181 */
182template <typename SyncReadStream, typename MutableBufferSequence,
183 typename CompletionCondition>
184std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
185 CompletionCondition completion_condition,
186 constraint_t<
187 is_mutable_buffer_sequence<MutableBufferSequence>::value
188 > = 0);
189
190/// Attempt to read a certain amount of data from a stream before returning.
191/**
192 * This function is used to read a certain number of bytes of data from a
193 * stream. The call will block until one of the following conditions is true:
194 *
195 * @li The supplied buffers are full. That is, the bytes transferred is equal to
196 * the sum of the buffer sizes.
197 *
198 * @li The completion_condition function object returns 0.
199 *
200 * This operation is implemented in terms of zero or more calls to the stream's
201 * read_some function.
202 *
203 * @param s The stream from which the data is to be read. The type must support
204 * the SyncReadStream concept.
205 *
206 * @param buffers One or more buffers into which the data will be read. The sum
207 * of the buffer sizes indicates the maximum number of bytes to read from the
208 * stream.
209 *
210 * @param completion_condition The function object to be called to determine
211 * whether the read operation is complete. The signature of the function object
212 * must be:
213 * @code std::size_t completion_condition(
214 * // Result of latest read_some operation.
215 * const boost::system::error_code& error,
216 *
217 * // Number of bytes transferred so far.
218 * std::size_t bytes_transferred
219 * ); @endcode
220 * A return value of 0 indicates that the read operation is complete. A non-zero
221 * return value indicates the maximum number of bytes to be read on the next
222 * call to the stream's read_some function.
223 *
224 * @param ec Set to indicate what error occurred, if any.
225 *
226 * @returns The number of bytes read. If an error occurs, returns the total
227 * number of bytes successfully transferred prior to the error.
228 */
229template <typename SyncReadStream, typename MutableBufferSequence,
230 typename CompletionCondition>
231std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
232 CompletionCondition completion_condition, boost::system::error_code& ec,
233 constraint_t<
234 is_mutable_buffer_sequence<MutableBufferSequence>::value
235 > = 0);
236
237#if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
238
239/// Attempt to read a certain amount of data from a stream before returning.
240/**
241 * This function is used to read a certain number of bytes of data from a
242 * stream. The call will block until one of the following conditions is true:
243 *
244 * @li The specified dynamic buffer sequence is full (that is, it has reached
245 * maximum size).
246 *
247 * @li An error occurred.
248 *
249 * This operation is implemented in terms of zero or more calls to the stream's
250 * read_some function.
251 *
252 * @param s The stream from which the data is to be read. The type must support
253 * the SyncReadStream concept.
254 *
255 * @param buffers The dynamic buffer sequence into which the data will be read.
256 *
257 * @returns The number of bytes transferred.
258 *
259 * @throws boost::system::system_error Thrown on failure.
260 *
261 * @note This overload is equivalent to calling:
262 * @code boost::asio::read(
263 * s, buffers,
264 * boost::asio::transfer_all()); @endcode
265 */
266template <typename SyncReadStream, typename DynamicBuffer_v1>
267std::size_t read(SyncReadStream& s,
268 DynamicBuffer_v1&& buffers,
269 constraint_t<
270 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
271 > = 0,
272 constraint_t<
273 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
274 > = 0);
275
276/// Attempt to read a certain amount of data from a stream before returning.
277/**
278 * This function is used to read a certain number of bytes of data from a
279 * stream. The call will block until one of the following conditions is true:
280 *
281 * @li The supplied buffer is full (that is, it has reached maximum size).
282 *
283 * @li An error occurred.
284 *
285 * This operation is implemented in terms of zero or more calls to the stream's
286 * read_some function.
287 *
288 * @param s The stream from which the data is to be read. The type must support
289 * the SyncReadStream concept.
290 *
291 * @param buffers The dynamic buffer sequence into which the data will be read.
292 *
293 * @param ec Set to indicate what error occurred, if any.
294 *
295 * @returns The number of bytes transferred.
296 *
297 * @note This overload is equivalent to calling:
298 * @code boost::asio::read(
299 * s, buffers,
300 * boost::asio::transfer_all(), ec); @endcode
301 */
302template <typename SyncReadStream, typename DynamicBuffer_v1>
303std::size_t read(SyncReadStream& s,
304 DynamicBuffer_v1&& buffers,
305 boost::system::error_code& ec,
306 constraint_t<
307 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
308 > = 0,
309 constraint_t<
310 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
311 > = 0);
312
313/// Attempt to read a certain amount of data from a stream before returning.
314/**
315 * This function is used to read a certain number of bytes of data from a
316 * stream. The call will block until one of the following conditions is true:
317 *
318 * @li The specified dynamic buffer sequence is full (that is, it has reached
319 * maximum size).
320 *
321 * @li The completion_condition function object returns 0.
322 *
323 * This operation is implemented in terms of zero or more calls to the stream's
324 * read_some function.
325 *
326 * @param s The stream from which the data is to be read. The type must support
327 * the SyncReadStream concept.
328 *
329 * @param buffers The dynamic buffer sequence into which the data will be read.
330 *
331 * @param completion_condition The function object to be called to determine
332 * whether the read operation is complete. The signature of the function object
333 * must be:
334 * @code std::size_t completion_condition(
335 * // Result of latest read_some operation.
336 * const boost::system::error_code& error,
337 *
338 * // Number of bytes transferred so far.
339 * std::size_t bytes_transferred
340 * ); @endcode
341 * A return value of 0 indicates that the read operation is complete. A non-zero
342 * return value indicates the maximum number of bytes to be read on the next
343 * call to the stream's read_some function.
344 *
345 * @returns The number of bytes transferred.
346 *
347 * @throws boost::system::system_error Thrown on failure.
348 */
349template <typename SyncReadStream, typename DynamicBuffer_v1,
350 typename CompletionCondition>
351std::size_t read(SyncReadStream& s,
352 DynamicBuffer_v1&& buffers,
353 CompletionCondition completion_condition,
354 constraint_t<
355 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
356 > = 0,
357 constraint_t<
358 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
359 > = 0);
360
361/// Attempt to read a certain amount of data from a stream before returning.
362/**
363 * This function is used to read a certain number of bytes of data from a
364 * stream. The call will block until one of the following conditions is true:
365 *
366 * @li The specified dynamic buffer sequence is full (that is, it has reached
367 * maximum size).
368 *
369 * @li The completion_condition function object returns 0.
370 *
371 * This operation is implemented in terms of zero or more calls to the stream's
372 * read_some function.
373 *
374 * @param s The stream from which the data is to be read. The type must support
375 * the SyncReadStream concept.
376 *
377 * @param buffers The dynamic buffer sequence into which the data will be read.
378 *
379 * @param completion_condition The function object to be called to determine
380 * whether the read operation is complete. The signature of the function object
381 * must be:
382 * @code std::size_t completion_condition(
383 * // Result of latest read_some operation.
384 * const boost::system::error_code& error,
385 *
386 * // Number of bytes transferred so far.
387 * std::size_t bytes_transferred
388 * ); @endcode
389 * A return value of 0 indicates that the read operation is complete. A non-zero
390 * return value indicates the maximum number of bytes to be read on the next
391 * call to the stream's read_some function.
392 *
393 * @param ec Set to indicate what error occurred, if any.
394 *
395 * @returns The number of bytes read. If an error occurs, returns the total
396 * number of bytes successfully transferred prior to the error.
397 */
398template <typename SyncReadStream, typename DynamicBuffer_v1,
399 typename CompletionCondition>
400std::size_t read(SyncReadStream& s,
401 DynamicBuffer_v1&& buffers,
402 CompletionCondition completion_condition, boost::system::error_code& ec,
403 constraint_t<
404 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
405 > = 0,
406 constraint_t<
407 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
408 > = 0);
409
410#if !defined(BOOST_ASIO_NO_EXTENSIONS)
411#if !defined(BOOST_ASIO_NO_IOSTREAM)
412
413/// Attempt to read a certain amount of data from a stream before returning.
414/**
415 * This function is used to read a certain number of bytes of data from a
416 * stream. The call will block until one of the following conditions is true:
417 *
418 * @li The supplied buffer is full (that is, it has reached maximum size).
419 *
420 * @li An error occurred.
421 *
422 * This operation is implemented in terms of zero or more calls to the stream's
423 * read_some function.
424 *
425 * @param s The stream from which the data is to be read. The type must support
426 * the SyncReadStream concept.
427 *
428 * @param b The basic_streambuf object into which the data will be read.
429 *
430 * @returns The number of bytes transferred.
431 *
432 * @throws boost::system::system_error Thrown on failure.
433 *
434 * @note This overload is equivalent to calling:
435 * @code boost::asio::read(
436 * s, b,
437 * boost::asio::transfer_all()); @endcode
438 */
439template <typename SyncReadStream, typename Allocator>
440std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b);
441
442/// Attempt to read a certain amount of data from a stream before returning.
443/**
444 * This function is used to read a certain number of bytes of data from a
445 * stream. The call will block until one of the following conditions is true:
446 *
447 * @li The supplied buffer is full (that is, it has reached maximum size).
448 *
449 * @li An error occurred.
450 *
451 * This operation is implemented in terms of zero or more calls to the stream's
452 * read_some function.
453 *
454 * @param s The stream from which the data is to be read. The type must support
455 * the SyncReadStream concept.
456 *
457 * @param b The basic_streambuf object into which the data will be read.
458 *
459 * @param ec Set to indicate what error occurred, if any.
460 *
461 * @returns The number of bytes transferred.
462 *
463 * @note This overload is equivalent to calling:
464 * @code boost::asio::read(
465 * s, b,
466 * boost::asio::transfer_all(), ec); @endcode
467 */
468template <typename SyncReadStream, typename Allocator>
469std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
470 boost::system::error_code& ec);
471
472/// Attempt to read a certain amount of data from a stream before returning.
473/**
474 * This function is used to read a certain number of bytes of data from a
475 * stream. The call will block until one of the following conditions is true:
476 *
477 * @li The supplied buffer is full (that is, it has reached maximum size).
478 *
479 * @li The completion_condition function object returns 0.
480 *
481 * This operation is implemented in terms of zero or more calls to the stream's
482 * read_some function.
483 *
484 * @param s The stream from which the data is to be read. The type must support
485 * the SyncReadStream concept.
486 *
487 * @param b The basic_streambuf object into which the data will be read.
488 *
489 * @param completion_condition The function object to be called to determine
490 * whether the read operation is complete. The signature of the function object
491 * must be:
492 * @code std::size_t completion_condition(
493 * // Result of latest read_some operation.
494 * const boost::system::error_code& error,
495 *
496 * // Number of bytes transferred so far.
497 * std::size_t bytes_transferred
498 * ); @endcode
499 * A return value of 0 indicates that the read operation is complete. A non-zero
500 * return value indicates the maximum number of bytes to be read on the next
501 * call to the stream's read_some function.
502 *
503 * @returns The number of bytes transferred.
504 *
505 * @throws boost::system::system_error Thrown on failure.
506 */
507template <typename SyncReadStream, typename Allocator,
508 typename CompletionCondition>
509std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
510 CompletionCondition completion_condition);
511
512/// Attempt to read a certain amount of data from a stream before returning.
513/**
514 * This function is used to read a certain number of bytes of data from a
515 * stream. The call will block until one of the following conditions is true:
516 *
517 * @li The supplied buffer is full (that is, it has reached maximum size).
518 *
519 * @li The completion_condition function object returns 0.
520 *
521 * This operation is implemented in terms of zero or more calls to the stream's
522 * read_some function.
523 *
524 * @param s The stream from which the data is to be read. The type must support
525 * the SyncReadStream concept.
526 *
527 * @param b The basic_streambuf object into which the data will be read.
528 *
529 * @param completion_condition The function object to be called to determine
530 * whether the read operation is complete. The signature of the function object
531 * must be:
532 * @code std::size_t completion_condition(
533 * // Result of latest read_some operation.
534 * const boost::system::error_code& error,
535 *
536 * // Number of bytes transferred so far.
537 * std::size_t bytes_transferred
538 * ); @endcode
539 * A return value of 0 indicates that the read operation is complete. A non-zero
540 * return value indicates the maximum number of bytes to be read on the next
541 * call to the stream's read_some function.
542 *
543 * @param ec Set to indicate what error occurred, if any.
544 *
545 * @returns The number of bytes read. If an error occurs, returns the total
546 * number of bytes successfully transferred prior to the error.
547 */
548template <typename SyncReadStream, typename Allocator,
549 typename CompletionCondition>
550std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
551 CompletionCondition completion_condition, boost::system::error_code& ec);
552
553#endif // !defined(BOOST_ASIO_NO_IOSTREAM)
554#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
555#endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
556
557/// Attempt to read a certain amount of data from a stream before returning.
558/**
559 * This function is used to read a certain number of bytes of data from a
560 * stream. The call will block until one of the following conditions is true:
561 *
562 * @li The specified dynamic buffer sequence is full (that is, it has reached
563 * maximum size).
564 *
565 * @li An error occurred.
566 *
567 * This operation is implemented in terms of zero or more calls to the stream's
568 * read_some function.
569 *
570 * @param s The stream from which the data is to be read. The type must support
571 * the SyncReadStream concept.
572 *
573 * @param buffers The dynamic buffer sequence into which the data will be read.
574 *
575 * @returns The number of bytes transferred.
576 *
577 * @throws boost::system::system_error Thrown on failure.
578 *
579 * @note This overload is equivalent to calling:
580 * @code boost::asio::read(
581 * s, buffers,
582 * boost::asio::transfer_all()); @endcode
583 */
584template <typename SyncReadStream, typename DynamicBuffer_v2>
585std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
586 constraint_t<
587 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
588 > = 0);
589
590/// Attempt to read a certain amount of data from a stream before returning.
591/**
592 * This function is used to read a certain number of bytes of data from a
593 * stream. The call will block until one of the following conditions is true:
594 *
595 * @li The supplied buffer is full (that is, it has reached maximum size).
596 *
597 * @li An error occurred.
598 *
599 * This operation is implemented in terms of zero or more calls to the stream's
600 * read_some function.
601 *
602 * @param s The stream from which the data is to be read. The type must support
603 * the SyncReadStream concept.
604 *
605 * @param buffers The dynamic buffer sequence into which the data will be read.
606 *
607 * @param ec Set to indicate what error occurred, if any.
608 *
609 * @returns The number of bytes transferred.
610 *
611 * @note This overload is equivalent to calling:
612 * @code boost::asio::read(
613 * s, buffers,
614 * boost::asio::transfer_all(), ec); @endcode
615 */
616template <typename SyncReadStream, typename DynamicBuffer_v2>
617std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
618 boost::system::error_code& ec,
619 constraint_t<
620 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
621 > = 0);
622
623/// Attempt to read a certain amount of data from a stream before returning.
624/**
625 * This function is used to read a certain number of bytes of data from a
626 * stream. The call will block until one of the following conditions is true:
627 *
628 * @li The specified dynamic buffer sequence is full (that is, it has reached
629 * maximum size).
630 *
631 * @li The completion_condition function object returns 0.
632 *
633 * This operation is implemented in terms of zero or more calls to the stream's
634 * read_some function.
635 *
636 * @param s The stream from which the data is to be read. The type must support
637 * the SyncReadStream concept.
638 *
639 * @param buffers The dynamic buffer sequence into which the data will be read.
640 *
641 * @param completion_condition The function object to be called to determine
642 * whether the read operation is complete. The signature of the function object
643 * must be:
644 * @code std::size_t completion_condition(
645 * // Result of latest read_some operation.
646 * const boost::system::error_code& error,
647 *
648 * // Number of bytes transferred so far.
649 * std::size_t bytes_transferred
650 * ); @endcode
651 * A return value of 0 indicates that the read operation is complete. A non-zero
652 * return value indicates the maximum number of bytes to be read on the next
653 * call to the stream's read_some function.
654 *
655 * @returns The number of bytes transferred.
656 *
657 * @throws boost::system::system_error Thrown on failure.
658 */
659template <typename SyncReadStream, typename DynamicBuffer_v2,
660 typename CompletionCondition>
661std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
662 CompletionCondition completion_condition,
663 constraint_t<
664 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
665 > = 0);
666
667/// Attempt to read a certain amount of data from a stream before returning.
668/**
669 * This function is used to read a certain number of bytes of data from a
670 * stream. The call will block until one of the following conditions is true:
671 *
672 * @li The specified dynamic buffer sequence is full (that is, it has reached
673 * maximum size).
674 *
675 * @li The completion_condition function object returns 0.
676 *
677 * This operation is implemented in terms of zero or more calls to the stream's
678 * read_some function.
679 *
680 * @param s The stream from which the data is to be read. The type must support
681 * the SyncReadStream concept.
682 *
683 * @param buffers The dynamic buffer sequence into which the data will be read.
684 *
685 * @param completion_condition The function object to be called to determine
686 * whether the read operation is complete. The signature of the function object
687 * must be:
688 * @code std::size_t completion_condition(
689 * // Result of latest read_some operation.
690 * const boost::system::error_code& error,
691 *
692 * // Number of bytes transferred so far.
693 * std::size_t bytes_transferred
694 * ); @endcode
695 * A return value of 0 indicates that the read operation is complete. A non-zero
696 * return value indicates the maximum number of bytes to be read on the next
697 * call to the stream's read_some function.
698 *
699 * @param ec Set to indicate what error occurred, if any.
700 *
701 * @returns The number of bytes read. If an error occurs, returns the total
702 * number of bytes successfully transferred prior to the error.
703 */
704template <typename SyncReadStream, typename DynamicBuffer_v2,
705 typename CompletionCondition>
706std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
707 CompletionCondition completion_condition, boost::system::error_code& ec,
708 constraint_t<
709 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
710 > = 0);
711
712/*@}*/
713/**
714 * @defgroup async_read boost::asio::async_read
715 *
716 * @brief The @c async_read function is a composed asynchronous operation that
717 * reads a certain amount of data from a stream before completion.
718 */
719/*@{*/
720
721/// Start an asynchronous operation to read a certain amount of data from a
722/// stream.
723/**
724 * This function is used to asynchronously read a certain number of bytes of
725 * data from a stream. It is an initiating function for an @ref
726 * asynchronous_operation, and always returns immediately. The asynchronous
727 * operation will continue until one of the following conditions is true:
728 *
729 * @li The supplied buffers are full. That is, the bytes transferred is equal to
730 * the sum of the buffer sizes.
731 *
732 * @li An error occurred.
733 *
734 * This operation is implemented in terms of zero or more calls to the stream's
735 * async_read_some function, and is known as a <em>composed operation</em>. The
736 * program must ensure that the stream performs no other read operations (such
737 * as async_read, the stream's async_read_some function, or any other composed
738 * operations that perform reads) until this operation completes.
739 *
740 * @param s The stream from which the data is to be read. The type must support
741 * the AsyncReadStream concept.
742 *
743 * @param buffers One or more buffers into which the data will be read. The sum
744 * of the buffer sizes indicates the maximum number of bytes to read from the
745 * stream. Although the buffers object may be copied as necessary, ownership of
746 * the underlying memory blocks is retained by the caller, which must guarantee
747 * that they remain valid until the completion handler is called.
748 *
749 * @param token The @ref completion_token that will be used to produce a
750 * completion handler, which will be called when the read completes.
751 * Potential completion tokens include @ref use_future, @ref use_awaitable,
752 * @ref yield_context, or a function object with the correct completion
753 * signature. The function signature of the completion handler must be:
754 * @code void handler(
755 * // Result of operation.
756 * const boost::system::error_code& error,
757 *
758 * // Number of bytes copied into the buffers. If an error
759 * // occurred, this will be the number of bytes successfully
760 * // transferred prior to the error.
761 * std::size_t bytes_transferred
762 * ); @endcode
763 * Regardless of whether the asynchronous operation completes immediately or
764 * not, the completion handler will not be invoked from within this function.
765 * On immediate completion, invocation of the handler will be performed in a
766 * manner equivalent to using boost::asio::post().
767 *
768 * @par Completion Signature
769 * @code void(boost::system::error_code, std::size_t) @endcode
770 *
771 * @par Example
772 * To read into a single data buffer use the @ref buffer function as follows:
773 * @code
774 * boost::asio::async_read(s, boost::asio::buffer(data, size), handler);
775 * @endcode
776 * See the @ref buffer documentation for information on reading into multiple
777 * buffers in one go, and how to use it with arrays, boost::array or
778 * std::vector.
779 *
780 * @note This overload is equivalent to calling:
781 * @code boost::asio::async_read(
782 * s, buffers,
783 * boost::asio::transfer_all(),
784 * handler); @endcode
785 *
786 * @par Per-Operation Cancellation
787 * This asynchronous operation supports cancellation for the following
788 * boost::asio::cancellation_type values:
789 *
790 * @li @c cancellation_type::terminal
791 *
792 * @li @c cancellation_type::partial
793 *
794 * if they are also supported by the @c AsyncReadStream type's
795 * @c async_read_some operation.
796 */
797template <typename AsyncReadStream, typename MutableBufferSequence,
798 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
799 std::size_t)) ReadToken = default_completion_token_t<
800 typename AsyncReadStream::executor_type>>
801auto async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
802 ReadToken&& token = default_completion_token_t<
803 typename AsyncReadStream::executor_type>(),
804 constraint_t<
805 is_mutable_buffer_sequence<MutableBufferSequence>::value
806 > = 0)
807 -> decltype(
808 async_initiate<ReadToken,
809 void (boost::system::error_code, std::size_t)>(
810 declval<detail::initiate_async_read<AsyncReadStream>>(),
811 token, buffers, transfer_all()));
812
813/// Start an asynchronous operation to read a certain amount of data from a
814/// stream.
815/**
816 * This function is used to asynchronously read a certain number of bytes of
817 * data from a stream. It is an initiating function for an @ref
818 * asynchronous_operation, and always returns immediately. The asynchronous
819 * operation will continue until one of the following conditions is true:
820 *
821 * @li The supplied buffers are full. That is, the bytes transferred is equal to
822 * the sum of the buffer sizes.
823 *
824 * @li The completion_condition function object returns 0.
825 *
826 * @param s The stream from which the data is to be read. The type must support
827 * the AsyncReadStream concept.
828 *
829 * @param buffers One or more buffers into which the data will be read. The sum
830 * of the buffer sizes indicates the maximum number of bytes to read from the
831 * stream. Although the buffers object may be copied as necessary, ownership of
832 * the underlying memory blocks is retained by the caller, which must guarantee
833 * that they remain valid until the completion handler is called.
834 *
835 * @param completion_condition The function object to be called to determine
836 * whether the read operation is complete. The signature of the function object
837 * must be:
838 * @code std::size_t completion_condition(
839 * // Result of latest async_read_some operation.
840 * const boost::system::error_code& error,
841 *
842 * // Number of bytes transferred so far.
843 * std::size_t bytes_transferred
844 * ); @endcode
845 * A return value of 0 indicates that the read operation is complete. A non-zero
846 * return value indicates the maximum number of bytes to be read on the next
847 * call to the stream's async_read_some function.
848 *
849 * @param token The @ref completion_token that will be used to produce a
850 * completion handler, which will be called when the read completes.
851 * Potential completion tokens include @ref use_future, @ref use_awaitable,
852 * @ref yield_context, or a function object with the correct completion
853 * signature. The function signature of the completion handler must be:
854 * @code void handler(
855 * // Result of operation.
856 * const boost::system::error_code& error,
857 *
858 * // Number of bytes copied into the buffers. If an error
859 * // occurred, this will be the number of bytes successfully
860 * // transferred prior to the error.
861 * std::size_t bytes_transferred
862 * ); @endcode
863 * Regardless of whether the asynchronous operation completes immediately or
864 * not, the completion handler will not be invoked from within this function.
865 * On immediate completion, invocation of the handler will be performed in a
866 * manner equivalent to using boost::asio::post().
867 *
868 * @par Completion Signature
869 * @code void(boost::system::error_code, std::size_t) @endcode
870 *
871 * @par Example
872 * To read into a single data buffer use the @ref buffer function as follows:
873 * @code boost::asio::async_read(s,
874 * boost::asio::buffer(data, size),
875 * boost::asio::transfer_at_least(32),
876 * handler); @endcode
877 * See the @ref buffer documentation for information on reading into multiple
878 * buffers in one go, and how to use it with arrays, boost::array or
879 * std::vector.
880 *
881 * @par Per-Operation Cancellation
882 * This asynchronous operation supports cancellation for the following
883 * boost::asio::cancellation_type values:
884 *
885 * @li @c cancellation_type::terminal
886 *
887 * @li @c cancellation_type::partial
888 *
889 * if they are also supported by the @c AsyncReadStream type's
890 * @c async_read_some operation.
891 */
892template <typename AsyncReadStream,
893 typename MutableBufferSequence, typename CompletionCondition,
894 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
895 std::size_t)) ReadToken = default_completion_token_t<
896 typename AsyncReadStream::executor_type>>
897auto async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
898 CompletionCondition completion_condition,
899 ReadToken&& token = default_completion_token_t<
900 typename AsyncReadStream::executor_type>(),
901 constraint_t<
902 is_mutable_buffer_sequence<MutableBufferSequence>::value
903 > = 0)
904 -> decltype(
905 async_initiate<ReadToken,
906 void (boost::system::error_code, std::size_t)>(
907 declval<detail::initiate_async_read<AsyncReadStream>>(),
908 token, buffers,
909 static_cast<CompletionCondition&&>(completion_condition)));
910
911#if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
912
913/// Start an asynchronous operation to read a certain amount of data from a
914/// stream.
915/**
916 * This function is used to asynchronously read a certain number of bytes of
917 * data from a stream. It is an initiating function for an @ref
918 * asynchronous_operation, and always returns immediately. The asynchronous
919 * operation will continue until one of the following conditions is true:
920 *
921 * @li The specified dynamic buffer sequence is full (that is, it has reached
922 * maximum size).
923 *
924 * @li An error occurred.
925 *
926 * This operation is implemented in terms of zero or more calls to the stream's
927 * async_read_some function, and is known as a <em>composed operation</em>. The
928 * program must ensure that the stream performs no other read operations (such
929 * as async_read, the stream's async_read_some function, or any other composed
930 * operations that perform reads) until this operation completes.
931 *
932 * @param s The stream from which the data is to be read. The type must support
933 * the AsyncReadStream concept.
934 *
935 * @param buffers The dynamic buffer sequence into which the data will be read.
936 * Although the buffers object may be copied as necessary, ownership of the
937 * underlying memory blocks is retained by the caller, which must guarantee
938 * that they remain valid until the completion handler is called.
939 *
940 * @param token The @ref completion_token that will be used to produce a
941 * completion handler, which will be called when the read completes.
942 * Potential completion tokens include @ref use_future, @ref use_awaitable,
943 * @ref yield_context, or a function object with the correct completion
944 * signature. The function signature of the completion handler must be:
945 * @code void handler(
946 * // Result of operation.
947 * const boost::system::error_code& error,
948 *
949 * // Number of bytes copied into the buffers. If an error
950 * // occurred, this will be the number of bytes successfully
951 * // transferred prior to the error.
952 * std::size_t bytes_transferred
953 * ); @endcode
954 * Regardless of whether the asynchronous operation completes immediately or
955 * not, the completion handler will not be invoked from within this function.
956 * On immediate completion, invocation of the handler will be performed in a
957 * manner equivalent to using boost::asio::post().
958 *
959 * @par Completion Signature
960 * @code void(boost::system::error_code, std::size_t) @endcode
961 *
962 * @note This overload is equivalent to calling:
963 * @code boost::asio::async_read(
964 * s, buffers,
965 * boost::asio::transfer_all(),
966 * handler); @endcode
967 *
968 * @par Per-Operation Cancellation
969 * This asynchronous operation supports cancellation for the following
970 * boost::asio::cancellation_type values:
971 *
972 * @li @c cancellation_type::terminal
973 *
974 * @li @c cancellation_type::partial
975 *
976 * if they are also supported by the @c AsyncReadStream type's
977 * @c async_read_some operation.
978 */
979template <typename AsyncReadStream, typename DynamicBuffer_v1,
980 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
981 std::size_t)) ReadToken = default_completion_token_t<
982 typename AsyncReadStream::executor_type>>
983auto async_read(AsyncReadStream& s, DynamicBuffer_v1&& buffers,
984 ReadToken&& token = default_completion_token_t<
985 typename AsyncReadStream::executor_type>(),
986 constraint_t<
987 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
988 > = 0,
989 constraint_t<
990 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
991 > = 0)
992 -> decltype(
993 async_initiate<ReadToken,
994 void (boost::system::error_code, std::size_t)>(
995 declval<detail::initiate_async_read_dynbuf_v1<AsyncReadStream>>(),
996 token, static_cast<DynamicBuffer_v1&&>(buffers), transfer_all()));
997
998/// Start an asynchronous operation to read a certain amount of data from a
999/// stream.
1000/**
1001 * This function is used to asynchronously read a certain number of bytes of
1002 * data from a stream. It is an initiating function for an @ref
1003 * asynchronous_operation, and always returns immediately. The asynchronous
1004 * operation will continue until one of the following conditions is true:
1005 *
1006 * @li The specified dynamic buffer sequence is full (that is, it has reached
1007 * maximum size).
1008 *
1009 * @li The completion_condition function object returns 0.
1010 *
1011 * This operation is implemented in terms of zero or more calls to the stream's
1012 * async_read_some function, and is known as a <em>composed operation</em>. The
1013 * program must ensure that the stream performs no other read operations (such
1014 * as async_read, the stream's async_read_some function, or any other composed
1015 * operations that perform reads) until this operation completes.
1016 *
1017 * @param s The stream from which the data is to be read. The type must support
1018 * the AsyncReadStream concept.
1019 *
1020 * @param buffers The dynamic buffer sequence into which the data will be read.
1021 * Although the buffers object may be copied as necessary, ownership of the
1022 * underlying memory blocks is retained by the caller, which must guarantee
1023 * that they remain valid until the completion handler is called.
1024 *
1025 * @param completion_condition The function object to be called to determine
1026 * whether the read operation is complete. The signature of the function object
1027 * must be:
1028 * @code std::size_t completion_condition(
1029 * // Result of latest async_read_some operation.
1030 * const boost::system::error_code& error,
1031 *
1032 * // Number of bytes transferred so far.
1033 * std::size_t bytes_transferred
1034 * ); @endcode
1035 * A return value of 0 indicates that the read operation is complete. A non-zero
1036 * return value indicates the maximum number of bytes to be read on the next
1037 * call to the stream's async_read_some function.
1038 *
1039 * @param token The @ref completion_token that will be used to produce a
1040 * completion handler, which will be called when the read completes.
1041 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1042 * @ref yield_context, or a function object with the correct completion
1043 * signature. The function signature of the completion handler must be:
1044 * @code void handler(
1045 * // Result of operation.
1046 * const boost::system::error_code& error,
1047 *
1048 * // Number of bytes copied into the buffers. If an error
1049 * // occurred, this will be the number of bytes successfully
1050 * // transferred prior to the error.
1051 * std::size_t bytes_transferred
1052 * ); @endcode
1053 * Regardless of whether the asynchronous operation completes immediately or
1054 * not, the completion handler will not be invoked from within this function.
1055 * On immediate completion, invocation of the handler will be performed in a
1056 * manner equivalent to using boost::asio::post().
1057 *
1058 * @par Completion Signature
1059 * @code void(boost::system::error_code, std::size_t) @endcode
1060 *
1061 * @par Per-Operation Cancellation
1062 * This asynchronous operation supports cancellation for the following
1063 * boost::asio::cancellation_type values:
1064 *
1065 * @li @c cancellation_type::terminal
1066 *
1067 * @li @c cancellation_type::partial
1068 *
1069 * if they are also supported by the @c AsyncReadStream type's
1070 * @c async_read_some operation.
1071 */
1072template <typename AsyncReadStream,
1073 typename DynamicBuffer_v1, typename CompletionCondition,
1074 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1075 std::size_t)) ReadToken = default_completion_token_t<
1076 typename AsyncReadStream::executor_type>>
1077auto async_read(AsyncReadStream& s, DynamicBuffer_v1&& buffers,
1078 CompletionCondition completion_condition,
1079 ReadToken&& token = default_completion_token_t<
1080 typename AsyncReadStream::executor_type>(),
1081 constraint_t<
1082 is_dynamic_buffer_v1<decay_t<DynamicBuffer_v1>>::value
1083 > = 0,
1084 constraint_t<
1085 !is_dynamic_buffer_v2<decay_t<DynamicBuffer_v1>>::value
1086 > = 0)
1087 -> decltype(
1088 async_initiate<ReadToken,
1089 void (boost::system::error_code, std::size_t)>(
1090 declval<detail::initiate_async_read_dynbuf_v1<AsyncReadStream>>(),
1091 token, static_cast<DynamicBuffer_v1&&>(buffers),
1092 static_cast<CompletionCondition&&>(completion_condition)));
1093
1094#if !defined(BOOST_ASIO_NO_EXTENSIONS)
1095#if !defined(BOOST_ASIO_NO_IOSTREAM)
1096
1097/// Start an asynchronous operation to read a certain amount of data from a
1098/// stream.
1099/**
1100 * This function is used to asynchronously read a certain number of bytes of
1101 * data from a stream. It is an initiating function for an @ref
1102 * asynchronous_operation, and always returns immediately. The asynchronous
1103 * operation will continue until one of the following conditions is true:
1104 *
1105 * @li The supplied buffer is full (that is, it has reached maximum size).
1106 *
1107 * @li An error occurred.
1108 *
1109 * This operation is implemented in terms of zero or more calls to the stream's
1110 * async_read_some function, and is known as a <em>composed operation</em>. The
1111 * program must ensure that the stream performs no other read operations (such
1112 * as async_read, the stream's async_read_some function, or any other composed
1113 * operations that perform reads) until this operation completes.
1114 *
1115 * @param s The stream from which the data is to be read. The type must support
1116 * the AsyncReadStream concept.
1117 *
1118 * @param b A basic_streambuf object into which the data will be read. Ownership
1119 * of the streambuf is retained by the caller, which must guarantee that it
1120 * remains valid until the completion handler is called.
1121 *
1122 * @param token The @ref completion_token that will be used to produce a
1123 * completion handler, which will be called when the read completes.
1124 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1125 * @ref yield_context, or a function object with the correct completion
1126 * signature. The function signature of the completion handler must be:
1127 * @code void handler(
1128 * // Result of operation.
1129 * const boost::system::error_code& error,
1130 *
1131 * // Number of bytes copied into the buffers. If an error
1132 * // occurred, this will be the number of bytes successfully
1133 * // transferred prior to the error.
1134 * std::size_t bytes_transferred
1135 * ); @endcode
1136 * Regardless of whether the asynchronous operation completes immediately or
1137 * not, the completion handler will not be invoked from within this function.
1138 * On immediate completion, invocation of the handler will be performed in a
1139 * manner equivalent to using boost::asio::post().
1140 *
1141 * @par Completion Signature
1142 * @code void(boost::system::error_code, std::size_t) @endcode
1143 *
1144 * @note This overload is equivalent to calling:
1145 * @code boost::asio::async_read(
1146 * s, b,
1147 * boost::asio::transfer_all(),
1148 * handler); @endcode
1149 *
1150 * @par Per-Operation Cancellation
1151 * This asynchronous operation supports cancellation for the following
1152 * boost::asio::cancellation_type values:
1153 *
1154 * @li @c cancellation_type::terminal
1155 *
1156 * @li @c cancellation_type::partial
1157 *
1158 * if they are also supported by the @c AsyncReadStream type's
1159 * @c async_read_some operation.
1160 */
1161template <typename AsyncReadStream, typename Allocator,
1162 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1163 std::size_t)) ReadToken = default_completion_token_t<
1164 typename AsyncReadStream::executor_type>>
1165auto async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
1166 ReadToken&& token = default_completion_token_t<
1167 typename AsyncReadStream::executor_type>())
1168 -> decltype(
1169 async_initiate<ReadToken,
1170 void (boost::system::error_code, std::size_t)>(
1171 declval<detail::initiate_async_read_dynbuf_v1<AsyncReadStream>>(),
1172 token, basic_streambuf_ref<Allocator>(b), transfer_all()));
1173
1174/// Start an asynchronous operation to read a certain amount of data from a
1175/// stream.
1176/**
1177 * This function is used to asynchronously read a certain number of bytes of
1178 * data from a stream. It is an initiating function for an @ref
1179 * asynchronous_operation, and always returns immediately. The asynchronous
1180 * operation will continue until one of the following conditions is true:
1181 *
1182 * @li The supplied buffer is full (that is, it has reached maximum size).
1183 *
1184 * @li The completion_condition function object returns 0.
1185 *
1186 * This operation is implemented in terms of zero or more calls to the stream's
1187 * async_read_some function, and is known as a <em>composed operation</em>. The
1188 * program must ensure that the stream performs no other read operations (such
1189 * as async_read, the stream's async_read_some function, or any other composed
1190 * operations that perform reads) until this operation completes.
1191 *
1192 * @param s The stream from which the data is to be read. The type must support
1193 * the AsyncReadStream concept.
1194 *
1195 * @param b A basic_streambuf object into which the data will be read. Ownership
1196 * of the streambuf is retained by the caller, which must guarantee that it
1197 * remains valid until the completion handler is called.
1198 *
1199 * @param completion_condition The function object to be called to determine
1200 * whether the read operation is complete. The signature of the function object
1201 * must be:
1202 * @code std::size_t completion_condition(
1203 * // Result of latest async_read_some operation.
1204 * const boost::system::error_code& error,
1205 *
1206 * // Number of bytes transferred so far.
1207 * std::size_t bytes_transferred
1208 * ); @endcode
1209 * A return value of 0 indicates that the read operation is complete. A non-zero
1210 * return value indicates the maximum number of bytes to be read on the next
1211 * call to the stream's async_read_some function.
1212 *
1213 * @param token The @ref completion_token that will be used to produce a
1214 * completion handler, which will be called when the read completes.
1215 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1216 * @ref yield_context, or a function object with the correct completion
1217 * signature. The function signature of the completion handler must be:
1218 * @code void handler(
1219 * // Result of operation.
1220 * const boost::system::error_code& error,
1221 *
1222 * // Number of bytes copied into the buffers. If an error
1223 * // occurred, this will be the number of bytes successfully
1224 * // transferred prior to the error.
1225 * std::size_t bytes_transferred
1226 * ); @endcode
1227 * Regardless of whether the asynchronous operation completes immediately or
1228 * not, the completion handler will not be invoked from within this function.
1229 * On immediate completion, invocation of the handler will be performed in a
1230 * manner equivalent to using boost::asio::post().
1231 *
1232 * @par Completion Signature
1233 * @code void(boost::system::error_code, std::size_t) @endcode
1234 *
1235 * @par Per-Operation Cancellation
1236 * This asynchronous operation supports cancellation for the following
1237 * boost::asio::cancellation_type values:
1238 *
1239 * @li @c cancellation_type::terminal
1240 *
1241 * @li @c cancellation_type::partial
1242 *
1243 * if they are also supported by the @c AsyncReadStream type's
1244 * @c async_read_some operation.
1245 */
1246template <typename AsyncReadStream,
1247 typename Allocator, typename CompletionCondition,
1248 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1249 std::size_t)) ReadToken = default_completion_token_t<
1250 typename AsyncReadStream::executor_type>>
1251auto async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
1252 CompletionCondition completion_condition,
1253 ReadToken&& token = default_completion_token_t<
1254 typename AsyncReadStream::executor_type>())
1255 -> decltype(
1256 async_initiate<ReadToken,
1257 void (boost::system::error_code, std::size_t)>(
1258 declval<detail::initiate_async_read_dynbuf_v1<AsyncReadStream>>(),
1259 token, basic_streambuf_ref<Allocator>(b),
1260 static_cast<CompletionCondition&&>(completion_condition)));
1261
1262#endif // !defined(BOOST_ASIO_NO_IOSTREAM)
1263#endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
1264#endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
1265
1266/// Start an asynchronous operation to read a certain amount of data from a
1267/// stream.
1268/**
1269 * This function is used to asynchronously read a certain number of bytes of
1270 * data from a stream. It is an initiating function for an @ref
1271 * asynchronous_operation, and always returns immediately. The asynchronous
1272 * operation will continue until one of the following conditions is true:
1273 *
1274 * @li The specified dynamic buffer sequence is full (that is, it has reached
1275 * maximum size).
1276 *
1277 * @li An error occurred.
1278 *
1279 * This operation is implemented in terms of zero or more calls to the stream's
1280 * async_read_some function, and is known as a <em>composed operation</em>. The
1281 * program must ensure that the stream performs no other read operations (such
1282 * as async_read, the stream's async_read_some function, or any other composed
1283 * operations that perform reads) until this operation completes.
1284 *
1285 * @param s The stream from which the data is to be read. The type must support
1286 * the AsyncReadStream concept.
1287 *
1288 * @param buffers The dynamic buffer sequence into which the data will be read.
1289 * Although the buffers object may be copied as necessary, ownership of the
1290 * underlying memory blocks is retained by the caller, which must guarantee
1291 * that they remain valid until the completion handler is called.
1292 *
1293 * @param token The @ref completion_token that will be used to produce a
1294 * completion handler, which will be called when the read completes.
1295 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1296 * @ref yield_context, or a function object with the correct completion
1297 * signature. The function signature of the completion handler must be:
1298 * @code void handler(
1299 * // Result of operation.
1300 * const boost::system::error_code& error,
1301 *
1302 * // Number of bytes copied into the buffers. If an error
1303 * // occurred, this will be the number of bytes successfully
1304 * // transferred prior to the error.
1305 * std::size_t bytes_transferred
1306 * ); @endcode
1307 * Regardless of whether the asynchronous operation completes immediately or
1308 * not, the completion handler will not be invoked from within this function.
1309 * On immediate completion, invocation of the handler will be performed in a
1310 * manner equivalent to using boost::asio::post().
1311 *
1312 * @par Completion Signature
1313 * @code void(boost::system::error_code, std::size_t) @endcode
1314 *
1315 * @note This overload is equivalent to calling:
1316 * @code boost::asio::async_read(
1317 * s, buffers,
1318 * boost::asio::transfer_all(),
1319 * handler); @endcode
1320 *
1321 * @par Per-Operation Cancellation
1322 * This asynchronous operation supports cancellation for the following
1323 * boost::asio::cancellation_type values:
1324 *
1325 * @li @c cancellation_type::terminal
1326 *
1327 * @li @c cancellation_type::partial
1328 *
1329 * if they are also supported by the @c AsyncReadStream type's
1330 * @c async_read_some operation.
1331 */
1332template <typename AsyncReadStream, typename DynamicBuffer_v2,
1333 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1334 std::size_t)) ReadToken = default_completion_token_t<
1335 typename AsyncReadStream::executor_type>>
1336auto async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers,
1337 ReadToken&& token = default_completion_token_t<
1338 typename AsyncReadStream::executor_type>(),
1339 constraint_t<
1340 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1341 > = 0)
1342 -> decltype(
1343 async_initiate<ReadToken,
1344 void (boost::system::error_code, std::size_t)>(
1345 declval<detail::initiate_async_read_dynbuf_v2<AsyncReadStream>>(),
1346 token, static_cast<DynamicBuffer_v2&&>(buffers), transfer_all()));
1347
1348/// Start an asynchronous operation to read a certain amount of data from a
1349/// stream.
1350/**
1351 * This function is used to asynchronously read a certain number of bytes of
1352 * data from a stream. It is an initiating function for an @ref
1353 * asynchronous_operation, and always returns immediately. The asynchronous
1354 * operation will continue until one of the following conditions is true:
1355 *
1356 * @li The specified dynamic buffer sequence is full (that is, it has reached
1357 * maximum size).
1358 *
1359 * @li The completion_condition function object returns 0.
1360 *
1361 * This operation is implemented in terms of zero or more calls to the stream's
1362 * async_read_some function, and is known as a <em>composed operation</em>. The
1363 * program must ensure that the stream performs no other read operations (such
1364 * as async_read, the stream's async_read_some function, or any other composed
1365 * operations that perform reads) until this operation completes.
1366 *
1367 * @param s The stream from which the data is to be read. The type must support
1368 * the AsyncReadStream concept.
1369 *
1370 * @param buffers The dynamic buffer sequence into which the data will be read.
1371 * Although the buffers object may be copied as necessary, ownership of the
1372 * underlying memory blocks is retained by the caller, which must guarantee
1373 * that they remain valid until the completion handler is called.
1374 *
1375 * @param completion_condition The function object to be called to determine
1376 * whether the read operation is complete. The signature of the function object
1377 * must be:
1378 * @code std::size_t completion_condition(
1379 * // Result of latest async_read_some operation.
1380 * const boost::system::error_code& error,
1381 *
1382 * // Number of bytes transferred so far.
1383 * std::size_t bytes_transferred
1384 * ); @endcode
1385 * A return value of 0 indicates that the read operation is complete. A non-zero
1386 * return value indicates the maximum number of bytes to be read on the next
1387 * call to the stream's async_read_some function.
1388 *
1389 * @param token The @ref completion_token that will be used to produce a
1390 * completion handler, which will be called when the read completes.
1391 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1392 * @ref yield_context, or a function object with the correct completion
1393 * signature. The function signature of the completion handler must be:
1394 * @code void handler(
1395 * // Result of operation.
1396 * const boost::system::error_code& error,
1397 *
1398 * // Number of bytes copied into the buffers. If an error
1399 * // occurred, this will be the number of bytes successfully
1400 * // transferred prior to the error.
1401 * std::size_t bytes_transferred
1402 * ); @endcode
1403 * Regardless of whether the asynchronous operation completes immediately or
1404 * not, the completion handler will not be invoked from within this function.
1405 * On immediate completion, invocation of the handler will be performed in a
1406 * manner equivalent to using boost::asio::post().
1407 *
1408 * @par Completion Signature
1409 * @code void(boost::system::error_code, std::size_t) @endcode
1410 *
1411 * @par Per-Operation Cancellation
1412 * This asynchronous operation supports cancellation for the following
1413 * boost::asio::cancellation_type values:
1414 *
1415 * @li @c cancellation_type::terminal
1416 *
1417 * @li @c cancellation_type::partial
1418 *
1419 * if they are also supported by the @c AsyncReadStream type's
1420 * @c async_read_some operation.
1421 */
1422template <typename AsyncReadStream,
1423 typename DynamicBuffer_v2, typename CompletionCondition,
1424 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1425 std::size_t)) ReadToken = default_completion_token_t<
1426 typename AsyncReadStream::executor_type>>
1427auto async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers,
1428 CompletionCondition completion_condition,
1429 ReadToken&& token = default_completion_token_t<
1430 typename AsyncReadStream::executor_type>(),
1431 constraint_t<
1432 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1433 > = 0)
1434 -> decltype(
1435 async_initiate<ReadToken,
1436 void (boost::system::error_code, std::size_t)>(
1437 declval<detail::initiate_async_read_dynbuf_v2<AsyncReadStream>>(),
1438 token, static_cast<DynamicBuffer_v2&&>(buffers),
1439 static_cast<CompletionCondition&&>(completion_condition)));
1440
1441/*@}*/
1442
1443} // namespace asio
1444} // namespace boost
1445
1446#include <boost/asio/detail/pop_options.hpp>
1447
1448#include <boost/asio/impl/read.hpp>
1449
1450#endif // BOOST_ASIO_READ_HPP
1451

source code of boost/libs/asio/include/boost/asio/read.hpp