boost/asio/read.hpp

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