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

http://hadesmem.googlecode.com/ · C++ Header · 612 lines · 64 code · 28 blank · 520 comment · 1 complexity · d9613bd8596e482badfb2086fe77dfb5 MD5 · raw file

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