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 ASIO_READ_HPP 12 #define ASIO_READ_HPP 13 14 15 #include "asio/detail/config.hpp" 16 #include <cstddef> 17 #include "asio/async_result.hpp" 18 #include "asio/basic_streambuf_fwd.hpp" 19 #include "asio/error.hpp" 20 21 #include "asio/detail/push_options.hpp" 22 23 namespace asio { 24 25 /** 26 * @defgroup read asio::read 27 * 28 * @brief Attempt to read a certain amount of data from a stream before 29 * returning. 30 */ 31 /*@{*/ 32 33 /// Attempt to read a certain amount of data from a stream before returning. 34 /** 35 * This function is used to read a certain number of bytes of data from a 36 * stream. The call will block until one of the following conditions is true: 37 * 38 * @li The supplied buffers are full. That is, the bytes transferred is equal to 39 * the sum of the buffer sizes. 40 * 41 * @li An error occurred. 42 * 43 * This operation is implemented in terms of zero or more calls to the stream's 44 * read_some function. 45 * 46 * @param s The stream from which the data is to be read. The type must support 47 * the SyncReadStream concept. 48 * 49 * @param buffers One or more buffers into which the data will be read. The sum 50 * of the buffer sizes indicates the maximum number of bytes to read from the 51 * stream. 52 * 53 * @returns The number of bytes transferred. 54 * 55 * @throws asio::system_error Thrown on failure. 56 * 57 * @par Example 58 * To read into a single data buffer use the @ref buffer function as follows: 59 * @code asio::read(s, asio::buffer(data, size)); @endcode 60 * See the @ref buffer documentation for information on reading into multiple 61 * buffers in one go, and how to use it with arrays, boost::array or 62 * std::vector. 63 * 64 * @note This overload is equivalent to calling: 65 * @code asio::read( 66 * s, buffers, 67 * asio::transfer_all()); @endcode 68 */ 69 template <typename SyncReadStream, typename MutableBufferSequence> 70 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers); 71 72 /// Attempt to read a certain amount of data from a stream before returning. 73 /** 74 * This function is used to read a certain number of bytes of data from a 75 * stream. The call will block until one of the following conditions is true: 76 * 77 * @li The supplied buffers are full. That is, the bytes transferred is equal to 78 * the sum of the buffer sizes. 79 * 80 * @li An error occurred. 81 * 82 * This operation is implemented in terms of zero or more calls to the stream's 83 * read_some function. 84 * 85 * @param s The stream from which the data is to be read. The type must support 86 * the SyncReadStream concept. 87 * 88 * @param buffers One or more buffers into which the data will be read. The sum 89 * of the buffer sizes indicates the maximum number of bytes to read from the 90 * stream. 91 * 92 * @param ec Set to indicate what error occurred, if any. 93 * 94 * @returns The number of bytes transferred. 95 * 96 * @par Example 97 * To read into a single data buffer use the @ref buffer function as follows: 98 * @code asio::read(s, asio::buffer(data, size), ec); @endcode 99 * See the @ref buffer documentation for information on reading into multiple 100 * buffers in one go, and how to use it with arrays, boost::array or 101 * std::vector. 102 * 103 * @note This overload is equivalent to calling: 104 * @code asio::read( 105 * s, buffers, 106 * asio::transfer_all(), ec); @endcode 107 */ 108 template <typename SyncReadStream, typename MutableBufferSequence> 109 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, 110 asio::error_code& ec); 111 112 /// Attempt to read a certain amount of data from a stream before returning. 113 /** 114 * This function is used to read a certain number of bytes of data from a 115 * stream. The call will block until one of the following conditions is true: 116 * 117 * @li The supplied buffers are full. That is, the bytes transferred is equal to 118 * the sum of the buffer sizes. 119 * 120 * @li The completion_condition function object returns 0. 121 * 122 * This operation is implemented in terms of zero or more calls to the stream's 123 * read_some function. 124 * 125 * @param s The stream from which the data is to be read. The type must support 126 * the SyncReadStream concept. 127 * 128 * @param buffers One or more buffers into which the data will be read. The sum 129 * of the buffer sizes indicates the maximum number of bytes to read from the 130 * stream. 131 * 132 * @param completion_condition The function object to be called to determine 133 * whether the read operation is complete. The signature of the function object 134 * must be: 135 * @code std::size_t completion_condition( 136 * // Result of latest read_some operation. 137 * const asio::error_code& error, 138 * 139 * // Number of bytes transferred so far. 140 * std::size_t bytes_transferred 141 * ); @endcode 142 * A return value of 0 indicates that the read operation is complete. A non-zero 143 * return value indicates the maximum number of bytes to be read on the next 144 * call to the stream's read_some function. 145 * 146 * @returns The number of bytes transferred. 147 * 148 * @throws asio::system_error Thrown on failure. 149 * 150 * @par Example 151 * To read into a single data buffer use the @ref buffer function as follows: 152 * @code asio::read(s, asio::buffer(data, size), 153 * asio::transfer_at_least(32)); @endcode 154 * See the @ref buffer documentation for information on reading into multiple 155 * buffers in one go, and how to use it with arrays, boost::array or 156 * std::vector. 157 */ 158 template <typename SyncReadStream, typename MutableBufferSequence, 159 typename CompletionCondition> 160 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, 161 CompletionCondition completion_condition); 162 163 /// Attempt to read a certain amount of data from a stream before returning. 164 /** 165 * This function is used to read a certain number of bytes of data from a 166 * stream. The call will block until one of the following conditions is true: 167 * 168 * @li The supplied buffers are full. That is, the bytes transferred is equal to 169 * the sum of the buffer sizes. 170 * 171 * @li The completion_condition function object returns 0. 172 * 173 * This operation is implemented in terms of zero or more calls to the stream's 174 * read_some function. 175 * 176 * @param s The stream from which the data is to be read. The type must support 177 * the SyncReadStream concept. 178 * 179 * @param buffers One or more buffers into which the data will be read. The sum 180 * of the buffer sizes indicates the maximum number of bytes to read from the 181 * stream. 182 * 183 * @param completion_condition The function object to be called to determine 184 * whether the read operation is complete. The signature of the function object 185 * must be: 186 * @code std::size_t completion_condition( 187 * // Result of latest read_some operation. 188 * const asio::error_code& error, 189 * 190 * // Number of bytes transferred so far. 191 * std::size_t bytes_transferred 192 * ); @endcode 193 * A return value of 0 indicates that the read operation is complete. A non-zero 194 * return value indicates the maximum number of bytes to be read on the next 195 * call to the stream's read_some function. 196 * 197 * @param ec Set to indicate what error occurred, if any. 198 * 199 * @returns The number of bytes read. If an error occurs, returns the total 200 * number of bytes successfully transferred prior to the error. 201 */ 202 template <typename SyncReadStream, typename MutableBufferSequence, 203 typename CompletionCondition> 204 std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers, 205 CompletionCondition completion_condition, asio::error_code& ec); 206 207 208 /*@}*/ 209 /** 210 * @defgroup async_read asio::async_read 211 * 212 * @brief Start an asynchronous operation to read a certain amount of data from 213 * a stream. 214 */ 215 /*@{*/ 216 217 /// Start an asynchronous operation to read a certain amount of data from a 218 /// stream. 219 /** 220 * This function is used to asynchronously read a certain number of bytes of 221 * data from a stream. The function call always returns immediately. The 222 * asynchronous operation will continue until one of the following conditions is 223 * true: 224 * 225 * @li The supplied buffers are full. That is, the bytes transferred is equal to 226 * the sum of the buffer sizes. 227 * 228 * @li An error occurred. 229 * 230 * This operation is implemented in terms of zero or more calls to the stream's 231 * async_read_some function, and is known as a <em>composed operation</em>. The 232 * program must ensure that the stream performs no other read operations (such 233 * as async_read, the stream's async_read_some function, or any other composed 234 * operations that perform reads) until this operation completes. 235 * 236 * @param s The stream from which the data is to be read. The type must support 237 * the AsyncReadStream concept. 238 * 239 * @param buffers One or more buffers into which the data will be read. The sum 240 * of the buffer sizes indicates the maximum number of bytes to read from the 241 * stream. Although the buffers object may be copied as necessary, ownership of 242 * the underlying memory blocks is retained by the caller, which must guarantee 243 * that they remain valid until the handler is called. 244 * 245 * @param handler The handler to be called when the read operation completes. 246 * Copies will be made of the handler as required. The function signature of the 247 * handler must be: 248 * @code void handler( 249 * const asio::error_code& error, // Result of operation. 250 * 251 * std::size_t bytes_transferred // Number of bytes copied into the 252 * // buffers. If an error occurred, 253 * // this will be the number of 254 * // bytes successfully transferred 255 * // prior to the error. 256 * ); @endcode 257 * Regardless of whether the asynchronous operation completes immediately or 258 * not, the handler will not be invoked from within this function. Invocation of 259 * the handler will be performed in a manner equivalent to using 260 * asio::io_service::post(). 261 * 262 * @par Example 263 * To read into a single data buffer use the @ref buffer function as follows: 264 * @code 265 * asio::async_read(s, asio::buffer(data, size), handler); 266 * @endcode 267 * See the @ref buffer documentation for information on reading into multiple 268 * buffers in one go, and how to use it with arrays, boost::array or 269 * std::vector. 270 * 271 * @note This overload is equivalent to calling: 272 * @code asio::async_read( 273 * s, buffers, 274 * asio::transfer_all(), 275 * handler); @endcode 276 */ 277 template <typename AsyncReadStream, typename MutableBufferSequence, 278 typename ReadHandler> 279 ASIO_INITFN_RESULT_TYPE(ReadHandler, 280 void (asio::error_code, std::size_t)) 281 async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, 282 ASIO_MOVE_ARG(ReadHandler) handler); 283 284 /// Start an asynchronous operation to read a certain amount of data from a 285 /// stream. 286 /** 287 * This function is used to asynchronously read a certain number of bytes of 288 * data from a stream. The function call always returns immediately. The 289 * asynchronous operation will continue until one of the following conditions is 290 * true: 291 * 292 * @li The supplied buffers are full. That is, the bytes transferred is equal to 293 * the sum of the buffer sizes. 294 * 295 * @li The completion_condition function object returns 0. 296 * 297 * @param s The stream from which the data is to be read. The type must support 298 * the AsyncReadStream concept. 299 * 300 * @param buffers One or more buffers into which the data will be read. The sum 301 * of the buffer sizes indicates the maximum number of bytes to read from the 302 * stream. Although the buffers object may be copied as necessary, ownership of 303 * the underlying memory blocks is retained by the caller, which must guarantee 304 * that they remain valid until the handler is called. 305 * 306 * @param completion_condition The function object to be called to determine 307 * whether the read operation is complete. The signature of the function object 308 * must be: 309 * @code std::size_t completion_condition( 310 * // Result of latest async_read_some operation. 311 * const asio::error_code& error, 312 * 313 * // Number of bytes transferred so far. 314 * std::size_t bytes_transferred 315 * ); @endcode 316 * A return value of 0 indicates that the read operation is complete. A non-zero 317 * return value indicates the maximum number of bytes to be read on the next 318 * call to the stream's async_read_some function. 319 * 320 * @param handler The handler to be called when the read operation completes. 321 * Copies will be made of the handler as required. The function signature of the 322 * handler must be: 323 * @code void handler( 324 * const asio::error_code& error, // Result of operation. 325 * 326 * std::size_t bytes_transferred // Number of bytes copied into the 327 * // buffers. If an error occurred, 328 * // this will be the number of 329 * // bytes successfully transferred 330 * // prior to the error. 331 * ); @endcode 332 * Regardless of whether the asynchronous operation completes immediately or 333 * not, the handler will not be invoked from within this function. Invocation of 334 * the handler will be performed in a manner equivalent to using 335 * asio::io_service::post(). 336 * 337 * @par Example 338 * To read into a single data buffer use the @ref buffer function as follows: 339 * @code asio::async_read(s, 340 * asio::buffer(data, size), 341 * asio::transfer_at_least(32), 342 * handler); @endcode 343 * See the @ref buffer documentation for information on reading into multiple 344 * buffers in one go, and how to use it with arrays, boost::array or 345 * std::vector. 346 */ 347 template <typename AsyncReadStream, typename MutableBufferSequence, 348 typename CompletionCondition, typename ReadHandler> 349 ASIO_INITFN_RESULT_TYPE(ReadHandler, 350 void (asio::error_code, std::size_t)) 351 async_read(AsyncReadStream& s, const MutableBufferSequence& buffers, 352 CompletionCondition completion_condition, 353 ASIO_MOVE_ARG(ReadHandler) handler); 354 355 356 /*@}*/ 357 358 } // namespace asio 359 360 #include "asio/detail/pop_options.hpp" 361 362 #include "asio/impl/read.hpp" 363 364 #endif // ASIO_READ_HPP 365
