5 // Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff dot com)
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)
11 #ifndef BOOST_ASIO_READ_HPP
12 #define BOOST_ASIO_READ_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
20 #include <boost/asio/async_result.hpp>
21 #include <boost/asio/buffer.hpp>
22 #include <boost/asio/error.hpp>
24 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
25 # include <boost/asio/basic_streambuf_fwd.hpp>
26 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
28 #include <boost/asio/detail/push_options.hpp>
34 * @defgroup read boost::asio::read
36 * @brief The @c read function is a composed operation that reads a certain
37 * amount of data from a stream before returning.
41 /// Attempt to read a certain amount of data from a stream before returning.
43 * This function is used to read a certain number of bytes of data from a
44 * stream. The call will block until one of the following conditions is true:
46 * @li The supplied buffers are full. That is, the bytes transferred is equal to
47 * the sum of the buffer sizes.
49 * @li An error occurred.
51 * This operation is implemented in terms of zero or more calls to the stream's
54 * @param s The stream from which the data is to be read. The type must support
55 * the SyncReadStream concept.
57 * @param buffers One or more buffers into which the data will be read. The sum
58 * of the buffer sizes indicates the maximum number of bytes to read from the
61 * @returns The number of bytes transferred.
63 * @throws boost::system::system_error Thrown on failure.
66 * To read into a single data buffer use the @ref buffer function as follows:
67 * @code boost::asio::read(s, boost::asio::buffer(data, size)); @endcode
68 * See the @ref buffer documentation for information on reading into multiple
69 * buffers in one go, and how to use it with arrays, boost::array or
72 * @note This overload is equivalent to calling:
73 * @code boost::asio::read(
75 * boost::asio::transfer_all()); @endcode
77 template <typename SyncReadStream, typename MutableBufferSequence>
78 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
80 is_mutable_buffer_sequence<MutableBufferSequence>::value
83 /// Attempt to read a certain amount of data from a stream before returning.
85 * This function is used to read a certain number of bytes of data from a
86 * stream. The call will block until one of the following conditions is true:
88 * @li The supplied buffers are full. That is, the bytes transferred is equal to
89 * the sum of the buffer sizes.
91 * @li An error occurred.
93 * This operation is implemented in terms of zero or more calls to the stream's
96 * @param s The stream from which the data is to be read. The type must support
97 * the SyncReadStream concept.
99 * @param buffers One or more buffers into which the data will be read. The sum
100 * of the buffer sizes indicates the maximum number of bytes to read from the
103 * @param ec Set to indicate what error occurred, if any.
105 * @returns The number of bytes transferred.
108 * To read into a single data buffer use the @ref buffer function as follows:
109 * @code boost::asio::read(s, boost::asio::buffer(data, size), ec); @endcode
110 * See the @ref buffer documentation for information on reading into multiple
111 * buffers in one go, and how to use it with arrays, boost::array or
114 * @note This overload is equivalent to calling:
115 * @code boost::asio::read(
117 * boost::asio::transfer_all(), ec); @endcode
119 template <typename SyncReadStream, typename MutableBufferSequence>
120 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
121 boost::system::error_code& ec,
123 is_mutable_buffer_sequence<MutableBufferSequence>::value
126 /// Attempt to read a certain amount of data from a stream before returning.
128 * This function is used to read a certain number of bytes of data from a
129 * stream. The call will block until one of the following conditions is true:
131 * @li The supplied buffers are full. That is, the bytes transferred is equal to
132 * the sum of the buffer sizes.
134 * @li The completion_condition function object returns 0.
136 * This operation is implemented in terms of zero or more calls to the stream's
137 * read_some function.
139 * @param s The stream from which the data is to be read. The type must support
140 * the SyncReadStream concept.
142 * @param buffers One or more buffers into which the data will be read. The sum
143 * of the buffer sizes indicates the maximum number of bytes to read from the
146 * @param completion_condition The function object to be called to determine
147 * whether the read operation is complete. The signature of the function object
149 * @code std::size_t completion_condition(
150 * // Result of latest read_some operation.
151 * const boost::system::error_code& error,
153 * // Number of bytes transferred so far.
154 * std::size_t bytes_transferred
156 * A return value of 0 indicates that the read operation is complete. A non-zero
157 * return value indicates the maximum number of bytes to be read on the next
158 * call to the stream's read_some function.
160 * @returns The number of bytes transferred.
162 * @throws boost::system::system_error Thrown on failure.
165 * To read into a single data buffer use the @ref buffer function as follows:
166 * @code boost::asio::read(s, boost::asio::buffer(data, size),
167 * boost::asio::transfer_at_least(32)); @endcode
168 * See the @ref buffer documentation for information on reading into multiple
169 * buffers in one go, and how to use it with arrays, boost::array or
172 template <typename SyncReadStream, typename MutableBufferSequence,
173 typename CompletionCondition>
174 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
175 CompletionCondition completion_condition,
177 is_mutable_buffer_sequence<MutableBufferSequence>::value
180 /// Attempt to read a certain amount of data from a stream before returning.
182 * This function is used to read a certain number of bytes of data from a
183 * stream. The call will block until one of the following conditions is true:
185 * @li The supplied buffers are full. That is, the bytes transferred is equal to
186 * the sum of the buffer sizes.
188 * @li The completion_condition function object returns 0.
190 * This operation is implemented in terms of zero or more calls to the stream's
191 * read_some function.
193 * @param s The stream from which the data is to be read. The type must support
194 * the SyncReadStream concept.
196 * @param buffers One or more buffers into which the data will be read. The sum
197 * of the buffer sizes indicates the maximum number of bytes to read from the
200 * @param completion_condition The function object to be called to determine
201 * whether the read operation is complete. The signature of the function object
203 * @code std::size_t completion_condition(
204 * // Result of latest read_some operation.
205 * const boost::system::error_code& error,
207 * // Number of bytes transferred so far.
208 * std::size_t bytes_transferred
210 * A return value of 0 indicates that the read operation is complete. A non-zero
211 * return value indicates the maximum number of bytes to be read on the next
212 * call to the stream's read_some function.
214 * @param ec Set to indicate what error occurred, if any.
216 * @returns The number of bytes read. If an error occurs, returns the total
217 * number of bytes successfully transferred prior to the error.
219 template <typename SyncReadStream, typename MutableBufferSequence,
220 typename CompletionCondition>
221 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
222 CompletionCondition completion_condition, boost::system::error_code& ec,
224 is_mutable_buffer_sequence<MutableBufferSequence>::value
227 #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
229 /// Attempt to read a certain amount of data from a stream before returning.
231 * This function is used to read a certain number of bytes of data from a
232 * stream. The call will block until one of the following conditions is true:
234 * @li The specified dynamic buffer sequence is full (that is, it has reached
237 * @li An error occurred.
239 * This operation is implemented in terms of zero or more calls to the stream's
240 * read_some function.
242 * @param s The stream from which the data is to be read. The type must support
243 * the SyncReadStream concept.
245 * @param buffers The dynamic buffer sequence into which the data will be read.
247 * @returns The number of bytes transferred.
249 * @throws boost::system::system_error Thrown on failure.
251 * @note This overload is equivalent to calling:
252 * @code boost::asio::read(
254 * boost::asio::transfer_all()); @endcode
256 template <typename SyncReadStream, typename DynamicBuffer_v1>
257 std::size_t read(SyncReadStream& s,
258 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
260 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
261 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
264 /// Attempt to read a certain amount of data from a stream before returning.
266 * This function is used to read a certain number of bytes of data from a
267 * stream. The call will block until one of the following conditions is true:
269 * @li The supplied buffer is full (that is, it has reached maximum size).
271 * @li An error occurred.
273 * This operation is implemented in terms of zero or more calls to the stream's
274 * read_some function.
276 * @param s The stream from which the data is to be read. The type must support
277 * the SyncReadStream concept.
279 * @param buffers The dynamic buffer sequence into which the data will be read.
281 * @param ec Set to indicate what error occurred, if any.
283 * @returns The number of bytes transferred.
285 * @note This overload is equivalent to calling:
286 * @code boost::asio::read(
288 * boost::asio::transfer_all(), ec); @endcode
290 template <typename SyncReadStream, typename DynamicBuffer_v1>
291 std::size_t read(SyncReadStream& s,
292 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
293 boost::system::error_code& ec,
295 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
296 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
299 /// Attempt to read a certain amount of data from a stream before returning.
301 * This function is used to read a certain number of bytes of data from a
302 * stream. The call will block until one of the following conditions is true:
304 * @li The specified dynamic buffer sequence is full (that is, it has reached
307 * @li The completion_condition function object returns 0.
309 * This operation is implemented in terms of zero or more calls to the stream's
310 * read_some function.
312 * @param s The stream from which the data is to be read. The type must support
313 * the SyncReadStream concept.
315 * @param buffers The dynamic buffer sequence into which the data will be read.
317 * @param completion_condition The function object to be called to determine
318 * whether the read operation is complete. The signature of the function object
320 * @code std::size_t completion_condition(
321 * // Result of latest read_some operation.
322 * const boost::system::error_code& error,
324 * // Number of bytes transferred so far.
325 * std::size_t bytes_transferred
327 * A return value of 0 indicates that the read operation is complete. A non-zero
328 * return value indicates the maximum number of bytes to be read on the next
329 * call to the stream's read_some function.
331 * @returns The number of bytes transferred.
333 * @throws boost::system::system_error Thrown on failure.
335 template <typename SyncReadStream, typename DynamicBuffer_v1,
336 typename CompletionCondition>
337 std::size_t read(SyncReadStream& s,
338 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
339 CompletionCondition completion_condition,
341 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
342 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
345 /// Attempt to read a certain amount of data from a stream before returning.
347 * This function is used to read a certain number of bytes of data from a
348 * stream. The call will block until one of the following conditions is true:
350 * @li The specified dynamic buffer sequence is full (that is, it has reached
353 * @li The completion_condition function object returns 0.
355 * This operation is implemented in terms of zero or more calls to the stream's
356 * read_some function.
358 * @param s The stream from which the data is to be read. The type must support
359 * the SyncReadStream concept.
361 * @param buffers The dynamic buffer sequence into which the data will be read.
363 * @param completion_condition The function object to be called to determine
364 * whether the read operation is complete. The signature of the function object
366 * @code std::size_t completion_condition(
367 * // Result of latest read_some operation.
368 * const boost::system::error_code& error,
370 * // Number of bytes transferred so far.
371 * std::size_t bytes_transferred
373 * A return value of 0 indicates that the read operation is complete. A non-zero
374 * return value indicates the maximum number of bytes to be read on the next
375 * call to the stream's read_some function.
377 * @param ec Set to indicate what error occurred, if any.
379 * @returns The number of bytes read. If an error occurs, returns the total
380 * number of bytes successfully transferred prior to the error.
382 template <typename SyncReadStream, typename DynamicBuffer_v1,
383 typename CompletionCondition>
384 std::size_t read(SyncReadStream& s,
385 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
386 CompletionCondition completion_condition, boost::system::error_code& ec,
388 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
389 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
392 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
393 #if !defined(BOOST_ASIO_NO_IOSTREAM)
395 /// Attempt to read a certain amount of data from a stream before returning.
397 * This function is used to read a certain number of bytes of data from a
398 * stream. The call will block until one of the following conditions is true:
400 * @li The supplied buffer is full (that is, it has reached maximum size).
402 * @li An error occurred.
404 * This operation is implemented in terms of zero or more calls to the stream's
405 * read_some function.
407 * @param s The stream from which the data is to be read. The type must support
408 * the SyncReadStream concept.
410 * @param b The basic_streambuf object into which the data will be read.
412 * @returns The number of bytes transferred.
414 * @throws boost::system::system_error Thrown on failure.
416 * @note This overload is equivalent to calling:
417 * @code boost::asio::read(
419 * boost::asio::transfer_all()); @endcode
421 template <typename SyncReadStream, typename Allocator>
422 std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b);
424 /// Attempt to read a certain amount of data from a stream before returning.
426 * This function is used to read a certain number of bytes of data from a
427 * stream. The call will block until one of the following conditions is true:
429 * @li The supplied buffer is full (that is, it has reached maximum size).
431 * @li An error occurred.
433 * This operation is implemented in terms of zero or more calls to the stream's
434 * read_some function.
436 * @param s The stream from which the data is to be read. The type must support
437 * the SyncReadStream concept.
439 * @param b The basic_streambuf object into which the data will be read.
441 * @param ec Set to indicate what error occurred, if any.
443 * @returns The number of bytes transferred.
445 * @note This overload is equivalent to calling:
446 * @code boost::asio::read(
448 * boost::asio::transfer_all(), ec); @endcode
450 template <typename SyncReadStream, typename Allocator>
451 std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
452 boost::system::error_code& ec);
454 /// Attempt to read a certain amount of data from a stream before returning.
456 * This function is used to read a certain number of bytes of data from a
457 * stream. The call will block until one of the following conditions is true:
459 * @li The supplied buffer is full (that is, it has reached maximum size).
461 * @li The completion_condition function object returns 0.
463 * This operation is implemented in terms of zero or more calls to the stream's
464 * read_some function.
466 * @param s The stream from which the data is to be read. The type must support
467 * the SyncReadStream concept.
469 * @param b The basic_streambuf object into which the data will be read.
471 * @param completion_condition The function object to be called to determine
472 * whether the read operation is complete. The signature of the function object
474 * @code std::size_t completion_condition(
475 * // Result of latest read_some operation.
476 * const boost::system::error_code& error,
478 * // Number of bytes transferred so far.
479 * std::size_t bytes_transferred
481 * A return value of 0 indicates that the read operation is complete. A non-zero
482 * return value indicates the maximum number of bytes to be read on the next
483 * call to the stream's read_some function.
485 * @returns The number of bytes transferred.
487 * @throws boost::system::system_error Thrown on failure.
489 template <typename SyncReadStream, typename Allocator,
490 typename CompletionCondition>
491 std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
492 CompletionCondition completion_condition);
494 /// Attempt to read a certain amount of data from a stream before returning.
496 * This function is used to read a certain number of bytes of data from a
497 * stream. The call will block until one of the following conditions is true:
499 * @li The supplied buffer is full (that is, it has reached maximum size).
501 * @li The completion_condition function object returns 0.
503 * This operation is implemented in terms of zero or more calls to the stream's
504 * read_some function.
506 * @param s The stream from which the data is to be read. The type must support
507 * the SyncReadStream concept.
509 * @param b The basic_streambuf object into which the data will be read.
511 * @param completion_condition The function object to be called to determine
512 * whether the read operation is complete. The signature of the function object
514 * @code std::size_t completion_condition(
515 * // Result of latest read_some operation.
516 * const boost::system::error_code& error,
518 * // Number of bytes transferred so far.
519 * std::size_t bytes_transferred
521 * A return value of 0 indicates that the read operation is complete. A non-zero
522 * return value indicates the maximum number of bytes to be read on the next
523 * call to the stream's read_some function.
525 * @param ec Set to indicate what error occurred, if any.
527 * @returns The number of bytes read. If an error occurs, returns the total
528 * number of bytes successfully transferred prior to the error.
530 template <typename SyncReadStream, typename Allocator,
531 typename CompletionCondition>
532 std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
533 CompletionCondition completion_condition, boost::system::error_code& ec);
535 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
536 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
537 #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
539 /// Attempt to read a certain amount of data from a stream before returning.
541 * This function is used to read a certain number of bytes of data from a
542 * stream. The call will block until one of the following conditions is true:
544 * @li The specified dynamic buffer sequence is full (that is, it has reached
547 * @li An error occurred.
549 * This operation is implemented in terms of zero or more calls to the stream's
550 * read_some function.
552 * @param s The stream from which the data is to be read. The type must support
553 * the SyncReadStream concept.
555 * @param buffers The dynamic buffer sequence into which the data will be read.
557 * @returns The number of bytes transferred.
559 * @throws boost::system::system_error Thrown on failure.
561 * @note This overload is equivalent to calling:
562 * @code boost::asio::read(
564 * boost::asio::transfer_all()); @endcode
566 template <typename SyncReadStream, typename DynamicBuffer_v2>
567 std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
569 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
572 /// Attempt to read a certain amount of data from a stream before returning.
574 * This function is used to read a certain number of bytes of data from a
575 * stream. The call will block until one of the following conditions is true:
577 * @li The supplied buffer is full (that is, it has reached maximum size).
579 * @li An error occurred.
581 * This operation is implemented in terms of zero or more calls to the stream's
582 * read_some function.
584 * @param s The stream from which the data is to be read. The type must support
585 * the SyncReadStream concept.
587 * @param buffers The dynamic buffer sequence into which the data will be read.
589 * @param ec Set to indicate what error occurred, if any.
591 * @returns The number of bytes transferred.
593 * @note This overload is equivalent to calling:
594 * @code boost::asio::read(
596 * boost::asio::transfer_all(), ec); @endcode
598 template <typename SyncReadStream, typename DynamicBuffer_v2>
599 std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
600 boost::system::error_code& ec,
602 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
605 /// Attempt to read a certain amount of data from a stream before returning.
607 * This function is used to read a certain number of bytes of data from a
608 * stream. The call will block until one of the following conditions is true:
610 * @li The specified dynamic buffer sequence is full (that is, it has reached
613 * @li The completion_condition function object returns 0.
615 * This operation is implemented in terms of zero or more calls to the stream's
616 * read_some function.
618 * @param s The stream from which the data is to be read. The type must support
619 * the SyncReadStream concept.
621 * @param buffers The dynamic buffer sequence into which the data will be read.
623 * @param completion_condition The function object to be called to determine
624 * whether the read operation is complete. The signature of the function object
626 * @code std::size_t completion_condition(
627 * // Result of latest read_some operation.
628 * const boost::system::error_code& error,
630 * // Number of bytes transferred so far.
631 * std::size_t bytes_transferred
633 * A return value of 0 indicates that the read operation is complete. A non-zero
634 * return value indicates the maximum number of bytes to be read on the next
635 * call to the stream's read_some function.
637 * @returns The number of bytes transferred.
639 * @throws boost::system::system_error Thrown on failure.
641 template <typename SyncReadStream, typename DynamicBuffer_v2,
642 typename CompletionCondition>
643 std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
644 CompletionCondition completion_condition,
646 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
649 /// Attempt to read a certain amount of data from a stream before returning.
651 * This function is used to read a certain number of bytes of data from a
652 * stream. The call will block until one of the following conditions is true:
654 * @li The specified dynamic buffer sequence is full (that is, it has reached
657 * @li The completion_condition function object returns 0.
659 * This operation is implemented in terms of zero or more calls to the stream's
660 * read_some function.
662 * @param s The stream from which the data is to be read. The type must support
663 * the SyncReadStream concept.
665 * @param buffers The dynamic buffer sequence into which the data will be read.
667 * @param completion_condition The function object to be called to determine
668 * whether the read operation is complete. The signature of the function object
670 * @code std::size_t completion_condition(
671 * // Result of latest read_some operation.
672 * const boost::system::error_code& error,
674 * // Number of bytes transferred so far.
675 * std::size_t bytes_transferred
677 * A return value of 0 indicates that the read operation is complete. A non-zero
678 * return value indicates the maximum number of bytes to be read on the next
679 * call to the stream's read_some function.
681 * @param ec Set to indicate what error occurred, if any.
683 * @returns The number of bytes read. If an error occurs, returns the total
684 * number of bytes successfully transferred prior to the error.
686 template <typename SyncReadStream, typename DynamicBuffer_v2,
687 typename CompletionCondition>
688 std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
689 CompletionCondition completion_condition, boost::system::error_code& ec,
691 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
696 * @defgroup async_read boost::asio::async_read
698 * @brief The @c async_read function is a composed asynchronous operation that
699 * reads a certain amount of data from a stream before completion.
703 /// Start an asynchronous operation to read a certain amount of data from a
706 * This function is used to asynchronously read a certain number of bytes of
707 * data from a stream. The function call always returns immediately. The
708 * asynchronous operation will continue until one of the following conditions is
711 * @li The supplied buffers are full. That is, the bytes transferred is equal to
712 * the sum of the buffer sizes.
714 * @li An error occurred.
716 * This operation is implemented in terms of zero or more calls to the stream's
717 * async_read_some function, and is known as a <em>composed operation</em>. The
718 * program must ensure that the stream performs no other read operations (such
719 * as async_read, the stream's async_read_some function, or any other composed
720 * operations that perform reads) until this operation completes.
722 * @param s The stream from which the data is to be read. The type must support
723 * the AsyncReadStream concept.
725 * @param buffers One or more buffers into which the data will be read. The sum
726 * of the buffer sizes indicates the maximum number of bytes to read from the
727 * stream. Although the buffers object may be copied as necessary, ownership of
728 * the underlying memory blocks is retained by the caller, which must guarantee
729 * that they remain valid until the handler is called.
731 * @param handler The handler to be called when the read operation completes.
732 * Copies will be made of the handler as required. The function signature of the
734 * @code void handler(
735 * const boost::system::error_code& error, // Result of operation.
737 * std::size_t bytes_transferred // Number of bytes copied into the
738 * // buffers. If an error occurred,
739 * // this will be the number of
740 * // bytes successfully transferred
741 * // prior to the error.
743 * Regardless of whether the asynchronous operation completes immediately or
744 * not, the handler will not be invoked from within this function. On
745 * immediate completion, invocation of the handler will be performed in a
746 * manner equivalent to using boost::asio::post().
749 * To read into a single data buffer use the @ref buffer function as follows:
751 * boost::asio::async_read(s, boost::asio::buffer(data, size), handler);
753 * See the @ref buffer documentation for information on reading into multiple
754 * buffers in one go, and how to use it with arrays, boost::array or
757 * @note This overload is equivalent to calling:
758 * @code boost::asio::async_read(
760 * boost::asio::transfer_all(),
763 template <typename AsyncReadStream, typename MutableBufferSequence,
764 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
765 std::size_t)) ReadHandler
766 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
767 typename AsyncReadStream::executor_type)>
768 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
769 void (boost::system::error_code, std::size_t))
770 async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
771 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
772 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
773 typename AsyncReadStream::executor_type),
775 is_mutable_buffer_sequence<MutableBufferSequence>::value
778 /// Start an asynchronous operation to read a certain amount of data from a
781 * This function is used to asynchronously read a certain number of bytes of
782 * data from a stream. The function call always returns immediately. The
783 * asynchronous operation will continue until one of the following conditions is
786 * @li The supplied buffers are full. That is, the bytes transferred is equal to
787 * the sum of the buffer sizes.
789 * @li The completion_condition function object returns 0.
791 * @param s The stream from which the data is to be read. The type must support
792 * the AsyncReadStream concept.
794 * @param buffers One or more buffers into which the data will be read. The sum
795 * of the buffer sizes indicates the maximum number of bytes to read from the
796 * stream. Although the buffers object may be copied as necessary, ownership of
797 * the underlying memory blocks is retained by the caller, which must guarantee
798 * that they remain valid until the handler is called.
800 * @param completion_condition The function object to be called to determine
801 * whether the read operation is complete. The signature of the function object
803 * @code std::size_t completion_condition(
804 * // Result of latest async_read_some operation.
805 * const boost::system::error_code& error,
807 * // Number of bytes transferred so far.
808 * std::size_t bytes_transferred
810 * A return value of 0 indicates that the read operation is complete. A non-zero
811 * return value indicates the maximum number of bytes to be read on the next
812 * call to the stream's async_read_some function.
814 * @param handler The handler to be called when the read operation completes.
815 * Copies will be made of the handler as required. The function signature of the
817 * @code void handler(
818 * const boost::system::error_code& error, // Result of operation.
820 * std::size_t bytes_transferred // Number of bytes copied into the
821 * // buffers. If an error occurred,
822 * // this will be the number of
823 * // bytes successfully transferred
824 * // prior to the error.
826 * Regardless of whether the asynchronous operation completes immediately or
827 * not, the handler will not be invoked from within this function. On
828 * immediate completion, invocation of the handler will be performed in a
829 * manner equivalent to using boost::asio::post().
832 * To read into a single data buffer use the @ref buffer function as follows:
833 * @code boost::asio::async_read(s,
834 * boost::asio::buffer(data, size),
835 * boost::asio::transfer_at_least(32),
837 * See the @ref buffer documentation for information on reading into multiple
838 * buffers in one go, and how to use it with arrays, boost::array or
841 template <typename AsyncReadStream,
842 typename MutableBufferSequence, typename CompletionCondition,
843 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
844 std::size_t)) ReadHandler
845 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
846 typename AsyncReadStream::executor_type)>
847 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
848 void (boost::system::error_code, std::size_t))
849 async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
850 CompletionCondition completion_condition,
851 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
852 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
853 typename AsyncReadStream::executor_type),
855 is_mutable_buffer_sequence<MutableBufferSequence>::value
858 #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
860 /// Start an asynchronous operation to read a certain amount of data from a
863 * This function is used to asynchronously read a certain number of bytes of
864 * data from a stream. The function call always returns immediately. The
865 * asynchronous operation will continue until one of the following conditions is
868 * @li The specified dynamic buffer sequence is full (that is, it has reached
871 * @li An error occurred.
873 * This operation is implemented in terms of zero or more calls to the stream's
874 * async_read_some function, and is known as a <em>composed operation</em>. The
875 * program must ensure that the stream performs no other read operations (such
876 * as async_read, the stream's async_read_some function, or any other composed
877 * operations that perform reads) until this operation completes.
879 * @param s The stream from which the data is to be read. The type must support
880 * the AsyncReadStream concept.
882 * @param buffers The dynamic buffer sequence into which the data will be read.
883 * Although the buffers object may be copied as necessary, ownership of the
884 * underlying memory blocks is retained by the caller, which must guarantee
885 * that they remain valid until the handler is called.
887 * @param handler The handler to be called when the read operation completes.
888 * Copies will be made of the handler as required. The function signature of the
890 * @code void handler(
891 * const boost::system::error_code& error, // Result of operation.
893 * std::size_t bytes_transferred // Number of bytes copied into the
894 * // buffers. If an error occurred,
895 * // this will be the number of
896 * // bytes successfully transferred
897 * // prior to the error.
899 * Regardless of whether the asynchronous operation completes immediately or
900 * not, the handler will not be invoked from within this function. On
901 * immediate completion, invocation of the handler will be performed in a
902 * manner equivalent to using boost::asio::post().
904 * @note This overload is equivalent to calling:
905 * @code boost::asio::async_read(
907 * boost::asio::transfer_all(),
910 template <typename AsyncReadStream, typename DynamicBuffer_v1,
911 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
912 std::size_t)) ReadHandler
913 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
914 typename AsyncReadStream::executor_type)>
915 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
916 void (boost::system::error_code, std::size_t))
917 async_read(AsyncReadStream& s,
918 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
919 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
920 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
921 typename AsyncReadStream::executor_type),
923 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
924 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
927 /// Start an asynchronous operation to read a certain amount of data from a
930 * This function is used to asynchronously read a certain number of bytes of
931 * data from a stream. The function call always returns immediately. The
932 * asynchronous operation will continue until one of the following conditions is
935 * @li The specified dynamic buffer sequence is full (that is, it has reached
938 * @li The completion_condition function object returns 0.
940 * This operation is implemented in terms of zero or more calls to the stream's
941 * async_read_some function, and is known as a <em>composed operation</em>. The
942 * program must ensure that the stream performs no other read operations (such
943 * as async_read, the stream's async_read_some function, or any other composed
944 * operations that perform reads) until this operation completes.
946 * @param s The stream from which the data is to be read. The type must support
947 * the AsyncReadStream concept.
949 * @param buffers The dynamic buffer sequence into which the data will be read.
950 * Although the buffers object may be copied as necessary, ownership of the
951 * underlying memory blocks is retained by the caller, which must guarantee
952 * that they remain valid until the handler is called.
954 * @param completion_condition The function object to be called to determine
955 * whether the read operation is complete. The signature of the function object
957 * @code std::size_t completion_condition(
958 * // Result of latest async_read_some operation.
959 * const boost::system::error_code& error,
961 * // Number of bytes transferred so far.
962 * std::size_t bytes_transferred
964 * A return value of 0 indicates that the read operation is complete. A non-zero
965 * return value indicates the maximum number of bytes to be read on the next
966 * call to the stream's async_read_some function.
968 * @param handler The handler to be called when the read operation completes.
969 * Copies will be made of the handler as required. The function signature of the
971 * @code void handler(
972 * const boost::system::error_code& error, // Result of operation.
974 * std::size_t bytes_transferred // Number of bytes copied into the
975 * // buffers. If an error occurred,
976 * // this will be the number of
977 * // bytes successfully transferred
978 * // prior to the error.
980 * Regardless of whether the asynchronous operation completes immediately or
981 * not, the handler will not be invoked from within this function. On
982 * immediate completion, invocation of the handler will be performed in a
983 * manner equivalent to using boost::asio::post().
985 template <typename AsyncReadStream,
986 typename DynamicBuffer_v1, typename CompletionCondition,
987 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
988 std::size_t)) ReadHandler
989 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
990 typename AsyncReadStream::executor_type)>
991 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
992 void (boost::system::error_code, std::size_t))
993 async_read(AsyncReadStream& s,
994 BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
995 CompletionCondition completion_condition,
996 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
997 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
998 typename AsyncReadStream::executor_type),
1000 is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
1001 && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
1004 #if !defined(BOOST_ASIO_NO_EXTENSIONS)
1005 #if !defined(BOOST_ASIO_NO_IOSTREAM)
1007 /// Start an asynchronous operation to read a certain amount of data from a
1010 * This function is used to asynchronously read a certain number of bytes of
1011 * data from a stream. The function call always returns immediately. The
1012 * asynchronous operation will continue until one of the following conditions is
1015 * @li The supplied buffer is full (that is, it has reached maximum size).
1017 * @li An error occurred.
1019 * This operation is implemented in terms of zero or more calls to the stream's
1020 * async_read_some function, and is known as a <em>composed operation</em>. The
1021 * program must ensure that the stream performs no other read operations (such
1022 * as async_read, the stream's async_read_some function, or any other composed
1023 * operations that perform reads) until this operation completes.
1025 * @param s The stream from which the data is to be read. The type must support
1026 * the AsyncReadStream concept.
1028 * @param b A basic_streambuf object into which the data will be read. Ownership
1029 * of the streambuf is retained by the caller, which must guarantee that it
1030 * remains valid until the handler is called.
1032 * @param handler The handler to be called when the read operation completes.
1033 * Copies will be made of the handler as required. The function signature of the
1035 * @code void handler(
1036 * const boost::system::error_code& error, // Result of operation.
1038 * std::size_t bytes_transferred // Number of bytes copied into the
1039 * // buffers. If an error occurred,
1040 * // this will be the number of
1041 * // bytes successfully transferred
1042 * // prior to the error.
1044 * Regardless of whether the asynchronous operation completes immediately or
1045 * not, the handler will not be invoked from within this function. On
1046 * immediate completion, invocation of the handler will be performed in a
1047 * manner equivalent to using boost::asio::post().
1049 * @note This overload is equivalent to calling:
1050 * @code boost::asio::async_read(
1052 * boost::asio::transfer_all(),
1053 * handler); @endcode
1055 template <typename AsyncReadStream, typename Allocator,
1056 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1057 std::size_t)) ReadHandler
1058 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
1059 typename AsyncReadStream::executor_type)>
1060 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
1061 void (boost::system::error_code, std::size_t))
1062 async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
1063 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
1064 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
1065 typename AsyncReadStream::executor_type));
1067 /// Start an asynchronous operation to read a certain amount of data from a
1070 * This function is used to asynchronously read a certain number of bytes of
1071 * data from a stream. The function call always returns immediately. The
1072 * asynchronous operation will continue until one of the following conditions is
1075 * @li The supplied buffer is full (that is, it has reached maximum size).
1077 * @li The completion_condition function object returns 0.
1079 * This operation is implemented in terms of zero or more calls to the stream's
1080 * async_read_some function, and is known as a <em>composed operation</em>. The
1081 * program must ensure that the stream performs no other read operations (such
1082 * as async_read, the stream's async_read_some function, or any other composed
1083 * operations that perform reads) until this operation completes.
1085 * @param s The stream from which the data is to be read. The type must support
1086 * the AsyncReadStream concept.
1088 * @param b A basic_streambuf object into which the data will be read. Ownership
1089 * of the streambuf is retained by the caller, which must guarantee that it
1090 * remains valid until the handler is called.
1092 * @param completion_condition The function object to be called to determine
1093 * whether the read operation is complete. The signature of the function object
1095 * @code std::size_t completion_condition(
1096 * // Result of latest async_read_some operation.
1097 * const boost::system::error_code& error,
1099 * // Number of bytes transferred so far.
1100 * std::size_t bytes_transferred
1102 * A return value of 0 indicates that the read operation is complete. A non-zero
1103 * return value indicates the maximum number of bytes to be read on the next
1104 * call to the stream's async_read_some function.
1106 * @param handler The handler to be called when the read operation completes.
1107 * Copies will be made of the handler as required. The function signature of the
1109 * @code void handler(
1110 * const boost::system::error_code& error, // Result of operation.
1112 * std::size_t bytes_transferred // Number of bytes copied into the
1113 * // buffers. If an error occurred,
1114 * // this will be the number of
1115 * // bytes successfully transferred
1116 * // prior to the error.
1118 * Regardless of whether the asynchronous operation completes immediately or
1119 * not, the handler will not be invoked from within this function. On
1120 * immediate completion, invocation of the handler will be performed in a
1121 * manner equivalent to using boost::asio::post().
1123 template <typename AsyncReadStream,
1124 typename Allocator, typename CompletionCondition,
1125 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1126 std::size_t)) ReadHandler
1127 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
1128 typename AsyncReadStream::executor_type)>
1129 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
1130 void (boost::system::error_code, std::size_t))
1131 async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
1132 CompletionCondition completion_condition,
1133 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
1134 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
1135 typename AsyncReadStream::executor_type));
1137 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
1138 #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
1139 #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
1141 /// Start an asynchronous operation to read a certain amount of data from a
1144 * This function is used to asynchronously read a certain number of bytes of
1145 * data from a stream. The function call always returns immediately. The
1146 * asynchronous operation will continue until one of the following conditions is
1149 * @li The specified dynamic buffer sequence is full (that is, it has reached
1152 * @li An error occurred.
1154 * This operation is implemented in terms of zero or more calls to the stream's
1155 * async_read_some function, and is known as a <em>composed operation</em>. The
1156 * program must ensure that the stream performs no other read operations (such
1157 * as async_read, the stream's async_read_some function, or any other composed
1158 * operations that perform reads) until this operation completes.
1160 * @param s The stream from which the data is to be read. The type must support
1161 * the AsyncReadStream concept.
1163 * @param buffers The dynamic buffer sequence into which the data will be read.
1164 * Although the buffers object may be copied as necessary, ownership of the
1165 * underlying memory blocks is retained by the caller, which must guarantee
1166 * that they remain valid until the handler is called.
1168 * @param handler The handler to be called when the read operation completes.
1169 * Copies will be made of the handler as required. The function signature of the
1171 * @code void handler(
1172 * const boost::system::error_code& error, // Result of operation.
1174 * std::size_t bytes_transferred // Number of bytes copied into the
1175 * // buffers. If an error occurred,
1176 * // this will be the number of
1177 * // bytes successfully transferred
1178 * // prior to the error.
1180 * Regardless of whether the asynchronous operation completes immediately or
1181 * not, the handler will not be invoked from within this function. On
1182 * immediate completion, invocation of the handler will be performed in a
1183 * manner equivalent to using boost::asio::post().
1185 * @note This overload is equivalent to calling:
1186 * @code boost::asio::async_read(
1188 * boost::asio::transfer_all(),
1189 * handler); @endcode
1191 template <typename AsyncReadStream, typename DynamicBuffer_v2,
1192 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1193 std::size_t)) ReadHandler
1194 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
1195 typename AsyncReadStream::executor_type)>
1196 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
1197 void (boost::system::error_code, std::size_t))
1198 async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers,
1199 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
1200 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
1201 typename AsyncReadStream::executor_type),
1203 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1206 /// Start an asynchronous operation to read a certain amount of data from a
1209 * This function is used to asynchronously read a certain number of bytes of
1210 * data from a stream. The function call always returns immediately. The
1211 * asynchronous operation will continue until one of the following conditions is
1214 * @li The specified dynamic buffer sequence is full (that is, it has reached
1217 * @li The completion_condition function object returns 0.
1219 * This operation is implemented in terms of zero or more calls to the stream's
1220 * async_read_some function, and is known as a <em>composed operation</em>. The
1221 * program must ensure that the stream performs no other read operations (such
1222 * as async_read, the stream's async_read_some function, or any other composed
1223 * operations that perform reads) until this operation completes.
1225 * @param s The stream from which the data is to be read. The type must support
1226 * the AsyncReadStream concept.
1228 * @param buffers The dynamic buffer sequence into which the data will be read.
1229 * Although the buffers object may be copied as necessary, ownership of the
1230 * underlying memory blocks is retained by the caller, which must guarantee
1231 * that they remain valid until the handler is called.
1233 * @param completion_condition The function object to be called to determine
1234 * whether the read operation is complete. The signature of the function object
1236 * @code std::size_t completion_condition(
1237 * // Result of latest async_read_some operation.
1238 * const boost::system::error_code& error,
1240 * // Number of bytes transferred so far.
1241 * std::size_t bytes_transferred
1243 * A return value of 0 indicates that the read operation is complete. A non-zero
1244 * return value indicates the maximum number of bytes to be read on the next
1245 * call to the stream's async_read_some function.
1247 * @param handler The handler to be called when the read operation completes.
1248 * Copies will be made of the handler as required. The function signature of the
1250 * @code void handler(
1251 * const boost::system::error_code& error, // Result of operation.
1253 * std::size_t bytes_transferred // Number of bytes copied into the
1254 * // buffers. If an error occurred,
1255 * // this will be the number of
1256 * // bytes successfully transferred
1257 * // prior to the error.
1259 * Regardless of whether the asynchronous operation completes immediately or
1260 * not, the handler will not be invoked from within this function. On
1261 * immediate completion, invocation of the handler will be performed in a
1262 * manner equivalent to using boost::asio::post().
1264 template <typename AsyncReadStream,
1265 typename DynamicBuffer_v2, typename CompletionCondition,
1266 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1267 std::size_t)) ReadHandler
1268 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
1269 typename AsyncReadStream::executor_type)>
1270 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
1271 void (boost::system::error_code, std::size_t))
1272 async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers,
1273 CompletionCondition completion_condition,
1274 BOOST_ASIO_MOVE_ARG(ReadHandler) handler
1275 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
1276 typename AsyncReadStream::executor_type),
1278 is_dynamic_buffer_v2<DynamicBuffer_v2>::value
1284 } // namespace boost
1286 #include <boost/asio/detail/pop_options.hpp>
1288 #include <boost/asio/impl/read.hpp>
1290 #endif // BOOST_ASIO_READ_HPP