9
3

read.hpp 53 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290
  1. //
  2. // read.hpp
  3. // ~~~~~~~~
  4. //
  5. // Copyright (c) 2003-2019 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/async_result.hpp>
  18. #include <boost/asio/buffer.hpp>
  19. #include <boost/asio/error.hpp>
  20. #if !defined(BOOST_ASIO_NO_EXTENSIONS)
  21. # include <boost/asio/basic_streambuf_fwd.hpp>
  22. #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
  23. #include <boost/asio/detail/push_options.hpp>
  24. namespace boost {
  25. namespace asio {
  26. /**
  27. * @defgroup read boost::asio::read
  28. *
  29. * @brief The @c read function is a composed operation that reads a certain
  30. * amount of data from a stream before returning.
  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 boost::system::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 boost::asio::read(s, boost::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 boost::asio::read(
  66. * s, buffers,
  67. * boost::asio::transfer_all()); @endcode
  68. */
  69. template <typename SyncReadStream, typename MutableBufferSequence>
  70. std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
  71. typename enable_if<
  72. is_mutable_buffer_sequence<MutableBufferSequence>::value
  73. >::type* = 0);
  74. /// Attempt to read a certain amount of data from a stream before returning.
  75. /**
  76. * This function is used to read a certain number of bytes of data from a
  77. * stream. The call will block until one of the following conditions is true:
  78. *
  79. * @li The supplied buffers are full. That is, the bytes transferred is equal to
  80. * the sum of the buffer sizes.
  81. *
  82. * @li An error occurred.
  83. *
  84. * This operation is implemented in terms of zero or more calls to the stream's
  85. * read_some function.
  86. *
  87. * @param s The stream from which the data is to be read. The type must support
  88. * the SyncReadStream concept.
  89. *
  90. * @param buffers One or more buffers into which the data will be read. The sum
  91. * of the buffer sizes indicates the maximum number of bytes to read from the
  92. * stream.
  93. *
  94. * @param ec Set to indicate what error occurred, if any.
  95. *
  96. * @returns The number of bytes transferred.
  97. *
  98. * @par Example
  99. * To read into a single data buffer use the @ref buffer function as follows:
  100. * @code boost::asio::read(s, boost::asio::buffer(data, size), ec); @endcode
  101. * See the @ref buffer documentation for information on reading into multiple
  102. * buffers in one go, and how to use it with arrays, boost::array or
  103. * std::vector.
  104. *
  105. * @note This overload is equivalent to calling:
  106. * @code boost::asio::read(
  107. * s, buffers,
  108. * boost::asio::transfer_all(), ec); @endcode
  109. */
  110. template <typename SyncReadStream, typename MutableBufferSequence>
  111. std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
  112. boost::system::error_code& ec,
  113. typename enable_if<
  114. is_mutable_buffer_sequence<MutableBufferSequence>::value
  115. >::type* = 0);
  116. /// Attempt to read a certain amount of data from a stream before returning.
  117. /**
  118. * This function is used to read a certain number of bytes of data from a
  119. * stream. The call will block until one of the following conditions is true:
  120. *
  121. * @li The supplied buffers are full. That is, the bytes transferred is equal to
  122. * the sum of the buffer sizes.
  123. *
  124. * @li The completion_condition function object returns 0.
  125. *
  126. * This operation is implemented in terms of zero or more calls to the stream's
  127. * read_some function.
  128. *
  129. * @param s The stream from which the data is to be read. The type must support
  130. * the SyncReadStream concept.
  131. *
  132. * @param buffers One or more buffers into which the data will be read. The sum
  133. * of the buffer sizes indicates the maximum number of bytes to read from the
  134. * stream.
  135. *
  136. * @param completion_condition The function object to be called to determine
  137. * whether the read operation is complete. The signature of the function object
  138. * must be:
  139. * @code std::size_t completion_condition(
  140. * // Result of latest read_some operation.
  141. * const boost::system::error_code& error,
  142. *
  143. * // Number of bytes transferred so far.
  144. * std::size_t bytes_transferred
  145. * ); @endcode
  146. * A return value of 0 indicates that the read operation is complete. A non-zero
  147. * return value indicates the maximum number of bytes to be read on the next
  148. * call to the stream's read_some function.
  149. *
  150. * @returns The number of bytes transferred.
  151. *
  152. * @throws boost::system::system_error Thrown on failure.
  153. *
  154. * @par Example
  155. * To read into a single data buffer use the @ref buffer function as follows:
  156. * @code boost::asio::read(s, boost::asio::buffer(data, size),
  157. * boost::asio::transfer_at_least(32)); @endcode
  158. * See the @ref buffer documentation for information on reading into multiple
  159. * buffers in one go, and how to use it with arrays, boost::array or
  160. * std::vector.
  161. */
  162. template <typename SyncReadStream, typename MutableBufferSequence,
  163. typename CompletionCondition>
  164. std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
  165. CompletionCondition completion_condition,
  166. typename enable_if<
  167. is_mutable_buffer_sequence<MutableBufferSequence>::value
  168. >::type* = 0);
  169. /// Attempt to read a certain amount of data from a stream before returning.
  170. /**
  171. * This function is used to read a certain number of bytes of data from a
  172. * stream. The call will block until one of the following conditions is true:
  173. *
  174. * @li The supplied buffers are full. That is, the bytes transferred is equal to
  175. * the sum of the buffer sizes.
  176. *
  177. * @li The completion_condition function object returns 0.
  178. *
  179. * This operation is implemented in terms of zero or more calls to the stream's
  180. * read_some function.
  181. *
  182. * @param s The stream from which the data is to be read. The type must support
  183. * the SyncReadStream concept.
  184. *
  185. * @param buffers One or more buffers into which the data will be read. The sum
  186. * of the buffer sizes indicates the maximum number of bytes to read from the
  187. * stream.
  188. *
  189. * @param completion_condition The function object to be called to determine
  190. * whether the read operation is complete. The signature of the function object
  191. * must be:
  192. * @code std::size_t completion_condition(
  193. * // Result of latest read_some operation.
  194. * const boost::system::error_code& error,
  195. *
  196. * // Number of bytes transferred so far.
  197. * std::size_t bytes_transferred
  198. * ); @endcode
  199. * A return value of 0 indicates that the read operation is complete. A non-zero
  200. * return value indicates the maximum number of bytes to be read on the next
  201. * call to the stream's read_some function.
  202. *
  203. * @param ec Set to indicate what error occurred, if any.
  204. *
  205. * @returns The number of bytes read. If an error occurs, returns the total
  206. * number of bytes successfully transferred prior to the error.
  207. */
  208. template <typename SyncReadStream, typename MutableBufferSequence,
  209. typename CompletionCondition>
  210. std::size_t read(SyncReadStream& s, const MutableBufferSequence& buffers,
  211. CompletionCondition completion_condition, boost::system::error_code& ec,
  212. typename enable_if<
  213. is_mutable_buffer_sequence<MutableBufferSequence>::value
  214. >::type* = 0);
  215. #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
  216. /// Attempt to read a certain amount of data from a stream before returning.
  217. /**
  218. * This function is used to read a certain number of bytes of data from a
  219. * stream. The call will block until one of the following conditions is true:
  220. *
  221. * @li The specified dynamic buffer sequence is full (that is, it has reached
  222. * maximum size).
  223. *
  224. * @li An error occurred.
  225. *
  226. * This operation is implemented in terms of zero or more calls to the stream's
  227. * read_some function.
  228. *
  229. * @param s The stream from which the data is to be read. The type must support
  230. * the SyncReadStream concept.
  231. *
  232. * @param buffers The dynamic buffer sequence into which the data will be read.
  233. *
  234. * @returns The number of bytes transferred.
  235. *
  236. * @throws boost::system::system_error Thrown on failure.
  237. *
  238. * @note This overload is equivalent to calling:
  239. * @code boost::asio::read(
  240. * s, buffers,
  241. * boost::asio::transfer_all()); @endcode
  242. */
  243. template <typename SyncReadStream, typename DynamicBuffer_v1>
  244. std::size_t read(SyncReadStream& s,
  245. BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
  246. typename enable_if<
  247. is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
  248. && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
  249. >::type* = 0);
  250. /// Attempt to read a certain amount of data from a stream before returning.
  251. /**
  252. * This function is used to read a certain number of bytes of data from a
  253. * stream. The call will block until one of the following conditions is true:
  254. *
  255. * @li The supplied buffer is full (that is, it has reached maximum size).
  256. *
  257. * @li An error occurred.
  258. *
  259. * This operation is implemented in terms of zero or more calls to the stream's
  260. * read_some function.
  261. *
  262. * @param s The stream from which the data is to be read. The type must support
  263. * the SyncReadStream concept.
  264. *
  265. * @param buffers The dynamic buffer sequence into which the data will be read.
  266. *
  267. * @param ec Set to indicate what error occurred, if any.
  268. *
  269. * @returns The number of bytes transferred.
  270. *
  271. * @note This overload is equivalent to calling:
  272. * @code boost::asio::read(
  273. * s, buffers,
  274. * boost::asio::transfer_all(), ec); @endcode
  275. */
  276. template <typename SyncReadStream, typename DynamicBuffer_v1>
  277. std::size_t read(SyncReadStream& s,
  278. BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
  279. boost::system::error_code& ec,
  280. typename enable_if<
  281. is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
  282. && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
  283. >::type* = 0);
  284. /// Attempt to read a certain amount of data from a stream before returning.
  285. /**
  286. * This function is used to read a certain number of bytes of data from a
  287. * stream. The call will block until one of the following conditions is true:
  288. *
  289. * @li The specified dynamic buffer sequence is full (that is, it has reached
  290. * maximum size).
  291. *
  292. * @li The completion_condition function object returns 0.
  293. *
  294. * This operation is implemented in terms of zero or more calls to the stream's
  295. * read_some function.
  296. *
  297. * @param s The stream from which the data is to be read. The type must support
  298. * the SyncReadStream concept.
  299. *
  300. * @param buffers The dynamic buffer sequence into which the data will be read.
  301. *
  302. * @param completion_condition The function object to be called to determine
  303. * whether the read operation is complete. The signature of the function object
  304. * must be:
  305. * @code std::size_t completion_condition(
  306. * // Result of latest read_some operation.
  307. * const boost::system::error_code& error,
  308. *
  309. * // Number of bytes transferred so far.
  310. * std::size_t bytes_transferred
  311. * ); @endcode
  312. * A return value of 0 indicates that the read operation is complete. A non-zero
  313. * return value indicates the maximum number of bytes to be read on the next
  314. * call to the stream's read_some function.
  315. *
  316. * @returns The number of bytes transferred.
  317. *
  318. * @throws boost::system::system_error Thrown on failure.
  319. */
  320. template <typename SyncReadStream, typename DynamicBuffer_v1,
  321. typename CompletionCondition>
  322. std::size_t read(SyncReadStream& s,
  323. BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
  324. CompletionCondition completion_condition,
  325. typename enable_if<
  326. is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
  327. && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
  328. >::type* = 0);
  329. /// Attempt to read a certain amount of data from a stream before returning.
  330. /**
  331. * This function is used to read a certain number of bytes of data from a
  332. * stream. The call will block until one of the following conditions is true:
  333. *
  334. * @li The specified dynamic buffer sequence is full (that is, it has reached
  335. * maximum size).
  336. *
  337. * @li The completion_condition function object returns 0.
  338. *
  339. * This operation is implemented in terms of zero or more calls to the stream's
  340. * read_some function.
  341. *
  342. * @param s The stream from which the data is to be read. The type must support
  343. * the SyncReadStream concept.
  344. *
  345. * @param buffers The dynamic buffer sequence into which the data will be read.
  346. *
  347. * @param completion_condition The function object to be called to determine
  348. * whether the read operation is complete. The signature of the function object
  349. * must be:
  350. * @code std::size_t completion_condition(
  351. * // Result of latest read_some operation.
  352. * const boost::system::error_code& error,
  353. *
  354. * // Number of bytes transferred so far.
  355. * std::size_t bytes_transferred
  356. * ); @endcode
  357. * A return value of 0 indicates that the read operation is complete. A non-zero
  358. * return value indicates the maximum number of bytes to be read on the next
  359. * call to the stream's read_some function.
  360. *
  361. * @param ec Set to indicate what error occurred, if any.
  362. *
  363. * @returns The number of bytes read. If an error occurs, returns the total
  364. * number of bytes successfully transferred prior to the error.
  365. */
  366. template <typename SyncReadStream, typename DynamicBuffer_v1,
  367. typename CompletionCondition>
  368. std::size_t read(SyncReadStream& s,
  369. BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
  370. CompletionCondition completion_condition, boost::system::error_code& ec,
  371. typename enable_if<
  372. is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
  373. && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
  374. >::type* = 0);
  375. #if !defined(BOOST_ASIO_NO_EXTENSIONS)
  376. #if !defined(BOOST_ASIO_NO_IOSTREAM)
  377. /// Attempt to read a certain amount of data from a stream before returning.
  378. /**
  379. * This function is used to read a certain number of bytes of data from a
  380. * stream. The call will block until one of the following conditions is true:
  381. *
  382. * @li The supplied buffer is full (that is, it has reached maximum size).
  383. *
  384. * @li An error occurred.
  385. *
  386. * This operation is implemented in terms of zero or more calls to the stream's
  387. * read_some function.
  388. *
  389. * @param s The stream from which the data is to be read. The type must support
  390. * the SyncReadStream concept.
  391. *
  392. * @param b The basic_streambuf object into which the data will be read.
  393. *
  394. * @returns The number of bytes transferred.
  395. *
  396. * @throws boost::system::system_error Thrown on failure.
  397. *
  398. * @note This overload is equivalent to calling:
  399. * @code boost::asio::read(
  400. * s, b,
  401. * boost::asio::transfer_all()); @endcode
  402. */
  403. template <typename SyncReadStream, typename Allocator>
  404. std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b);
  405. /// Attempt to read a certain amount of data from a stream before returning.
  406. /**
  407. * This function is used to read a certain number of bytes of data from a
  408. * stream. The call will block until one of the following conditions is true:
  409. *
  410. * @li The supplied buffer is full (that is, it has reached maximum size).
  411. *
  412. * @li An error occurred.
  413. *
  414. * This operation is implemented in terms of zero or more calls to the stream's
  415. * read_some function.
  416. *
  417. * @param s The stream from which the data is to be read. The type must support
  418. * the SyncReadStream concept.
  419. *
  420. * @param b The basic_streambuf object into which the data will be read.
  421. *
  422. * @param ec Set to indicate what error occurred, if any.
  423. *
  424. * @returns The number of bytes transferred.
  425. *
  426. * @note This overload is equivalent to calling:
  427. * @code boost::asio::read(
  428. * s, b,
  429. * boost::asio::transfer_all(), ec); @endcode
  430. */
  431. template <typename SyncReadStream, typename Allocator>
  432. std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
  433. boost::system::error_code& ec);
  434. /// Attempt to read a certain amount of data from a stream before returning.
  435. /**
  436. * This function is used to read a certain number of bytes of data from a
  437. * stream. The call will block until one of the following conditions is true:
  438. *
  439. * @li The supplied buffer is full (that is, it has reached maximum size).
  440. *
  441. * @li The completion_condition function object returns 0.
  442. *
  443. * This operation is implemented in terms of zero or more calls to the stream's
  444. * read_some function.
  445. *
  446. * @param s The stream from which the data is to be read. The type must support
  447. * the SyncReadStream concept.
  448. *
  449. * @param b The basic_streambuf object into which the data will be read.
  450. *
  451. * @param completion_condition The function object to be called to determine
  452. * whether the read operation is complete. The signature of the function object
  453. * must be:
  454. * @code std::size_t completion_condition(
  455. * // Result of latest read_some operation.
  456. * const boost::system::error_code& error,
  457. *
  458. * // Number of bytes transferred so far.
  459. * std::size_t bytes_transferred
  460. * ); @endcode
  461. * A return value of 0 indicates that the read operation is complete. A non-zero
  462. * return value indicates the maximum number of bytes to be read on the next
  463. * call to the stream's read_some function.
  464. *
  465. * @returns The number of bytes transferred.
  466. *
  467. * @throws boost::system::system_error Thrown on failure.
  468. */
  469. template <typename SyncReadStream, typename Allocator,
  470. typename CompletionCondition>
  471. std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
  472. CompletionCondition completion_condition);
  473. /// Attempt to read a certain amount of data from a stream before returning.
  474. /**
  475. * This function is used to read a certain number of bytes of data from a
  476. * stream. The call will block until one of the following conditions is true:
  477. *
  478. * @li The supplied buffer is full (that is, it has reached maximum size).
  479. *
  480. * @li The completion_condition function object returns 0.
  481. *
  482. * This operation is implemented in terms of zero or more calls to the stream's
  483. * read_some function.
  484. *
  485. * @param s The stream from which the data is to be read. The type must support
  486. * the SyncReadStream concept.
  487. *
  488. * @param b The basic_streambuf object into which the data will be read.
  489. *
  490. * @param completion_condition The function object to be called to determine
  491. * whether the read operation is complete. The signature of the function object
  492. * must be:
  493. * @code std::size_t completion_condition(
  494. * // Result of latest read_some operation.
  495. * const boost::system::error_code& error,
  496. *
  497. * // Number of bytes transferred so far.
  498. * std::size_t bytes_transferred
  499. * ); @endcode
  500. * A return value of 0 indicates that the read operation is complete. A non-zero
  501. * return value indicates the maximum number of bytes to be read on the next
  502. * call to the stream's read_some function.
  503. *
  504. * @param ec Set to indicate what error occurred, if any.
  505. *
  506. * @returns The number of bytes read. If an error occurs, returns the total
  507. * number of bytes successfully transferred prior to the error.
  508. */
  509. template <typename SyncReadStream, typename Allocator,
  510. typename CompletionCondition>
  511. std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
  512. CompletionCondition completion_condition, boost::system::error_code& ec);
  513. #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
  514. #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
  515. #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
  516. /// Attempt to read a certain amount of data from a stream before returning.
  517. /**
  518. * This function is used to read a certain number of bytes of data from a
  519. * stream. The call will block until one of the following conditions is true:
  520. *
  521. * @li The specified dynamic buffer sequence is full (that is, it has reached
  522. * maximum size).
  523. *
  524. * @li An error occurred.
  525. *
  526. * This operation is implemented in terms of zero or more calls to the stream's
  527. * read_some function.
  528. *
  529. * @param s The stream from which the data is to be read. The type must support
  530. * the SyncReadStream concept.
  531. *
  532. * @param buffers The dynamic buffer sequence into which the data will be read.
  533. *
  534. * @returns The number of bytes transferred.
  535. *
  536. * @throws boost::system::system_error Thrown on failure.
  537. *
  538. * @note This overload is equivalent to calling:
  539. * @code boost::asio::read(
  540. * s, buffers,
  541. * boost::asio::transfer_all()); @endcode
  542. */
  543. template <typename SyncReadStream, typename DynamicBuffer_v2>
  544. std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
  545. typename enable_if<
  546. is_dynamic_buffer_v2<DynamicBuffer_v2>::value
  547. >::type* = 0);
  548. /// Attempt to read a certain amount of data from a stream before returning.
  549. /**
  550. * This function is used to read a certain number of bytes of data from a
  551. * stream. The call will block until one of the following conditions is true:
  552. *
  553. * @li The supplied buffer is full (that is, it has reached maximum size).
  554. *
  555. * @li An error occurred.
  556. *
  557. * This operation is implemented in terms of zero or more calls to the stream's
  558. * read_some function.
  559. *
  560. * @param s The stream from which the data is to be read. The type must support
  561. * the SyncReadStream concept.
  562. *
  563. * @param buffers The dynamic buffer sequence into which the data will be read.
  564. *
  565. * @param ec Set to indicate what error occurred, if any.
  566. *
  567. * @returns The number of bytes transferred.
  568. *
  569. * @note This overload is equivalent to calling:
  570. * @code boost::asio::read(
  571. * s, buffers,
  572. * boost::asio::transfer_all(), ec); @endcode
  573. */
  574. template <typename SyncReadStream, typename DynamicBuffer_v2>
  575. std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
  576. boost::system::error_code& ec,
  577. typename enable_if<
  578. is_dynamic_buffer_v2<DynamicBuffer_v2>::value
  579. >::type* = 0);
  580. /// Attempt to read a certain amount of data from a stream before returning.
  581. /**
  582. * This function is used to read a certain number of bytes of data from a
  583. * stream. The call will block until one of the following conditions is true:
  584. *
  585. * @li The specified dynamic buffer sequence is full (that is, it has reached
  586. * maximum size).
  587. *
  588. * @li The completion_condition function object returns 0.
  589. *
  590. * This operation is implemented in terms of zero or more calls to the stream's
  591. * read_some function.
  592. *
  593. * @param s The stream from which the data is to be read. The type must support
  594. * the SyncReadStream concept.
  595. *
  596. * @param buffers The dynamic buffer sequence into which the data will be read.
  597. *
  598. * @param completion_condition The function object to be called to determine
  599. * whether the read operation is complete. The signature of the function object
  600. * must be:
  601. * @code std::size_t completion_condition(
  602. * // Result of latest read_some operation.
  603. * const boost::system::error_code& error,
  604. *
  605. * // Number of bytes transferred so far.
  606. * std::size_t bytes_transferred
  607. * ); @endcode
  608. * A return value of 0 indicates that the read operation is complete. A non-zero
  609. * return value indicates the maximum number of bytes to be read on the next
  610. * call to the stream's read_some function.
  611. *
  612. * @returns The number of bytes transferred.
  613. *
  614. * @throws boost::system::system_error Thrown on failure.
  615. */
  616. template <typename SyncReadStream, typename DynamicBuffer_v2,
  617. typename CompletionCondition>
  618. std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
  619. CompletionCondition completion_condition,
  620. typename enable_if<
  621. is_dynamic_buffer_v2<DynamicBuffer_v2>::value
  622. >::type* = 0);
  623. /// Attempt to read a certain amount of data from a stream before returning.
  624. /**
  625. * This function is used to read a certain number of bytes of data from a
  626. * stream. The call will block until one of the following conditions is true:
  627. *
  628. * @li The specified dynamic buffer sequence is full (that is, it has reached
  629. * maximum size).
  630. *
  631. * @li The completion_condition function object returns 0.
  632. *
  633. * This operation is implemented in terms of zero or more calls to the stream's
  634. * read_some function.
  635. *
  636. * @param s The stream from which the data is to be read. The type must support
  637. * the SyncReadStream concept.
  638. *
  639. * @param buffers The dynamic buffer sequence into which the data will be read.
  640. *
  641. * @param completion_condition The function object to be called to determine
  642. * whether the read operation is complete. The signature of the function object
  643. * must be:
  644. * @code std::size_t completion_condition(
  645. * // Result of latest read_some operation.
  646. * const boost::system::error_code& error,
  647. *
  648. * // Number of bytes transferred so far.
  649. * std::size_t bytes_transferred
  650. * ); @endcode
  651. * A return value of 0 indicates that the read operation is complete. A non-zero
  652. * return value indicates the maximum number of bytes to be read on the next
  653. * call to the stream's read_some function.
  654. *
  655. * @param ec Set to indicate what error occurred, if any.
  656. *
  657. * @returns The number of bytes read. If an error occurs, returns the total
  658. * number of bytes successfully transferred prior to the error.
  659. */
  660. template <typename SyncReadStream, typename DynamicBuffer_v2,
  661. typename CompletionCondition>
  662. std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
  663. CompletionCondition completion_condition, boost::system::error_code& ec,
  664. typename enable_if<
  665. is_dynamic_buffer_v2<DynamicBuffer_v2>::value
  666. >::type* = 0);
  667. /*@}*/
  668. /**
  669. * @defgroup async_read boost::asio::async_read
  670. *
  671. * @brief The @c async_read function is a composed asynchronous operation that
  672. * reads a certain amount of data from a stream before completion.
  673. */
  674. /*@{*/
  675. /// Start an asynchronous operation to read a certain amount of data from a
  676. /// stream.
  677. /**
  678. * This function is used to asynchronously read a certain number of bytes of
  679. * data from a stream. The function call always returns immediately. The
  680. * asynchronous operation will continue until one of the following conditions is
  681. * true:
  682. *
  683. * @li The supplied buffers are full. That is, the bytes transferred is equal to
  684. * the sum of the buffer sizes.
  685. *
  686. * @li An error occurred.
  687. *
  688. * This operation is implemented in terms of zero or more calls to the stream's
  689. * async_read_some function, and is known as a <em>composed operation</em>. The
  690. * program must ensure that the stream performs no other read operations (such
  691. * as async_read, the stream's async_read_some function, or any other composed
  692. * operations that perform reads) until this operation completes.
  693. *
  694. * @param s The stream from which the data is to be read. The type must support
  695. * the AsyncReadStream concept.
  696. *
  697. * @param buffers One or more buffers into which the data will be read. The sum
  698. * of the buffer sizes indicates the maximum number of bytes to read from the
  699. * stream. Although the buffers object may be copied as necessary, ownership of
  700. * the underlying memory blocks is retained by the caller, which must guarantee
  701. * that they remain valid until the handler is called.
  702. *
  703. * @param handler The handler to be called when the read operation completes.
  704. * Copies will be made of the handler as required. The function signature of the
  705. * handler must be:
  706. * @code void handler(
  707. * const boost::system::error_code& error, // Result of operation.
  708. *
  709. * std::size_t bytes_transferred // Number of bytes copied into the
  710. * // buffers. If an error occurred,
  711. * // this will be the number of
  712. * // bytes successfully transferred
  713. * // prior to the error.
  714. * ); @endcode
  715. * Regardless of whether the asynchronous operation completes immediately or
  716. * not, the handler will not be invoked from within this function. On
  717. * immediate completion, invocation of the handler will be performed in a
  718. * manner equivalent to using boost::asio::post().
  719. *
  720. * @par Example
  721. * To read into a single data buffer use the @ref buffer function as follows:
  722. * @code
  723. * boost::asio::async_read(s, boost::asio::buffer(data, size), handler);
  724. * @endcode
  725. * See the @ref buffer documentation for information on reading into multiple
  726. * buffers in one go, and how to use it with arrays, boost::array or
  727. * std::vector.
  728. *
  729. * @note This overload is equivalent to calling:
  730. * @code boost::asio::async_read(
  731. * s, buffers,
  732. * boost::asio::transfer_all(),
  733. * handler); @endcode
  734. */
  735. template <typename AsyncReadStream, typename MutableBufferSequence,
  736. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  737. std::size_t)) ReadHandler
  738. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  739. typename AsyncReadStream::executor_type)>
  740. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
  741. void (boost::system::error_code, std::size_t))
  742. async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
  743. BOOST_ASIO_MOVE_ARG(ReadHandler) handler
  744. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  745. typename AsyncReadStream::executor_type),
  746. typename enable_if<
  747. is_mutable_buffer_sequence<MutableBufferSequence>::value
  748. >::type* = 0);
  749. /// Start an asynchronous operation to read a certain amount of data from a
  750. /// stream.
  751. /**
  752. * This function is used to asynchronously read a certain number of bytes of
  753. * data from a stream. The function call always returns immediately. The
  754. * asynchronous operation will continue until one of the following conditions is
  755. * true:
  756. *
  757. * @li The supplied buffers are full. That is, the bytes transferred is equal to
  758. * the sum of the buffer sizes.
  759. *
  760. * @li The completion_condition function object returns 0.
  761. *
  762. * @param s The stream from which the data is to be read. The type must support
  763. * the AsyncReadStream concept.
  764. *
  765. * @param buffers One or more buffers into which the data will be read. The sum
  766. * of the buffer sizes indicates the maximum number of bytes to read from the
  767. * stream. Although the buffers object may be copied as necessary, ownership of
  768. * the underlying memory blocks is retained by the caller, which must guarantee
  769. * that they remain valid until the handler is called.
  770. *
  771. * @param completion_condition The function object to be called to determine
  772. * whether the read operation is complete. The signature of the function object
  773. * must be:
  774. * @code std::size_t completion_condition(
  775. * // Result of latest async_read_some operation.
  776. * const boost::system::error_code& error,
  777. *
  778. * // Number of bytes transferred so far.
  779. * std::size_t bytes_transferred
  780. * ); @endcode
  781. * A return value of 0 indicates that the read operation is complete. A non-zero
  782. * return value indicates the maximum number of bytes to be read on the next
  783. * call to the stream's async_read_some function.
  784. *
  785. * @param handler The handler to be called when the read operation completes.
  786. * Copies will be made of the handler as required. The function signature of the
  787. * handler must be:
  788. * @code void handler(
  789. * const boost::system::error_code& error, // Result of operation.
  790. *
  791. * std::size_t bytes_transferred // Number of bytes copied into the
  792. * // buffers. If an error occurred,
  793. * // this will be the number of
  794. * // bytes successfully transferred
  795. * // prior to the error.
  796. * ); @endcode
  797. * Regardless of whether the asynchronous operation completes immediately or
  798. * not, the handler will not be invoked from within this function. On
  799. * immediate completion, invocation of the handler will be performed in a
  800. * manner equivalent to using boost::asio::post().
  801. *
  802. * @par Example
  803. * To read into a single data buffer use the @ref buffer function as follows:
  804. * @code boost::asio::async_read(s,
  805. * boost::asio::buffer(data, size),
  806. * boost::asio::transfer_at_least(32),
  807. * handler); @endcode
  808. * See the @ref buffer documentation for information on reading into multiple
  809. * buffers in one go, and how to use it with arrays, boost::array or
  810. * std::vector.
  811. */
  812. template <typename AsyncReadStream,
  813. typename MutableBufferSequence, typename CompletionCondition,
  814. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  815. std::size_t)) ReadHandler
  816. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  817. typename AsyncReadStream::executor_type)>
  818. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
  819. void (boost::system::error_code, std::size_t))
  820. async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
  821. CompletionCondition completion_condition,
  822. BOOST_ASIO_MOVE_ARG(ReadHandler) handler
  823. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  824. typename AsyncReadStream::executor_type),
  825. typename enable_if<
  826. is_mutable_buffer_sequence<MutableBufferSequence>::value
  827. >::type* = 0);
  828. #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
  829. /// Start an asynchronous operation to read a certain amount of data from a
  830. /// stream.
  831. /**
  832. * This function is used to asynchronously read a certain number of bytes of
  833. * data from a stream. The function call always returns immediately. The
  834. * asynchronous operation will continue until one of the following conditions is
  835. * true:
  836. *
  837. * @li The specified dynamic buffer sequence is full (that is, it has reached
  838. * maximum size).
  839. *
  840. * @li An error occurred.
  841. *
  842. * This operation is implemented in terms of zero or more calls to the stream's
  843. * async_read_some function, and is known as a <em>composed operation</em>. The
  844. * program must ensure that the stream performs no other read operations (such
  845. * as async_read, the stream's async_read_some function, or any other composed
  846. * operations that perform reads) until this operation completes.
  847. *
  848. * @param s The stream from which the data is to be read. The type must support
  849. * the AsyncReadStream concept.
  850. *
  851. * @param buffers The dynamic buffer sequence into which the data will be read.
  852. * Although the buffers object may be copied as necessary, ownership of the
  853. * underlying memory blocks is retained by the caller, which must guarantee
  854. * that they remain valid until the handler is called.
  855. *
  856. * @param handler The handler to be called when the read operation completes.
  857. * Copies will be made of the handler as required. The function signature of the
  858. * handler must be:
  859. * @code void handler(
  860. * const boost::system::error_code& error, // Result of operation.
  861. *
  862. * std::size_t bytes_transferred // Number of bytes copied into the
  863. * // buffers. If an error occurred,
  864. * // this will be the number of
  865. * // bytes successfully transferred
  866. * // prior to the error.
  867. * ); @endcode
  868. * Regardless of whether the asynchronous operation completes immediately or
  869. * not, the handler will not be invoked from within this function. On
  870. * immediate completion, invocation of the handler will be performed in a
  871. * manner equivalent to using boost::asio::post().
  872. *
  873. * @note This overload is equivalent to calling:
  874. * @code boost::asio::async_read(
  875. * s, buffers,
  876. * boost::asio::transfer_all(),
  877. * handler); @endcode
  878. */
  879. template <typename AsyncReadStream, typename DynamicBuffer_v1,
  880. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  881. std::size_t)) ReadHandler
  882. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  883. typename AsyncReadStream::executor_type)>
  884. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
  885. void (boost::system::error_code, std::size_t))
  886. async_read(AsyncReadStream& s,
  887. BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
  888. BOOST_ASIO_MOVE_ARG(ReadHandler) handler
  889. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  890. typename AsyncReadStream::executor_type),
  891. typename enable_if<
  892. is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
  893. && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
  894. >::type* = 0);
  895. /// Start an asynchronous operation to read a certain amount of data from a
  896. /// stream.
  897. /**
  898. * This function is used to asynchronously read a certain number of bytes of
  899. * data from a stream. The function call always returns immediately. The
  900. * asynchronous operation will continue until one of the following conditions is
  901. * true:
  902. *
  903. * @li The specified dynamic buffer sequence is full (that is, it has reached
  904. * maximum size).
  905. *
  906. * @li The completion_condition function object returns 0.
  907. *
  908. * This operation is implemented in terms of zero or more calls to the stream's
  909. * async_read_some function, and is known as a <em>composed operation</em>. The
  910. * program must ensure that the stream performs no other read operations (such
  911. * as async_read, the stream's async_read_some function, or any other composed
  912. * operations that perform reads) until this operation completes.
  913. *
  914. * @param s The stream from which the data is to be read. The type must support
  915. * the AsyncReadStream concept.
  916. *
  917. * @param buffers The dynamic buffer sequence into which the data will be read.
  918. * Although the buffers object may be copied as necessary, ownership of the
  919. * underlying memory blocks is retained by the caller, which must guarantee
  920. * that they remain valid until the handler is called.
  921. *
  922. * @param completion_condition The function object to be called to determine
  923. * whether the read operation is complete. The signature of the function object
  924. * must be:
  925. * @code std::size_t completion_condition(
  926. * // Result of latest async_read_some operation.
  927. * const boost::system::error_code& error,
  928. *
  929. * // Number of bytes transferred so far.
  930. * std::size_t bytes_transferred
  931. * ); @endcode
  932. * A return value of 0 indicates that the read operation is complete. A non-zero
  933. * return value indicates the maximum number of bytes to be read on the next
  934. * call to the stream's async_read_some function.
  935. *
  936. * @param handler The handler to be called when the read operation completes.
  937. * Copies will be made of the handler as required. The function signature of the
  938. * handler must be:
  939. * @code void handler(
  940. * const boost::system::error_code& error, // Result of operation.
  941. *
  942. * std::size_t bytes_transferred // Number of bytes copied into the
  943. * // buffers. If an error occurred,
  944. * // this will be the number of
  945. * // bytes successfully transferred
  946. * // prior to the error.
  947. * ); @endcode
  948. * Regardless of whether the asynchronous operation completes immediately or
  949. * not, the handler will not be invoked from within this function. On
  950. * immediate completion, invocation of the handler will be performed in a
  951. * manner equivalent to using boost::asio::post().
  952. */
  953. template <typename AsyncReadStream,
  954. typename DynamicBuffer_v1, typename CompletionCondition,
  955. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  956. std::size_t)) ReadHandler
  957. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  958. typename AsyncReadStream::executor_type)>
  959. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
  960. void (boost::system::error_code, std::size_t))
  961. async_read(AsyncReadStream& s,
  962. BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
  963. CompletionCondition completion_condition,
  964. BOOST_ASIO_MOVE_ARG(ReadHandler) handler
  965. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  966. typename AsyncReadStream::executor_type),
  967. typename enable_if<
  968. is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
  969. && !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
  970. >::type* = 0);
  971. #if !defined(BOOST_ASIO_NO_EXTENSIONS)
  972. #if !defined(BOOST_ASIO_NO_IOSTREAM)
  973. /// Start an asynchronous operation to read a certain amount of data from a
  974. /// stream.
  975. /**
  976. * This function is used to asynchronously read a certain number of bytes of
  977. * data from a stream. The function call always returns immediately. The
  978. * asynchronous operation will continue until one of the following conditions is
  979. * true:
  980. *
  981. * @li The supplied buffer is full (that is, it has reached maximum size).
  982. *
  983. * @li An error occurred.
  984. *
  985. * This operation is implemented in terms of zero or more calls to the stream's
  986. * async_read_some function, and is known as a <em>composed operation</em>. The
  987. * program must ensure that the stream performs no other read operations (such
  988. * as async_read, the stream's async_read_some function, or any other composed
  989. * operations that perform reads) until this operation completes.
  990. *
  991. * @param s The stream from which the data is to be read. The type must support
  992. * the AsyncReadStream concept.
  993. *
  994. * @param b A basic_streambuf object into which the data will be read. Ownership
  995. * of the streambuf is retained by the caller, which must guarantee that it
  996. * remains valid until the handler is called.
  997. *
  998. * @param handler The handler to be called when the read operation completes.
  999. * Copies will be made of the handler as required. The function signature of the
  1000. * handler must be:
  1001. * @code void handler(
  1002. * const boost::system::error_code& error, // Result of operation.
  1003. *
  1004. * std::size_t bytes_transferred // Number of bytes copied into the
  1005. * // buffers. If an error occurred,
  1006. * // this will be the number of
  1007. * // bytes successfully transferred
  1008. * // prior to the error.
  1009. * ); @endcode
  1010. * Regardless of whether the asynchronous operation completes immediately or
  1011. * not, the handler will not be invoked from within this function. On
  1012. * immediate completion, invocation of the handler will be performed in a
  1013. * manner equivalent to using boost::asio::post().
  1014. *
  1015. * @note This overload is equivalent to calling:
  1016. * @code boost::asio::async_read(
  1017. * s, b,
  1018. * boost::asio::transfer_all(),
  1019. * handler); @endcode
  1020. */
  1021. template <typename AsyncReadStream, typename Allocator,
  1022. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  1023. std::size_t)) ReadHandler
  1024. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  1025. typename AsyncReadStream::executor_type)>
  1026. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
  1027. void (boost::system::error_code, std::size_t))
  1028. async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
  1029. BOOST_ASIO_MOVE_ARG(ReadHandler) handler
  1030. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  1031. typename AsyncReadStream::executor_type));
  1032. /// Start an asynchronous operation to read a certain amount of data from a
  1033. /// stream.
  1034. /**
  1035. * This function is used to asynchronously read a certain number of bytes of
  1036. * data from a stream. The function call always returns immediately. The
  1037. * asynchronous operation will continue until one of the following conditions is
  1038. * true:
  1039. *
  1040. * @li The supplied buffer is full (that is, it has reached maximum size).
  1041. *
  1042. * @li The completion_condition function object returns 0.
  1043. *
  1044. * This operation is implemented in terms of zero or more calls to the stream's
  1045. * async_read_some function, and is known as a <em>composed operation</em>. The
  1046. * program must ensure that the stream performs no other read operations (such
  1047. * as async_read, the stream's async_read_some function, or any other composed
  1048. * operations that perform reads) until this operation completes.
  1049. *
  1050. * @param s The stream from which the data is to be read. The type must support
  1051. * the AsyncReadStream concept.
  1052. *
  1053. * @param b A basic_streambuf object into which the data will be read. Ownership
  1054. * of the streambuf is retained by the caller, which must guarantee that it
  1055. * remains valid until the handler is called.
  1056. *
  1057. * @param completion_condition The function object to be called to determine
  1058. * whether the read operation is complete. The signature of the function object
  1059. * must be:
  1060. * @code std::size_t completion_condition(
  1061. * // Result of latest async_read_some operation.
  1062. * const boost::system::error_code& error,
  1063. *
  1064. * // Number of bytes transferred so far.
  1065. * std::size_t bytes_transferred
  1066. * ); @endcode
  1067. * A return value of 0 indicates that the read operation is complete. A non-zero
  1068. * return value indicates the maximum number of bytes to be read on the next
  1069. * call to the stream's async_read_some function.
  1070. *
  1071. * @param handler The handler to be called when the read operation completes.
  1072. * Copies will be made of the handler as required. The function signature of the
  1073. * handler must be:
  1074. * @code void handler(
  1075. * const boost::system::error_code& error, // Result of operation.
  1076. *
  1077. * std::size_t bytes_transferred // Number of bytes copied into the
  1078. * // buffers. If an error occurred,
  1079. * // this will be the number of
  1080. * // bytes successfully transferred
  1081. * // prior to the error.
  1082. * ); @endcode
  1083. * Regardless of whether the asynchronous operation completes immediately or
  1084. * not, the handler will not be invoked from within this function. On
  1085. * immediate completion, invocation of the handler will be performed in a
  1086. * manner equivalent to using boost::asio::post().
  1087. */
  1088. template <typename AsyncReadStream,
  1089. typename Allocator, typename CompletionCondition,
  1090. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  1091. std::size_t)) ReadHandler
  1092. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  1093. typename AsyncReadStream::executor_type)>
  1094. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
  1095. void (boost::system::error_code, std::size_t))
  1096. async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
  1097. CompletionCondition completion_condition,
  1098. BOOST_ASIO_MOVE_ARG(ReadHandler) handler
  1099. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  1100. typename AsyncReadStream::executor_type));
  1101. #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
  1102. #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
  1103. #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
  1104. /// Start an asynchronous operation to read a certain amount of data from a
  1105. /// stream.
  1106. /**
  1107. * This function is used to asynchronously read a certain number of bytes of
  1108. * data from a stream. The function call always returns immediately. The
  1109. * asynchronous operation will continue until one of the following conditions is
  1110. * true:
  1111. *
  1112. * @li The specified dynamic buffer sequence is full (that is, it has reached
  1113. * maximum size).
  1114. *
  1115. * @li An error occurred.
  1116. *
  1117. * This operation is implemented in terms of zero or more calls to the stream's
  1118. * async_read_some function, and is known as a <em>composed operation</em>. The
  1119. * program must ensure that the stream performs no other read operations (such
  1120. * as async_read, the stream's async_read_some function, or any other composed
  1121. * operations that perform reads) until this operation completes.
  1122. *
  1123. * @param s The stream from which the data is to be read. The type must support
  1124. * the AsyncReadStream concept.
  1125. *
  1126. * @param buffers The dynamic buffer sequence into which the data will be read.
  1127. * Although the buffers object may be copied as necessary, ownership of the
  1128. * underlying memory blocks is retained by the caller, which must guarantee
  1129. * that they remain valid until the handler is called.
  1130. *
  1131. * @param handler The handler to be called when the read operation completes.
  1132. * Copies will be made of the handler as required. The function signature of the
  1133. * handler must be:
  1134. * @code void handler(
  1135. * const boost::system::error_code& error, // Result of operation.
  1136. *
  1137. * std::size_t bytes_transferred // Number of bytes copied into the
  1138. * // buffers. If an error occurred,
  1139. * // this will be the number of
  1140. * // bytes successfully transferred
  1141. * // prior to the error.
  1142. * ); @endcode
  1143. * Regardless of whether the asynchronous operation completes immediately or
  1144. * not, the handler will not be invoked from within this function. On
  1145. * immediate completion, invocation of the handler will be performed in a
  1146. * manner equivalent to using boost::asio::post().
  1147. *
  1148. * @note This overload is equivalent to calling:
  1149. * @code boost::asio::async_read(
  1150. * s, buffers,
  1151. * boost::asio::transfer_all(),
  1152. * handler); @endcode
  1153. */
  1154. template <typename AsyncReadStream, typename DynamicBuffer_v2,
  1155. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  1156. std::size_t)) ReadHandler
  1157. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  1158. typename AsyncReadStream::executor_type)>
  1159. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
  1160. void (boost::system::error_code, std::size_t))
  1161. async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers,
  1162. BOOST_ASIO_MOVE_ARG(ReadHandler) handler
  1163. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  1164. typename AsyncReadStream::executor_type),
  1165. typename enable_if<
  1166. is_dynamic_buffer_v2<DynamicBuffer_v2>::value
  1167. >::type* = 0);
  1168. /// Start an asynchronous operation to read a certain amount of data from a
  1169. /// stream.
  1170. /**
  1171. * This function is used to asynchronously read a certain number of bytes of
  1172. * data from a stream. The function call always returns immediately. The
  1173. * asynchronous operation will continue until one of the following conditions is
  1174. * true:
  1175. *
  1176. * @li The specified dynamic buffer sequence is full (that is, it has reached
  1177. * maximum size).
  1178. *
  1179. * @li The completion_condition function object returns 0.
  1180. *
  1181. * This operation is implemented in terms of zero or more calls to the stream's
  1182. * async_read_some function, and is known as a <em>composed operation</em>. The
  1183. * program must ensure that the stream performs no other read operations (such
  1184. * as async_read, the stream's async_read_some function, or any other composed
  1185. * operations that perform reads) until this operation completes.
  1186. *
  1187. * @param s The stream from which the data is to be read. The type must support
  1188. * the AsyncReadStream concept.
  1189. *
  1190. * @param buffers The dynamic buffer sequence into which the data will be read.
  1191. * Although the buffers object may be copied as necessary, ownership of the
  1192. * underlying memory blocks is retained by the caller, which must guarantee
  1193. * that they remain valid until the handler is called.
  1194. *
  1195. * @param completion_condition The function object to be called to determine
  1196. * whether the read operation is complete. The signature of the function object
  1197. * must be:
  1198. * @code std::size_t completion_condition(
  1199. * // Result of latest async_read_some operation.
  1200. * const boost::system::error_code& error,
  1201. *
  1202. * // Number of bytes transferred so far.
  1203. * std::size_t bytes_transferred
  1204. * ); @endcode
  1205. * A return value of 0 indicates that the read operation is complete. A non-zero
  1206. * return value indicates the maximum number of bytes to be read on the next
  1207. * call to the stream's async_read_some function.
  1208. *
  1209. * @param handler The handler to be called when the read operation completes.
  1210. * Copies will be made of the handler as required. The function signature of the
  1211. * handler must be:
  1212. * @code void handler(
  1213. * const boost::system::error_code& error, // Result of operation.
  1214. *
  1215. * std::size_t bytes_transferred // Number of bytes copied into the
  1216. * // buffers. If an error occurred,
  1217. * // this will be the number of
  1218. * // bytes successfully transferred
  1219. * // prior to the error.
  1220. * ); @endcode
  1221. * Regardless of whether the asynchronous operation completes immediately or
  1222. * not, the handler will not be invoked from within this function. On
  1223. * immediate completion, invocation of the handler will be performed in a
  1224. * manner equivalent to using boost::asio::post().
  1225. */
  1226. template <typename AsyncReadStream,
  1227. typename DynamicBuffer_v2, typename CompletionCondition,
  1228. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  1229. std::size_t)) ReadHandler
  1230. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  1231. typename AsyncReadStream::executor_type)>
  1232. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
  1233. void (boost::system::error_code, std::size_t))
  1234. async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers,
  1235. CompletionCondition completion_condition,
  1236. BOOST_ASIO_MOVE_ARG(ReadHandler) handler
  1237. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  1238. typename AsyncReadStream::executor_type),
  1239. typename enable_if<
  1240. is_dynamic_buffer_v2<DynamicBuffer_v2>::value
  1241. >::type* = 0);
  1242. /*@}*/
  1243. } // namespace asio
  1244. } // namespace boost
  1245. #include <boost/asio/detail/pop_options.hpp>
  1246. #include <boost/asio/impl/read.hpp>
  1247. #endif // BOOST_ASIO_READ_HPP