/Src/Dependencies/Boost/boost/asio/read.hpp

  1//
  2// read.hpp
  3// ~~~~~~~~
  4//
  5// Copyright (c) 2003-2011 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/basic_streambuf_fwd.hpp>
 21#include <boost/asio/error.hpp>
 22
 23#include <boost/asio/detail/push_options.hpp>
 24
 25namespace boost {
 26namespace asio {
 27
 28/**
 29 * @defgroup read boost::asio::read
 30 *
 31 * @brief Attempt to read a certain amount of data from a stream before
 32 * returning.
 33 */
 34/*@{*/
 35
 36/// Attempt to read a certain amount of data from a stream before returning.
 37/**
 38 * This function is used to read a certain number of bytes of data from a
 39 * stream. The call will block until one of the following conditions is true:
 40 *
 41 * @li The supplied buffers are full. That is, the bytes transferred is equal to
 42 * the sum of the buffer sizes.
 43 *
 44 * @li An error occurred.
 45 *
 46 * This operation is implemented in terms of zero or more calls to the stream's
 47 * read_some function.
 48 *
 49 * @param s The stream from which the data is to be read. The type must support
 50 * the SyncReadStream concept.
 51 *
 52 * @param buffers One or more buffers into which the data will be read. The sum
 53 * of the buffer sizes indicates the maximum number of bytes to read from the
 54 * stream.
 55 *
 56 * @returns The number of bytes transferred.
 57 *
 58 * @throws boost::system::system_error Thrown on failure.
 59 *
 60 * @par Example
 61 * To read into a single data buffer use the @ref buffer function as follows:
 62 * @code boost::asio::read(s, boost::asio::buffer(data, size)); @endcode
 63 * See the @ref buffer documentation for information on reading into multiple
 64 * buffers in one go, and how to use it with arrays, boost::array or
 65 * std::vector.
 66 *
 67 * @note This overload is equivalent to calling:
 68 * @code boost::asio::read(
 69 *     s, buffers,
 70 *     boost::asio::transfer_all()); @endcode
 71 */
 72template <typename SyncReadStream, typename MutableBufferSequence>
 73std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers);
 74
 75/// Attempt to read a certain amount of data from a stream before returning.
 76/**
 77 * This function is used to read a certain number of bytes of data from a
 78 * stream. The call will block until one of the following conditions is true:
 79 *
 80 * @li The supplied buffers are full. That is, the bytes transferred is equal to
 81 * the sum of the buffer sizes.
 82 *
 83 * @li An error occurred.
 84 *
 85 * This operation is implemented in terms of zero or more calls to the stream's
 86 * read_some function.
 87 *
 88 * @param s The stream from which the data is to be read. The type must support
 89 * the SyncReadStream concept.
 90 *
 91 * @param buffers One or more buffers into which the data will be read. The sum
 92 * of the buffer sizes indicates the maximum number of bytes to read from the
 93 * stream.
 94 *
 95 * @param ec Set to indicate what error occurred, if any.
 96 *
 97 * @returns The number of bytes transferred.
 98 *
 99 * @par Example
100 * To read into a single data buffer use the @ref buffer function as follows:
101 * @code boost::asio::read(s, boost::asio::buffer(data, size), ec); @endcode
102 * See the @ref buffer documentation for information on reading into multiple
103 * buffers in one go, and how to use it with arrays, boost::array or
104 * std::vector.
105 *
106 * @note This overload is equivalent to calling:
107 * @code boost::asio::read(
108 *     s, buffers,
109 *     boost::asio::transfer_all(), ec); @endcode
110 */
111template <typename SyncReadStream, typename MutableBufferSequence>
112std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
113    boost::system::error_code& ec);
114
115/// Attempt to read a certain amount of data from a stream before returning.
116/**
117 * This function is used to read a certain number of bytes of data from a
118 * stream. The call will block until one of the following conditions is true:
119 *
120 * @li The supplied buffers are full. That is, the bytes transferred is equal to
121 * the sum of the buffer sizes.
122 *
123 * @li The completion_condition function object returns 0.
124 *
125 * This operation is implemented in terms of zero or more calls to the stream's
126 * read_some function.
127 *
128 * @param s The stream from which the data is to be read. The type must support
129 * the SyncReadStream concept.
130 *
131 * @param buffers One or more buffers into which the data will be read. The sum
132 * of the buffer sizes indicates the maximum number of bytes to read from the
133 * stream.
134 *
135 * @param completion_condition The function object to be called to determine
136 * whether the read operation is complete. The signature of the function object
137 * must be:
138 * @code std::size_t completion_condition(
139 *   // Result of latest read_some operation.
140 *   const boost::system::error_code& error,
141 *
142 *   // Number of bytes transferred so far.
143 *   std::size_t bytes_transferred
144 * ); @endcode
145 * A return value of 0 indicates that the read operation is complete. A non-zero
146 * return value indicates the maximum number of bytes to be read on the next
147 * call to the stream's read_some function.
148 *
149 * @returns The number of bytes transferred.
150 *
151 * @throws boost::system::system_error Thrown on failure.
152 *
153 * @par Example
154 * To read into a single data buffer use the @ref buffer function as follows:
155 * @code boost::asio::read(s, boost::asio::buffer(data, size),
156 *     boost::asio::transfer_at_least(32)); @endcode
157 * See the @ref buffer documentation for information on reading into multiple
158 * buffers in one go, and how to use it with arrays, boost::array or
159 * std::vector.
160 */
161template <typename SyncReadStream, typename MutableBufferSequence,
162  typename CompletionCondition>
163std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
164    CompletionCondition completion_condition);
165
166/// Attempt to read a certain amount of data from a stream before returning.
167/**
168 * This function is used to read a certain number of bytes of data from a
169 * stream. The call will block until one of the following conditions is true:
170 *
171 * @li The supplied buffers are full. That is, the bytes transferred is equal to
172 * the sum of the buffer sizes.
173 *
174 * @li The completion_condition function object returns 0.
175 *
176 * This operation is implemented in terms of zero or more calls to the stream's
177 * read_some function.
178 *
179 * @param s The stream from which the data is to be read. The type must support
180 * the SyncReadStream concept.
181 *
182 * @param buffers One or more buffers into which the data will be read. The sum
183 * of the buffer sizes indicates the maximum number of bytes to read from the
184 * stream.
185 *
186 * @param completion_condition The function object to be called to determine
187 * whether the read operation is complete. The signature of the function object
188 * must be:
189 * @code std::size_t completion_condition(
190 *   // Result of latest read_some operation.
191 *   const boost::system::error_code& error,
192 *
193 *   // Number of bytes transferred so far.
194 *   std::size_t bytes_transferred
195 * ); @endcode
196 * A return value of 0 indicates that the read operation is complete. A non-zero
197 * return value indicates the maximum number of bytes to be read on the next
198 * call to the stream's read_some function.
199 *
200 * @param ec Set to indicate what error occurred, if any.
201 *
202 * @returns The number of bytes read. If an error occurs, returns the total
203 * number of bytes successfully transferred prior to the error.
204 */
205template <typename SyncReadStream, typename MutableBufferSequence,
206    typename CompletionCondition>
207std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
208    CompletionCondition completion_condition, boost::system::error_code& ec);
209
210#if !defined(BOOST_NO_IOSTREAM)
211
212/// Attempt to read a certain amount of data from a stream before returning.
213/**
214 * This function is used to read a certain number of bytes of data from a
215 * stream. The call will block until one of the following conditions is true:
216 *
217 * @li An error occurred.
218 *
219 * This operation is implemented in terms of zero or more calls to the stream's
220 * read_some function.
221 *
222 * @param s The stream from which the data is to be read. The type must support
223 * the SyncReadStream concept.
224 *
225 * @param b The basic_streambuf object into which the data will be read.
226 *
227 * @returns The number of bytes transferred.
228 *
229 * @throws boost::system::system_error Thrown on failure.
230 *
231 * @note This overload is equivalent to calling:
232 * @code boost::asio::read(
233 *     s, b,
234 *     boost::asio::transfer_all()); @endcode
235 */
236template <typename SyncReadStream, typename Allocator>
237std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b);
238
239/// Attempt to read a certain amount of data from a stream before returning.
240/**
241 * This function is used to read a certain number of bytes of data from a
242 * stream. The call will block until one of the following conditions is true:
243 *
244 * @li An error occurred.
245 *
246 * This operation is implemented in terms of zero or more calls to the stream's
247 * read_some function.
248 *
249 * @param s The stream from which the data is to be read. The type must support
250 * the SyncReadStream concept.
251 *
252 * @param b The basic_streambuf object into which the data will be read.
253 *
254 * @param ec Set to indicate what error occurred, if any.
255 *
256 * @returns The number of bytes transferred.
257 *
258 * @note This overload is equivalent to calling:
259 * @code boost::asio::read(
260 *     s, b,
261 *     boost::asio::transfer_all(), ec); @endcode
262 */
263template <typename SyncReadStream, typename Allocator>
264std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
265    boost::system::error_code& ec);
266
267/// Attempt to read a certain amount of data from a stream before returning.
268/**
269 * This function is used to read a certain number of bytes of data from a
270 * stream. The call will block until one of the following conditions is true:
271 *
272 * @li The completion_condition function object returns 0.
273 *
274 * This operation is implemented in terms of zero or more calls to the stream's
275 * read_some function.
276 *
277 * @param s The stream from which the data is to be read. The type must support
278 * the SyncReadStream concept.
279 *
280 * @param b The basic_streambuf object into which the data will be read.
281 *
282 * @param completion_condition The function object to be called to determine
283 * whether the read operation is complete. The signature of the function object
284 * must be:
285 * @code std::size_t completion_condition(
286 *   // Result of latest read_some operation.
287 *   const boost::system::error_code& error,
288 *
289 *   // Number of bytes transferred so far.
290 *   std::size_t bytes_transferred
291 * ); @endcode
292 * A return value of 0 indicates that the read operation is complete. A non-zero
293 * return value indicates the maximum number of bytes to be read on the next
294 * call to the stream's read_some function.
295 *
296 * @returns The number of bytes transferred.
297 *
298 * @throws boost::system::system_error Thrown on failure.
299 */
300template <typename SyncReadStream, typename Allocator,
301    typename CompletionCondition>
302std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
303    CompletionCondition completion_condition);
304
305/// Attempt to read a certain amount of data from a stream before returning.
306/**
307 * This function is used to read a certain number of bytes of data from a
308 * stream. The call will block until one of the following conditions is true:
309 *
310 * @li The completion_condition function object returns 0.
311 *
312 * This operation is implemented in terms of zero or more calls to the stream's
313 * read_some function.
314 *
315 * @param s The stream from which the data is to be read. The type must support
316 * the SyncReadStream concept.
317 *
318 * @param b The basic_streambuf object into which the data will be read.
319 *
320 * @param completion_condition The function object to be called to determine
321 * whether the read operation is complete. The signature of the function object
322 * must be:
323 * @code std::size_t completion_condition(
324 *   // Result of latest read_some operation.
325 *   const boost::system::error_code& error,
326 *
327 *   // Number of bytes transferred so far.
328 *   std::size_t bytes_transferred
329 * ); @endcode
330 * A return value of 0 indicates that the read operation is complete. A non-zero
331 * return value indicates the maximum number of bytes to be read on the next
332 * call to the stream's read_some function.
333 *
334 * @param ec Set to indicate what error occurred, if any.
335 *
336 * @returns The number of bytes read. If an error occurs, returns the total
337 * number of bytes successfully transferred prior to the error.
338 */
339template <typename SyncReadStream, typename Allocator,
340    typename CompletionCondition>
341std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
342    CompletionCondition completion_condition, boost::system::error_code& ec);
343
344#endif // !defined(BOOST_NO_IOSTREAM)
345
346/*@}*/
347/**
348 * @defgroup async_read boost::asio::async_read
349 *
350 * @brief Start an asynchronous operation to read a certain amount of data from
351 * a stream.
352 */
353/*@{*/
354
355/// Start an asynchronous operation to read a certain amount of data from a
356/// stream.
357/**
358 * This function is used to asynchronously read a certain number of bytes of
359 * data from a stream. The function call always returns immediately. The
360 * asynchronous operation will continue until one of the following conditions is
361 * true:
362 *
363 * @li The supplied buffers are full. That is, the bytes transferred is equal to
364 * the sum of the buffer sizes.
365 *
366 * @li An error occurred.
367 *
368 * This operation is implemented in terms of zero or more calls to the stream's
369 * async_read_some function, and is known as a <em>composed operation</em>. The
370 * program must ensure that the stream performs no other read operations (such
371 * as async_read, the stream's async_read_some function, or any other composed
372 * operations that perform reads) until this operation completes.
373 *
374 * @param s The stream from which the data is to be read. The type must support
375 * the AsyncReadStream concept.
376 *
377 * @param buffers One or more buffers into which the data will be read. The sum
378 * of the buffer sizes indicates the maximum number of bytes to read from the
379 * stream. Although the buffers object may be copied as necessary, ownership of
380 * the underlying memory blocks is retained by the caller, which must guarantee
381 * that they remain valid until the handler is called.
382 *
383 * @param handler The handler to be called when the read operation completes.
384 * Copies will be made of the handler as required. The function signature of the
385 * handler must be:
386 * @code void handler(
387 *   const boost::system::error_code& error, // Result of operation.
388 *
389 *   std::size_t bytes_transferred           // Number of bytes copied into the
390 *                                           // buffers. If an error occurred,
391 *                                           // this will be the  number of
392 *                                           // bytes successfully transferred
393 *                                           // prior to the error.
394 * ); @endcode
395 * Regardless of whether the asynchronous operation completes immediately or
396 * not, the handler will not be invoked from within this function. Invocation of
397 * the handler will be performed in a manner equivalent to using
398 * boost::asio::io_service::post().
399 *
400 * @par Example
401 * To read into a single data buffer use the @ref buffer function as follows:
402 * @code
403 * boost::asio::async_read(s, boost::asio::buffer(data, size), handler);
404 * @endcode
405 * See the @ref buffer documentation for information on reading into multiple
406 * buffers in one go, and how to use it with arrays, boost::array or
407 * std::vector.
408 *
409 * @note This overload is equivalent to calling:
410 * @code boost::asio::async_read(
411 *     s, buffers,
412 *     boost::asio::transfer_all(),
413 *     handler); @endcode
414 */
415template <typename AsyncReadStream, typename MutableBufferSequence,
416    typename ReadHandler>
417void async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
418    BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
419
420/// Start an asynchronous operation to read a certain amount of data from a
421/// stream.
422/**
423 * This function is used to asynchronously read a certain number of bytes of
424 * data from a stream. The function call always returns immediately. The
425 * asynchronous operation will continue until one of the following conditions is
426 * true:
427 *
428 * @li The supplied buffers are full. That is, the bytes transferred is equal to
429 * the sum of the buffer sizes.
430 *
431 * @li The completion_condition function object returns 0.
432 *
433 * @param s The stream from which the data is to be read. The type must support
434 * the AsyncReadStream concept.
435 *
436 * @param buffers One or more buffers into which the data will be read. The sum
437 * of the buffer sizes indicates the maximum number of bytes to read from the
438 * stream. Although the buffers object may be copied as necessary, ownership of
439 * the underlying memory blocks is retained by the caller, which must guarantee
440 * that they remain valid until the handler is called.
441 *
442 * @param completion_condition The function object to be called to determine
443 * whether the read operation is complete. The signature of the function object
444 * must be:
445 * @code std::size_t completion_condition(
446 *   // Result of latest async_read_some operation.
447 *   const boost::system::error_code& error,
448 *
449 *   // Number of bytes transferred so far.
450 *   std::size_t bytes_transferred
451 * ); @endcode
452 * A return value of 0 indicates that the read operation is complete. A non-zero
453 * return value indicates the maximum number of bytes to be read on the next
454 * call to the stream's async_read_some function.
455 *
456 * @param handler The handler to be called when the read operation completes.
457 * Copies will be made of the handler as required. The function signature of the
458 * handler must be:
459 * @code void handler(
460 *   const boost::system::error_code& error, // Result of operation.
461 *
462 *   std::size_t bytes_transferred           // Number of bytes copied into the
463 *                                           // buffers. If an error occurred,
464 *                                           // this will be the  number of
465 *                                           // bytes successfully transferred
466 *                                           // prior to the error.
467 * ); @endcode
468 * Regardless of whether the asynchronous operation completes immediately or
469 * not, the handler will not be invoked from within this function. Invocation of
470 * the handler will be performed in a manner equivalent to using
471 * boost::asio::io_service::post().
472 *
473 * @par Example
474 * To read into a single data buffer use the @ref buffer function as follows:
475 * @code boost::asio::async_read(s,
476 *     boost::asio::buffer(data, size),
477 *     boost::asio::transfer_at_least(32),
478 *     handler); @endcode
479 * See the @ref buffer documentation for information on reading into multiple
480 * buffers in one go, and how to use it with arrays, boost::array or
481 * std::vector.
482 */
483template <typename AsyncReadStream, typename MutableBufferSequence,
484    typename CompletionCondition, typename ReadHandler>
485void async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
486    CompletionCondition completion_condition,
487    BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
488
489#if !defined(BOOST_NO_IOSTREAM)
490
491/// Start an asynchronous operation to read a certain amount of data from a
492/// stream.
493/**
494 * This function is used to asynchronously read a certain number of bytes of
495 * data from a stream. The function call always returns immediately. The
496 * asynchronous operation will continue until one of the following conditions is
497 * true:
498 *
499 * @li An error occurred.
500 *
501 * This operation is implemented in terms of zero or more calls to the stream's
502 * async_read_some function, and is known as a <em>composed operation</em>. The
503 * program must ensure that the stream performs no other read operations (such
504 * as async_read, the stream's async_read_some function, or any other composed
505 * operations that perform reads) until this operation completes.
506 *
507 * @param s The stream from which the data is to be read. The type must support
508 * the AsyncReadStream concept.
509 *
510 * @param b A basic_streambuf object into which the data will be read. Ownership
511 * of the streambuf is retained by the caller, which must guarantee that it
512 * remains valid until the handler is called.
513 *
514 * @param handler The handler to be called when the read operation completes.
515 * Copies will be made of the handler as required. The function signature of the
516 * handler must be:
517 * @code void handler(
518 *   const boost::system::error_code& error, // Result of operation.
519 *
520 *   std::size_t bytes_transferred           // Number of bytes copied into the
521 *                                           // buffers. If an error occurred,
522 *                                           // this will be the  number of
523 *                                           // bytes successfully transferred
524 *                                           // prior to the error.
525 * ); @endcode
526 * Regardless of whether the asynchronous operation completes immediately or
527 * not, the handler will not be invoked from within this function. Invocation of
528 * the handler will be performed in a manner equivalent to using
529 * boost::asio::io_service::post().
530 *
531 * @note This overload is equivalent to calling:
532 * @code boost::asio::async_read(
533 *     s, b,
534 *     boost::asio::transfer_all(),
535 *     handler); @endcode
536 */
537template <typename AsyncReadStream, typename Allocator, typename ReadHandler>
538void async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
539    BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
540
541/// Start an asynchronous operation to read a certain amount of data from a
542/// stream.
543/**
544 * This function is used to asynchronously read a certain number of bytes of
545 * data from a stream. The function call always returns immediately. The
546 * asynchronous operation will continue until one of the following conditions is
547 * true:
548 *
549 * @li The completion_condition function object returns 0.
550 *
551 * This operation is implemented in terms of zero or more calls to the stream's
552 * async_read_some function, and is known as a <em>composed operation</em>. The
553 * program must ensure that the stream performs no other read operations (such
554 * as async_read, the stream's async_read_some function, or any other composed
555 * operations that perform reads) until this operation completes.
556 *
557 * @param s The stream from which the data is to be read. The type must support
558 * the AsyncReadStream concept.
559 *
560 * @param b A basic_streambuf object into which the data will be read. Ownership
561 * of the streambuf is retained by the caller, which must guarantee that it
562 * remains valid until the handler is called.
563 *
564 * @param completion_condition The function object to be called to determine
565 * whether the read operation is complete. The signature of the function object
566 * must be:
567 * @code std::size_t completion_condition(
568 *   // Result of latest async_read_some operation.
569 *   const boost::system::error_code& error,
570 *
571 *   // Number of bytes transferred so far.
572 *   std::size_t bytes_transferred
573 * ); @endcode
574 * A return value of 0 indicates that the read operation is complete. A non-zero
575 * return value indicates the maximum number of bytes to be read on the next
576 * call to the stream's async_read_some function.
577 *
578 * @param handler The handler to be called when the read operation completes.
579 * Copies will be made of the handler as required. The function signature of the
580 * handler must be:
581 * @code void handler(
582 *   const boost::system::error_code& error, // Result of operation.
583 *
584 *   std::size_t bytes_transferred           // Number of bytes copied into the
585 *                                           // buffers. If an error occurred,
586 *                                           // this will be the  number of
587 *                                           // bytes successfully transferred
588 *                                           // prior to the error.
589 * ); @endcode
590 * Regardless of whether the asynchronous operation completes immediately or
591 * not, the handler will not be invoked from within this function. Invocation of
592 * the handler will be performed in a manner equivalent to using
593 * boost::asio::io_service::post().
594 */
595template <typename AsyncReadStream, typename Allocator,
596    typename CompletionCondition, typename ReadHandler>
597void async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
598    CompletionCondition completion_condition,
599    BOOST_ASIO_MOVE_ARG(ReadHandler) handler);
600
601#endif // !defined(BOOST_NO_IOSTREAM)
602
603/*@}*/
604
605} // namespace asio
606} // namespace boost
607
608#include <boost/asio/detail/pop_options.hpp>
609
610#include <boost/asio/impl/read.hpp>
611
612#endif // BOOST_ASIO_READ_HPP