5 // Copyright (c) 2003-2016 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/basic_streambuf_fwd.hpp>
22 #include <boost/asio/error.hpp>
24 #include <boost/asio/detail/push_options.hpp>
30 * @defgroup read boost::asio::read
32 * @brief Attempt to read a certain amount of data from a stream before
37 /// Attempt to read a certain amount of data from a stream before returning.
39 * This function is used to read a certain number of bytes of data from a
40 * stream. The call will block until one of the following conditions is true:
42 * @li The supplied buffers are full. That is, the bytes transferred is equal to
43 * the sum of the buffer sizes.
45 * @li An error occurred.
47 * This operation is implemented in terms of zero or more calls to the stream's
50 * @param s The stream from which the data is to be read. The type must support
51 * the SyncReadStream concept.
53 * @param buffers One or more buffers into which the data will be read. The sum
54 * of the buffer sizes indicates the maximum number of bytes to read from the
57 * @returns The number of bytes transferred.
59 * @throws boost::system::system_error Thrown on failure.
62 * To read into a single data buffer use the @ref buffer function as follows:
63 * @code boost::asio::read(s, boost::asio::buffer(data, size)); @endcode
64 * See the @ref buffer documentation for information on reading into multiple
65 * buffers in one go, and how to use it with arrays, boost::array or
68 * @note This overload is equivalent to calling:
69 * @code boost::asio::read(
71 * boost::asio::transfer_all()); @endcode
73 template <typename SyncReadStream, typename MutableBufferSequence>
74 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers);
76 /// Attempt to read a certain amount of data from a stream before returning.
78 * This function is used to read a certain number of bytes of data from a
79 * stream. The call will block until one of the following conditions is true:
81 * @li The supplied buffers are full. That is, the bytes transferred is equal to
82 * the sum of the buffer sizes.
84 * @li An error occurred.
86 * This operation is implemented in terms of zero or more calls to the stream's
89 * @param s The stream from which the data is to be read. The type must support
90 * the SyncReadStream concept.
92 * @param buffers One or more buffers into which the data will be read. The sum
93 * of the buffer sizes indicates the maximum number of bytes to read from the
96 * @param ec Set to indicate what error occurred, if any.
98 * @returns The number of bytes transferred.
101 * To read into a single data buffer use the @ref buffer function as follows:
102 * @code boost::asio::read(s, boost::asio::buffer(data, size), ec); @endcode
103 * See the @ref buffer documentation for information on reading into multiple
104 * buffers in one go, and how to use it with arrays, boost::array or
107 * @note This overload is equivalent to calling:
108 * @code boost::asio::read(
110 * boost::asio::transfer_all(), ec); @endcode
112 template <typename SyncReadStream, typename MutableBufferSequence>
113 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
114 boost::system::error_code& ec);
116 /// Attempt to read a certain amount of data from a stream before returning.
118 * This function is used to read a certain number of bytes of data from a
119 * stream. The call will block until one of the following conditions is true:
121 * @li The supplied buffers are full. That is, the bytes transferred is equal to
122 * the sum of the buffer sizes.
124 * @li The completion_condition function object returns 0.
126 * This operation is implemented in terms of zero or more calls to the stream's
127 * read_some function.
129 * @param s The stream from which the data is to be read. The type must support
130 * the SyncReadStream concept.
132 * @param buffers One or more buffers into which the data will be read. The sum
133 * of the buffer sizes indicates the maximum number of bytes to read from the
136 * @param completion_condition The function object to be called to determine
137 * whether the read operation is complete. The signature of the function object
139 * @code std::size_t completion_condition(
140 * // Result of latest read_some operation.
141 * const boost::system::error_code& error,
143 * // Number of bytes transferred so far.
144 * std::size_t bytes_transferred
146 * A return value of 0 indicates that the read operation is complete. A non-zero
147 * return value indicates the maximum number of bytes to be read on the next
148 * call to the stream's read_some function.
150 * @returns The number of bytes transferred.
152 * @throws boost::system::system_error Thrown on failure.
155 * To read into a single data buffer use the @ref buffer function as follows:
156 * @code boost::asio::read(s, boost::asio::buffer(data, size),
157 * boost::asio::transfer_at_least(32)); @endcode
158 * See the @ref buffer documentation for information on reading into multiple
159 * buffers in one go, and how to use it with arrays, boost::array or
162 template <typename SyncReadStream, typename MutableBufferSequence,
163 typename CompletionCondition>
164 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
165 CompletionCondition completion_condition);
167 /// Attempt to read a certain amount of data from a stream before returning.
169 * This function is used to read a certain number of bytes of data from a
170 * stream. The call will block until one of the following conditions is true:
172 * @li The supplied buffers are full. That is, the bytes transferred is equal to
173 * the sum of the buffer sizes.
175 * @li The completion_condition function object returns 0.
177 * This operation is implemented in terms of zero or more calls to the stream's
178 * read_some function.
180 * @param s The stream from which the data is to be read. The type must support
181 * the SyncReadStream concept.
183 * @param buffers One or more buffers into which the data will be read. The sum
184 * of the buffer sizes indicates the maximum number of bytes to read from the
187 * @param completion_condition The function object to be called to determine
188 * whether the read operation is complete. The signature of the function object
190 * @code std::size_t completion_condition(
191 * // Result of latest read_some operation.
192 * const boost::system::error_code& error,
194 * // Number of bytes transferred so far.
195 * std::size_t bytes_transferred
197 * A return value of 0 indicates that the read operation is complete. A non-zero
198 * return value indicates the maximum number of bytes to be read on the next
199 * call to the stream's read_some function.
201 * @param ec Set to indicate what error occurred, if any.
203 * @returns The number of bytes read. If an error occurs, returns the total
204 * number of bytes successfully transferred prior to the error.
206 template <typename SyncReadStream, typename MutableBufferSequence,
207 typename CompletionCondition>
208 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
209 CompletionCondition completion_condition, boost::system::error_code& ec);
211 #if !defined(BOOST_ASIO_NO_IOSTREAM)
213 /// Attempt to read a certain amount of data from a stream before returning.
215 * This function is used to read a certain number of bytes of data from a
216 * stream. The call will block until one of the following conditions is true:
218 * @li The supplied buffer is full (that is, it has reached maximum size).
220 * @li An error occurred.
222 * This operation is implemented in terms of zero or more calls to the stream's
223 * read_some function.
225 * @param s The stream from which the data is to be read. The type must support
226 * the SyncReadStream concept.
228 * @param b The basic_streambuf object into which the data will be read.
230 * @returns The number of bytes transferred.
232 * @throws boost::system::system_error Thrown on failure.
234 * @note This overload is equivalent to calling:
235 * @code boost::asio::read(
237 * boost::asio::transfer_all()); @endcode
239 template <typename SyncReadStream, typename Allocator>
240 std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b);
242 /// Attempt to read a certain amount of data from a stream before returning.
244 * This function is used to read a certain number of bytes of data from a
245 * stream. The call will block until one of the following conditions is true:
247 * @li The supplied buffer is full (that is, it has reached maximum size).
249 * @li An error occurred.
251 * This operation is implemented in terms of zero or more calls to the stream's
252 * read_some function.
254 * @param s The stream from which the data is to be read. The type must support
255 * the SyncReadStream concept.
257 * @param b The basic_streambuf object into which the data will be read.
259 * @param ec Set to indicate what error occurred, if any.
261 * @returns The number of bytes transferred.
263 * @note This overload is equivalent to calling:
264 * @code boost::asio::read(
266 * boost::asio::transfer_all(), ec); @endcode
268 template <typename SyncReadStream, typename Allocator>
269 std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
270 boost::system::error_code& ec);
272 /// Attempt to read a certain amount of data from a stream before returning.
274 * This function is used to read a certain number of bytes of data from a
275 * stream. The call will block until one of the following conditions is true:
277 * @li The supplied buffer is full (that is, it has reached maximum size).
279 * @li The completion_condition function object returns 0.
281 * This operation is implemented in terms of zero or more calls to the stream's
282 * read_some function.
284 * @param s The stream from which the data is to be read. The type must support
285 * the SyncReadStream concept.
287 * @param b The basic_streambuf object into which the data will be read.
289 * @param completion_condition The function object to be called to determine
290 * whether the read operation is complete. The signature of the function object
292 * @code std::size_t completion_condition(
293 * // Result of latest read_some operation.
294 * const boost::system::error_code& error,
296 * // Number of bytes transferred so far.
297 * std::size_t bytes_transferred
299 * A return value of 0 indicates that the read operation is complete. A non-zero
300 * return value indicates the maximum number of bytes to be read on the next
301 * call to the stream's read_some function.
303 * @returns The number of bytes transferred.
305 * @throws boost::system::system_error Thrown on failure.
307 template <typename SyncReadStream, typename Allocator,
308 typename CompletionCondition>
309 std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
310 CompletionCondition completion_condition);
312 /// Attempt to read a certain amount of data from a stream before returning.
314 * This function is used to read a certain number of bytes of data from a
315 * stream. The call will block until one of the following conditions is true:
317 * @li The supplied buffer is full (that is, it has reached maximum size).
319 * @li The completion_condition function object returns 0.
321 * This operation is implemented in terms of zero or more calls to the stream's
322 * read_some function.
324 * @param s The stream from which the data is to be read. The type must support
325 * the SyncReadStream concept.
327 * @param b The basic_streambuf object into which the data will be read.
329 * @param completion_condition The function object to be called to determine
330 * whether the read operation is complete. The signature of the function object
332 * @code std::size_t completion_condition(
333 * // Result of latest read_some operation.
334 * const boost::system::error_code& error,
336 * // Number of bytes transferred so far.
337 * std::size_t bytes_transferred
339 * A return value of 0 indicates that the read operation is complete. A non-zero
340 * return value indicates the maximum number of bytes to be read on the next
341 * call to the stream's read_some function.
343 * @param ec Set to indicate what error occurred, if any.
345 * @returns The number of bytes read. If an error occurs, returns the total
346 * number of bytes successfully transferred prior to the error.
348 template <typename SyncReadStream, typename Allocator,
349 typename CompletionCondition>
350 std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
351 CompletionCondition completion_condition, boost::system::error_code& ec);
353 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
357 * @defgroup async_read boost::asio::async_read
359 * @brief Start an asynchronous operation to read a certain amount of data from
364 /// Start an asynchronous operation to read a certain amount of data from a
367 * This function is used to asynchronously read a certain number of bytes of
368 * data from a stream. The function call always returns immediately. The
369 * asynchronous operation will continue until one of the following conditions is
372 * @li The supplied buffers are full. That is, the bytes transferred is equal to
373 * the sum of the buffer sizes.
375 * @li An error occurred.
377 * This operation is implemented in terms of zero or more calls to the stream's
378 * async_read_some function, and is known as a <em>composed operation</em>. The
379 * program must ensure that the stream performs no other read operations (such
380 * as async_read, the stream's async_read_some function, or any other composed
381 * operations that perform reads) until this operation completes.
383 * @param s The stream from which the data is to be read. The type must support
384 * the AsyncReadStream concept.
386 * @param buffers One or more buffers into which the data will be read. The sum
387 * of the buffer sizes indicates the maximum number of bytes to read from the
388 * stream. Although the buffers object may be copied as necessary, ownership of
389 * the underlying memory blocks is retained by the caller, which must guarantee
390 * that they remain valid until the handler is called.
392 * @param handler The handler to be called when the read operation completes.
393 * Copies will be made of the handler as required. The function signature of the
395 * @code void handler(
396 * const boost::system::error_code& error, // Result of operation.
398 * std::size_t bytes_transferred // Number of bytes copied into the
399 * // buffers. If an error occurred,
400 * // this will be the number of
401 * // bytes successfully transferred
402 * // prior to the error.
404 * Regardless of whether the asynchronous operation completes immediately or
405 * not, the handler will not be invoked from within this function. Invocation of
406 * the handler will be performed in a manner equivalent to using
407 * boost::asio::io_service::post().
410 * To read into a single data buffer use the @ref buffer function as follows:
412 * boost::asio::async_read(s, boost::asio::buffer(data, size), handler);
414 * See the @ref buffer documentation for information on reading into multiple
415 * buffers in one go, and how to use it with arrays, boost::array or
418 * @note This overload is equivalent to calling:
419 * @code boost::asio::async_read(
421 * boost::asio::transfer_all(),
424 template <typename AsyncReadStream, typename MutableBufferSequence,
425 typename ReadHandler>
426 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
427 void (boost::system::error_code, std::size_t))
428 async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
429 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
431 /// Start an asynchronous operation to read a certain amount of data from a
434 * This function is used to asynchronously read a certain number of bytes of
435 * data from a stream. The function call always returns immediately. The
436 * asynchronous operation will continue until one of the following conditions is
439 * @li The supplied buffers are full. That is, the bytes transferred is equal to
440 * the sum of the buffer sizes.
442 * @li The completion_condition function object returns 0.
444 * @param s The stream from which the data is to be read. The type must support
445 * the AsyncReadStream concept.
447 * @param buffers One or more buffers into which the data will be read. The sum
448 * of the buffer sizes indicates the maximum number of bytes to read from the
449 * stream. Although the buffers object may be copied as necessary, ownership of
450 * the underlying memory blocks is retained by the caller, which must guarantee
451 * that they remain valid until the handler is called.
453 * @param completion_condition The function object to be called to determine
454 * whether the read operation is complete. The signature of the function object
456 * @code std::size_t completion_condition(
457 * // Result of latest async_read_some operation.
458 * const boost::system::error_code& error,
460 * // Number of bytes transferred so far.
461 * std::size_t bytes_transferred
463 * A return value of 0 indicates that the read operation is complete. A non-zero
464 * return value indicates the maximum number of bytes to be read on the next
465 * call to the stream's async_read_some function.
467 * @param handler The handler to be called when the read operation completes.
468 * Copies will be made of the handler as required. The function signature of the
470 * @code void handler(
471 * const boost::system::error_code& error, // Result of operation.
473 * std::size_t bytes_transferred // Number of bytes copied into the
474 * // buffers. If an error occurred,
475 * // this will be the number of
476 * // bytes successfully transferred
477 * // prior to the error.
479 * Regardless of whether the asynchronous operation completes immediately or
480 * not, the handler will not be invoked from within this function. Invocation of
481 * the handler will be performed in a manner equivalent to using
482 * boost::asio::io_service::post().
485 * To read into a single data buffer use the @ref buffer function as follows:
486 * @code boost::asio::async_read(s,
487 * boost::asio::buffer(data, size),
488 * boost::asio::transfer_at_least(32),
490 * See the @ref buffer documentation for information on reading into multiple
491 * buffers in one go, and how to use it with arrays, boost::array or
494 template <typename AsyncReadStream, typename MutableBufferSequence,
495 typename CompletionCondition, typename ReadHandler>
496 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
497 void (boost::system::error_code, std::size_t))
498 async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
499 CompletionCondition completion_condition,
500 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
502 #if !defined(BOOST_ASIO_NO_IOSTREAM)
504 /// Start an asynchronous operation to read a certain amount of data from a
507 * This function is used to asynchronously read a certain number of bytes of
508 * data from a stream. The function call always returns immediately. The
509 * asynchronous operation will continue until one of the following conditions is
512 * @li The supplied buffer is full (that is, it has reached maximum size).
514 * @li An error occurred.
516 * This operation is implemented in terms of zero or more calls to the stream's
517 * async_read_some function, and is known as a <em>composed operation</em>. The
518 * program must ensure that the stream performs no other read operations (such
519 * as async_read, the stream's async_read_some function, or any other composed
520 * operations that perform reads) until this operation completes.
522 * @param s The stream from which the data is to be read. The type must support
523 * the AsyncReadStream concept.
525 * @param b A basic_streambuf object into which the data will be read. Ownership
526 * of the streambuf is retained by the caller, which must guarantee that it
527 * remains valid until the handler is called.
529 * @param handler The handler to be called when the read operation completes.
530 * Copies will be made of the handler as required. The function signature of the
532 * @code void handler(
533 * const boost::system::error_code& error, // Result of operation.
535 * std::size_t bytes_transferred // Number of bytes copied into the
536 * // buffers. If an error occurred,
537 * // this will be the number of
538 * // bytes successfully transferred
539 * // prior to the error.
541 * Regardless of whether the asynchronous operation completes immediately or
542 * not, the handler will not be invoked from within this function. Invocation of
543 * the handler will be performed in a manner equivalent to using
544 * boost::asio::io_service::post().
546 * @note This overload is equivalent to calling:
547 * @code boost::asio::async_read(
549 * boost::asio::transfer_all(),
552 template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
553 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
554 void (boost::system::error_code, std::size_t))
555 async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
556 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
558 /// Start an asynchronous operation to read a certain amount of data from a
561 * This function is used to asynchronously read a certain number of bytes of
562 * data from a stream. The function call always returns immediately. The
563 * asynchronous operation will continue until one of the following conditions is
566 * @li The supplied buffer is full (that is, it has reached maximum size).
568 * @li The completion_condition function object returns 0.
570 * This operation is implemented in terms of zero or more calls to the stream's
571 * async_read_some function, and is known as a <em>composed operation</em>. The
572 * program must ensure that the stream performs no other read operations (such
573 * as async_read, the stream's async_read_some function, or any other composed
574 * operations that perform reads) until this operation completes.
576 * @param s The stream from which the data is to be read. The type must support
577 * the AsyncReadStream concept.
579 * @param b A basic_streambuf object into which the data will be read. Ownership
580 * of the streambuf is retained by the caller, which must guarantee that it
581 * remains valid until the handler is called.
583 * @param completion_condition The function object to be called to determine
584 * whether the read operation is complete. The signature of the function object
586 * @code std::size_t completion_condition(
587 * // Result of latest async_read_some operation.
588 * const boost::system::error_code& error,
590 * // Number of bytes transferred so far.
591 * std::size_t bytes_transferred
593 * A return value of 0 indicates that the read operation is complete. A non-zero
594 * return value indicates the maximum number of bytes to be read on the next
595 * call to the stream's async_read_some function.
597 * @param handler The handler to be called when the read operation completes.
598 * Copies will be made of the handler as required. The function signature of the
600 * @code void handler(
601 * const boost::system::error_code& error, // Result of operation.
603 * std::size_t bytes_transferred // Number of bytes copied into the
604 * // buffers. If an error occurred,
605 * // this will be the number of
606 * // bytes successfully transferred
607 * // prior to the error.
609 * Regardless of whether the asynchronous operation completes immediately or
610 * not, the handler will not be invoked from within this function. Invocation of
611 * the handler will be performed in a manner equivalent to using
612 * boost::asio::io_service::post().
614 template <typename AsyncReadStream, typename Allocator,
615 typename CompletionCondition, typename ReadHandler>
616 BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
617 void (boost::system::error_code, std::size_t))
618 async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
619 CompletionCondition completion_condition,
620 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
622 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
629 #include <boost/asio/detail/pop_options.hpp>
631 #include <boost/asio/impl/read.hpp>
633 #endif // BOOST_ASIO_READ_HPP