1//
2// read.hpp
3// ~~~~~~~~
4//
5// Copyright (c) 2003-2015 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/basic_streambuf_fwd.hpp>
22#include <boost/asio/error.hpp>
23
24#include <boost/asio/detail/push_options.hpp>
25
26namespace boost {
27namespace asio {
28
29/**
30 * @defgroup read boost::asio::read
31 *
32 * @brief Attempt to read a certain amount of data from a stream before
33 * returning.
34 */
35/*@{*/
36
37/// Attempt to read a certain amount of data from a stream before returning.
38/**
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:
41 *
42 * @li The supplied buffers are full. That is, the bytes transferred is equal to
43 * the sum of the buffer sizes.
44 *
45 * @li An error occurred.
46 *
47 * This operation is implemented in terms of zero or more calls to the stream's
48 * read_some function.
49 *
50 * @param s The stream from which the data is to be read. The type must support
51 * the SyncReadStream concept.
52 *
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
55 * stream.
56 *
57 * @returns The number of bytes transferred.
58 *
59 * @throws boost::system::system_error Thrown on failure.
60 *
61 * @par Example
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
66 * std::vector.
67 *
68 * @note This overload is equivalent to calling:
69 * @code boost::asio::read(
70 * s, buffers,
71 * boost::asio::transfer_all()); @endcode
72 */
73template <typename SyncReadStream, typename MutableBufferSequence>
74std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers);
75
76/// Attempt to read a certain amount of data from a stream before returning.
77/**
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:
80 *
81 * @li The supplied buffers are full. That is, the bytes transferred is equal to
82 * the sum of the buffer sizes.
83 *
84 * @li An error occurred.
85 *
86 * This operation is implemented in terms of zero or more calls to the stream's
87 * read_some function.
88 *
89 * @param s The stream from which the data is to be read. The type must support
90 * the SyncReadStream concept.
91 *
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
94 * stream.
95 *
96 * @param ec Set to indicate what error occurred, if any.
97 *
98 * @returns The number of bytes transferred.
99 *
100 * @par Example
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
105 * std::vector.
106 *
107 * @note This overload is equivalent to calling:
108 * @code boost::asio::read(
109 * s, buffers,
110 * boost::asio::transfer_all(), ec); @endcode
111 */
112template <typename SyncReadStream, typename MutableBufferSequence>
113std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
114 boost::system::error_code& ec);
115
116/// Attempt to read a certain amount of data from a stream before returning.
117/**
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:
120 *
121 * @li The supplied buffers are full. That is, the bytes transferred is equal to
122 * the sum of the buffer sizes.
123 *
124 * @li The completion_condition function object returns 0.
125 *
126 * This operation is implemented in terms of zero or more calls to the stream's
127 * read_some function.
128 *
129 * @param s The stream from which the data is to be read. The type must support
130 * the SyncReadStream concept.
131 *
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
134 * stream.
135 *
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
138 * must be:
139 * @code std::size_t completion_condition(
140 * // Result of latest read_some operation.
141 * const boost::system::error_code& error,
142 *
143 * // Number of bytes transferred so far.
144 * std::size_t bytes_transferred
145 * ); @endcode
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.
149 *
150 * @returns The number of bytes transferred.
151 *
152 * @throws boost::system::system_error Thrown on failure.
153 *
154 * @par Example
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
160 * std::vector.
161 */
162template <typename SyncReadStream, typename MutableBufferSequence,
163 typename CompletionCondition>
164std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
165 CompletionCondition completion_condition);
166
167/// Attempt to read a certain amount of data from a stream before returning.
168/**
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:
171 *
172 * @li The supplied buffers are full. That is, the bytes transferred is equal to
173 * the sum of the buffer sizes.
174 *
175 * @li The completion_condition function object returns 0.
176 *
177 * This operation is implemented in terms of zero or more calls to the stream's
178 * read_some function.
179 *
180 * @param s The stream from which the data is to be read. The type must support
181 * the SyncReadStream concept.
182 *
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
185 * stream.
186 *
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
189 * must be:
190 * @code std::size_t completion_condition(
191 * // Result of latest read_some operation.
192 * const boost::system::error_code& error,
193 *
194 * // Number of bytes transferred so far.
195 * std::size_t bytes_transferred
196 * ); @endcode
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.
200 *
201 * @param ec Set to indicate what error occurred, if any.
202 *
203 * @returns The number of bytes read. If an error occurs, returns the total
204 * number of bytes successfully transferred prior to the error.
205 */
206template <typename SyncReadStream, typename MutableBufferSequence,
207 typename CompletionCondition>
208std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
209 CompletionCondition completion_condition, boost::system::error_code& ec);
210
211#if !defined(BOOST_ASIO_NO_IOSTREAM)
212
213/// Attempt to read a certain amount of data from a stream before returning.
214/**
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:
217 *
218 * @li The supplied buffer is full (that is, it has reached maximum size).
219 *
220 * @li An error occurred.
221 *
222 * This operation is implemented in terms of zero or more calls to the stream's
223 * read_some function.
224 *
225 * @param s The stream from which the data is to be read. The type must support
226 * the SyncReadStream concept.
227 *
228 * @param b The basic_streambuf object into which the data will be read.
229 *
230 * @returns The number of bytes transferred.
231 *
232 * @throws boost::system::system_error Thrown on failure.
233 *
234 * @note This overload is equivalent to calling:
235 * @code boost::asio::read(
236 * s, b,
237 * boost::asio::transfer_all()); @endcode
238 */
239template <typename SyncReadStream, typename Allocator>
240std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b);
241
242/// Attempt to read a certain amount of data from a stream before returning.
243/**
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:
246 *
247 * @li The supplied buffer is full (that is, it has reached maximum size).
248 *
249 * @li An error occurred.
250 *
251 * This operation is implemented in terms of zero or more calls to the stream's
252 * read_some function.
253 *
254 * @param s The stream from which the data is to be read. The type must support
255 * the SyncReadStream concept.
256 *
257 * @param b The basic_streambuf object into which the data will be read.
258 *
259 * @param ec Set to indicate what error occurred, if any.
260 *
261 * @returns The number of bytes transferred.
262 *
263 * @note This overload is equivalent to calling:
264 * @code boost::asio::read(
265 * s, b,
266 * boost::asio::transfer_all(), ec); @endcode
267 */
268template <typename SyncReadStream, typename Allocator>
269std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
270 boost::system::error_code& ec);
271
272/// Attempt to read a certain amount of data from a stream before returning.
273/**
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:
276 *
277 * @li The supplied buffer is full (that is, it has reached maximum size).
278 *
279 * @li The completion_condition function object returns 0.
280 *
281 * This operation is implemented in terms of zero or more calls to the stream's
282 * read_some function.
283 *
284 * @param s The stream from which the data is to be read. The type must support
285 * the SyncReadStream concept.
286 *
287 * @param b The basic_streambuf object into which the data will be read.
288 *
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
291 * must be:
292 * @code std::size_t completion_condition(
293 * // Result of latest read_some operation.
294 * const boost::system::error_code& error,
295 *
296 * // Number of bytes transferred so far.
297 * std::size_t bytes_transferred
298 * ); @endcode
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.
302 *
303 * @returns The number of bytes transferred.
304 *
305 * @throws boost::system::system_error Thrown on failure.
306 */
307template <typename SyncReadStream, typename Allocator,
308 typename CompletionCondition>
309std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
310 CompletionCondition completion_condition);
311
312/// Attempt to read a certain amount of data from a stream before returning.
313/**
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:
316 *
317 * @li The supplied buffer is full (that is, it has reached maximum size).
318 *
319 * @li The completion_condition function object returns 0.
320 *
321 * This operation is implemented in terms of zero or more calls to the stream's
322 * read_some function.
323 *
324 * @param s The stream from which the data is to be read. The type must support
325 * the SyncReadStream concept.
326 *
327 * @param b The basic_streambuf object into which the data will be read.
328 *
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
331 * must be:
332 * @code std::size_t completion_condition(
333 * // Result of latest read_some operation.
334 * const boost::system::error_code& error,
335 *
336 * // Number of bytes transferred so far.
337 * std::size_t bytes_transferred
338 * ); @endcode
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.
342 *
343 * @param ec Set to indicate what error occurred, if any.
344 *
345 * @returns The number of bytes read. If an error occurs, returns the total
346 * number of bytes successfully transferred prior to the error.
347 */
348template <typename SyncReadStream, typename Allocator,
349 typename CompletionCondition>
350std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
351 CompletionCondition completion_condition, boost::system::error_code& ec);
352
353#endif // !defined(BOOST_ASIO_NO_IOSTREAM)
354
355/*@}*/
356/**
357 * @defgroup async_read boost::asio::async_read
358 *
359 * @brief Start an asynchronous operation to read a certain amount of data from
360 * a stream.
361 */
362/*@{*/
363
364/// Start an asynchronous operation to read a certain amount of data from a
365/// stream.
366/**
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
370 * true:
371 *
372 * @li The supplied buffers are full. That is, the bytes transferred is equal to
373 * the sum of the buffer sizes.
374 *
375 * @li An error occurred.
376 *
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.
382 *
383 * @param s The stream from which the data is to be read. The type must support
384 * the AsyncReadStream concept.
385 *
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.
391 *
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
394 * handler must be:
395 * @code void handler(
396 * const boost::system::error_code& error, // Result of operation.
397 *
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.
403 * ); @endcode
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().
408 *
409 * @par Example
410 * To read into a single data buffer use the @ref buffer function as follows:
411 * @code
412 * boost::asio::async_read(s, boost::asio::buffer(data, size), handler);
413 * @endcode
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
416 * std::vector.
417 *
418 * @note This overload is equivalent to calling:
419 * @code boost::asio::async_read(
420 * s, buffers,
421 * boost::asio::transfer_all(),
422 * handler); @endcode
423 */
424template <typename AsyncReadStream, typename MutableBufferSequence,
425 typename ReadHandler>
426BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
427 void (boost::system::error_code, std::size_t))
428async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
429 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
430
431/// Start an asynchronous operation to read a certain amount of data from a
432/// stream.
433/**
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
437 * true:
438 *
439 * @li The supplied buffers are full. That is, the bytes transferred is equal to
440 * the sum of the buffer sizes.
441 *
442 * @li The completion_condition function object returns 0.
443 *
444 * @param s The stream from which the data is to be read. The type must support
445 * the AsyncReadStream concept.
446 *
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.
452 *
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
455 * must be:
456 * @code std::size_t completion_condition(
457 * // Result of latest async_read_some operation.
458 * const boost::system::error_code& error,
459 *
460 * // Number of bytes transferred so far.
461 * std::size_t bytes_transferred
462 * ); @endcode
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.
466 *
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
469 * handler must be:
470 * @code void handler(
471 * const boost::system::error_code& error, // Result of operation.
472 *
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.
478 * ); @endcode
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().
483 *
484 * @par Example
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),
489 * handler); @endcode
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
492 * std::vector.
493 */
494template <typename AsyncReadStream, typename MutableBufferSequence,
495 typename CompletionCondition, typename ReadHandler>
496BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
497 void (boost::system::error_code, std::size_t))
498async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
499 CompletionCondition completion_condition,
500 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
501
502#if !defined(BOOST_ASIO_NO_IOSTREAM)
503
504/// Start an asynchronous operation to read a certain amount of data from a
505/// stream.
506/**
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
510 * true:
511 *
512 * @li The supplied buffer is full (that is, it has reached maximum size).
513 *
514 * @li An error occurred.
515 *
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.
521 *
522 * @param s The stream from which the data is to be read. The type must support
523 * the AsyncReadStream concept.
524 *
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.
528 *
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
531 * handler must be:
532 * @code void handler(
533 * const boost::system::error_code& error, // Result of operation.
534 *
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.
540 * ); @endcode
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().
545 *
546 * @note This overload is equivalent to calling:
547 * @code boost::asio::async_read(
548 * s, b,
549 * boost::asio::transfer_all(),
550 * handler); @endcode
551 */
552template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
553BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
554 void (boost::system::error_code, std::size_t))
555async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
556 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
557
558/// Start an asynchronous operation to read a certain amount of data from a
559/// stream.
560/**
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
564 * true:
565 *
566 * @li The supplied buffer is full (that is, it has reached maximum size).
567 *
568 * @li The completion_condition function object returns 0.
569 *
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.
575 *
576 * @param s The stream from which the data is to be read. The type must support
577 * the AsyncReadStream concept.
578 *
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.
582 *
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
585 * must be:
586 * @code std::size_t completion_condition(
587 * // Result of latest async_read_some operation.
588 * const boost::system::error_code& error,
589 *
590 * // Number of bytes transferred so far.
591 * std::size_t bytes_transferred
592 * ); @endcode
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.
596 *
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
599 * handler must be:
600 * @code void handler(
601 * const boost::system::error_code& error, // Result of operation.
602 *
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.
608 * ); @endcode
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().
613 */
614template <typename AsyncReadStream, typename Allocator,
615 typename CompletionCondition, typename ReadHandler>
616BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
617 void (boost::system::error_code, std::size_t))
618async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
619 CompletionCondition completion_condition,
620 BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
621
622#endif // !defined(BOOST_ASIO_NO_IOSTREAM)
623
624/*@}*/
625
626} // namespace asio
627} // namespace boost
628
629#include <boost/asio/detail/pop_options.hpp>
630
631#include <boost/asio/impl/read.hpp>
632
633#endif // BOOST_ASIO_READ_HPP
634