read.hpp 57 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430
  1. //
  2. // read.hpp
  3. // ~~~~~~~~
  4. //
  5. // Copyright (c) 2003-2022 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 constraint<
  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 constraint<
  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 constraint<
  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 constraint<
  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 constraint<
  247. is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
  248. >::type = 0,
  249. typename constraint<
  250. !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
  251. >::type = 0);
  252. /// Attempt to read a certain amount of data from a stream before returning.
  253. /**
  254. * This function is used to read a certain number of bytes of data from a
  255. * stream. The call will block until one of the following conditions is true:
  256. *
  257. * @li The supplied buffer is full (that is, it has reached maximum size).
  258. *
  259. * @li An error occurred.
  260. *
  261. * This operation is implemented in terms of zero or more calls to the stream's
  262. * read_some function.
  263. *
  264. * @param s The stream from which the data is to be read. The type must support
  265. * the SyncReadStream concept.
  266. *
  267. * @param buffers The dynamic buffer sequence into which the data will be read.
  268. *
  269. * @param ec Set to indicate what error occurred, if any.
  270. *
  271. * @returns The number of bytes transferred.
  272. *
  273. * @note This overload is equivalent to calling:
  274. * @code boost::asio::read(
  275. * s, buffers,
  276. * boost::asio::transfer_all(), ec); @endcode
  277. */
  278. template <typename SyncReadStream, typename DynamicBuffer_v1>
  279. std::size_t read(SyncReadStream& s,
  280. BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
  281. boost::system::error_code& ec,
  282. typename constraint<
  283. is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
  284. >::type = 0,
  285. typename constraint<
  286. !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
  287. >::type = 0);
  288. /// Attempt to read a certain amount of data from a stream before returning.
  289. /**
  290. * This function is used to read a certain number of bytes of data from a
  291. * stream. The call will block until one of the following conditions is true:
  292. *
  293. * @li The specified dynamic buffer sequence is full (that is, it has reached
  294. * maximum size).
  295. *
  296. * @li The completion_condition function object returns 0.
  297. *
  298. * This operation is implemented in terms of zero or more calls to the stream's
  299. * read_some function.
  300. *
  301. * @param s The stream from which the data is to be read. The type must support
  302. * the SyncReadStream concept.
  303. *
  304. * @param buffers The dynamic buffer sequence into which the data will be read.
  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 read_some operation.
  311. * const boost::system::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 read_some function.
  319. *
  320. * @returns The number of bytes transferred.
  321. *
  322. * @throws boost::system::system_error Thrown on failure.
  323. */
  324. template <typename SyncReadStream, typename DynamicBuffer_v1,
  325. typename CompletionCondition>
  326. std::size_t read(SyncReadStream& s,
  327. BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
  328. CompletionCondition completion_condition,
  329. typename constraint<
  330. is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
  331. >::type = 0,
  332. typename constraint<
  333. !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
  334. >::type = 0);
  335. /// Attempt to read a certain amount of data from a stream before returning.
  336. /**
  337. * This function is used to read a certain number of bytes of data from a
  338. * stream. The call will block until one of the following conditions is true:
  339. *
  340. * @li The specified dynamic buffer sequence is full (that is, it has reached
  341. * maximum size).
  342. *
  343. * @li The completion_condition function object returns 0.
  344. *
  345. * This operation is implemented in terms of zero or more calls to the stream's
  346. * read_some function.
  347. *
  348. * @param s The stream from which the data is to be read. The type must support
  349. * the SyncReadStream concept.
  350. *
  351. * @param buffers The dynamic buffer sequence into which the data will be read.
  352. *
  353. * @param completion_condition The function object to be called to determine
  354. * whether the read operation is complete. The signature of the function object
  355. * must be:
  356. * @code std::size_t completion_condition(
  357. * // Result of latest read_some operation.
  358. * const boost::system::error_code& error,
  359. *
  360. * // Number of bytes transferred so far.
  361. * std::size_t bytes_transferred
  362. * ); @endcode
  363. * A return value of 0 indicates that the read operation is complete. A non-zero
  364. * return value indicates the maximum number of bytes to be read on the next
  365. * call to the stream's read_some function.
  366. *
  367. * @param ec Set to indicate what error occurred, if any.
  368. *
  369. * @returns The number of bytes read. If an error occurs, returns the total
  370. * number of bytes successfully transferred prior to the error.
  371. */
  372. template <typename SyncReadStream, typename DynamicBuffer_v1,
  373. typename CompletionCondition>
  374. std::size_t read(SyncReadStream& s,
  375. BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
  376. CompletionCondition completion_condition, boost::system::error_code& ec,
  377. typename constraint<
  378. is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
  379. >::type = 0,
  380. typename constraint<
  381. !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
  382. >::type = 0);
  383. #if !defined(BOOST_ASIO_NO_EXTENSIONS)
  384. #if !defined(BOOST_ASIO_NO_IOSTREAM)
  385. /// Attempt to read a certain amount of data from a stream before returning.
  386. /**
  387. * This function is used to read a certain number of bytes of data from a
  388. * stream. The call will block until one of the following conditions is true:
  389. *
  390. * @li The supplied buffer is full (that is, it has reached maximum size).
  391. *
  392. * @li An error occurred.
  393. *
  394. * This operation is implemented in terms of zero or more calls to the stream's
  395. * read_some function.
  396. *
  397. * @param s The stream from which the data is to be read. The type must support
  398. * the SyncReadStream concept.
  399. *
  400. * @param b The basic_streambuf object into which the data will be read.
  401. *
  402. * @returns The number of bytes transferred.
  403. *
  404. * @throws boost::system::system_error Thrown on failure.
  405. *
  406. * @note This overload is equivalent to calling:
  407. * @code boost::asio::read(
  408. * s, b,
  409. * boost::asio::transfer_all()); @endcode
  410. */
  411. template <typename SyncReadStream, typename Allocator>
  412. std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b);
  413. /// Attempt to read a certain amount of data from a stream before returning.
  414. /**
  415. * This function is used to read a certain number of bytes of data from a
  416. * stream. The call will block until one of the following conditions is true:
  417. *
  418. * @li The supplied buffer is full (that is, it has reached maximum size).
  419. *
  420. * @li An error occurred.
  421. *
  422. * This operation is implemented in terms of zero or more calls to the stream's
  423. * read_some function.
  424. *
  425. * @param s The stream from which the data is to be read. The type must support
  426. * the SyncReadStream concept.
  427. *
  428. * @param b The basic_streambuf object into which the data will be read.
  429. *
  430. * @param ec Set to indicate what error occurred, if any.
  431. *
  432. * @returns The number of bytes transferred.
  433. *
  434. * @note This overload is equivalent to calling:
  435. * @code boost::asio::read(
  436. * s, b,
  437. * boost::asio::transfer_all(), ec); @endcode
  438. */
  439. template <typename SyncReadStream, typename Allocator>
  440. std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
  441. boost::system::error_code& ec);
  442. /// Attempt to read a certain amount of data from a stream before returning.
  443. /**
  444. * This function is used to read a certain number of bytes of data from a
  445. * stream. The call will block until one of the following conditions is true:
  446. *
  447. * @li The supplied buffer is full (that is, it has reached maximum size).
  448. *
  449. * @li The completion_condition function object returns 0.
  450. *
  451. * This operation is implemented in terms of zero or more calls to the stream's
  452. * read_some function.
  453. *
  454. * @param s The stream from which the data is to be read. The type must support
  455. * the SyncReadStream concept.
  456. *
  457. * @param b The basic_streambuf object into which the data will be read.
  458. *
  459. * @param completion_condition The function object to be called to determine
  460. * whether the read operation is complete. The signature of the function object
  461. * must be:
  462. * @code std::size_t completion_condition(
  463. * // Result of latest read_some operation.
  464. * const boost::system::error_code& error,
  465. *
  466. * // Number of bytes transferred so far.
  467. * std::size_t bytes_transferred
  468. * ); @endcode
  469. * A return value of 0 indicates that the read operation is complete. A non-zero
  470. * return value indicates the maximum number of bytes to be read on the next
  471. * call to the stream's read_some function.
  472. *
  473. * @returns The number of bytes transferred.
  474. *
  475. * @throws boost::system::system_error Thrown on failure.
  476. */
  477. template <typename SyncReadStream, typename Allocator,
  478. typename CompletionCondition>
  479. std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
  480. CompletionCondition completion_condition);
  481. /// Attempt to read a certain amount of data from a stream before returning.
  482. /**
  483. * This function is used to read a certain number of bytes of data from a
  484. * stream. The call will block until one of the following conditions is true:
  485. *
  486. * @li The supplied buffer is full (that is, it has reached maximum size).
  487. *
  488. * @li The completion_condition function object returns 0.
  489. *
  490. * This operation is implemented in terms of zero or more calls to the stream's
  491. * read_some function.
  492. *
  493. * @param s The stream from which the data is to be read. The type must support
  494. * the SyncReadStream concept.
  495. *
  496. * @param b The basic_streambuf object into which the data will be read.
  497. *
  498. * @param completion_condition The function object to be called to determine
  499. * whether the read operation is complete. The signature of the function object
  500. * must be:
  501. * @code std::size_t completion_condition(
  502. * // Result of latest read_some operation.
  503. * const boost::system::error_code& error,
  504. *
  505. * // Number of bytes transferred so far.
  506. * std::size_t bytes_transferred
  507. * ); @endcode
  508. * A return value of 0 indicates that the read operation is complete. A non-zero
  509. * return value indicates the maximum number of bytes to be read on the next
  510. * call to the stream's read_some function.
  511. *
  512. * @param ec Set to indicate what error occurred, if any.
  513. *
  514. * @returns The number of bytes read. If an error occurs, returns the total
  515. * number of bytes successfully transferred prior to the error.
  516. */
  517. template <typename SyncReadStream, typename Allocator,
  518. typename CompletionCondition>
  519. std::size_t read(SyncReadStream& s, basic_streambuf<Allocator>& b,
  520. CompletionCondition completion_condition, boost::system::error_code& ec);
  521. #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
  522. #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
  523. #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
  524. /// Attempt to read a certain amount of data from a stream before returning.
  525. /**
  526. * This function is used to read a certain number of bytes of data from a
  527. * stream. The call will block until one of the following conditions is true:
  528. *
  529. * @li The specified dynamic buffer sequence is full (that is, it has reached
  530. * maximum size).
  531. *
  532. * @li An error occurred.
  533. *
  534. * This operation is implemented in terms of zero or more calls to the stream's
  535. * read_some function.
  536. *
  537. * @param s The stream from which the data is to be read. The type must support
  538. * the SyncReadStream concept.
  539. *
  540. * @param buffers The dynamic buffer sequence into which the data will be read.
  541. *
  542. * @returns The number of bytes transferred.
  543. *
  544. * @throws boost::system::system_error Thrown on failure.
  545. *
  546. * @note This overload is equivalent to calling:
  547. * @code boost::asio::read(
  548. * s, buffers,
  549. * boost::asio::transfer_all()); @endcode
  550. */
  551. template <typename SyncReadStream, typename DynamicBuffer_v2>
  552. std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
  553. typename constraint<
  554. is_dynamic_buffer_v2<DynamicBuffer_v2>::value
  555. >::type = 0);
  556. /// Attempt to read a certain amount of data from a stream before returning.
  557. /**
  558. * This function is used to read a certain number of bytes of data from a
  559. * stream. The call will block until one of the following conditions is true:
  560. *
  561. * @li The supplied buffer is full (that is, it has reached maximum size).
  562. *
  563. * @li An error occurred.
  564. *
  565. * This operation is implemented in terms of zero or more calls to the stream's
  566. * read_some function.
  567. *
  568. * @param s The stream from which the data is to be read. The type must support
  569. * the SyncReadStream concept.
  570. *
  571. * @param buffers The dynamic buffer sequence into which the data will be read.
  572. *
  573. * @param ec Set to indicate what error occurred, if any.
  574. *
  575. * @returns The number of bytes transferred.
  576. *
  577. * @note This overload is equivalent to calling:
  578. * @code boost::asio::read(
  579. * s, buffers,
  580. * boost::asio::transfer_all(), ec); @endcode
  581. */
  582. template <typename SyncReadStream, typename DynamicBuffer_v2>
  583. std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
  584. boost::system::error_code& ec,
  585. typename constraint<
  586. is_dynamic_buffer_v2<DynamicBuffer_v2>::value
  587. >::type = 0);
  588. /// Attempt to read a certain amount of data from a stream before returning.
  589. /**
  590. * This function is used to read a certain number of bytes of data from a
  591. * stream. The call will block until one of the following conditions is true:
  592. *
  593. * @li The specified dynamic buffer sequence is full (that is, it has reached
  594. * maximum size).
  595. *
  596. * @li The completion_condition function object returns 0.
  597. *
  598. * This operation is implemented in terms of zero or more calls to the stream's
  599. * read_some function.
  600. *
  601. * @param s The stream from which the data is to be read. The type must support
  602. * the SyncReadStream concept.
  603. *
  604. * @param buffers The dynamic buffer sequence into which the data will be read.
  605. *
  606. * @param completion_condition The function object to be called to determine
  607. * whether the read operation is complete. The signature of the function object
  608. * must be:
  609. * @code std::size_t completion_condition(
  610. * // Result of latest read_some operation.
  611. * const boost::system::error_code& error,
  612. *
  613. * // Number of bytes transferred so far.
  614. * std::size_t bytes_transferred
  615. * ); @endcode
  616. * A return value of 0 indicates that the read operation is complete. A non-zero
  617. * return value indicates the maximum number of bytes to be read on the next
  618. * call to the stream's read_some function.
  619. *
  620. * @returns The number of bytes transferred.
  621. *
  622. * @throws boost::system::system_error Thrown on failure.
  623. */
  624. template <typename SyncReadStream, typename DynamicBuffer_v2,
  625. typename CompletionCondition>
  626. std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
  627. CompletionCondition completion_condition,
  628. typename constraint<
  629. is_dynamic_buffer_v2<DynamicBuffer_v2>::value
  630. >::type = 0);
  631. /// Attempt to read a certain amount of data from a stream before returning.
  632. /**
  633. * This function is used to read a certain number of bytes of data from a
  634. * stream. The call will block until one of the following conditions is true:
  635. *
  636. * @li The specified dynamic buffer sequence is full (that is, it has reached
  637. * maximum size).
  638. *
  639. * @li The completion_condition function object returns 0.
  640. *
  641. * This operation is implemented in terms of zero or more calls to the stream's
  642. * read_some function.
  643. *
  644. * @param s The stream from which the data is to be read. The type must support
  645. * the SyncReadStream concept.
  646. *
  647. * @param buffers The dynamic buffer sequence into which the data will be read.
  648. *
  649. * @param completion_condition The function object to be called to determine
  650. * whether the read operation is complete. The signature of the function object
  651. * must be:
  652. * @code std::size_t completion_condition(
  653. * // Result of latest read_some operation.
  654. * const boost::system::error_code& error,
  655. *
  656. * // Number of bytes transferred so far.
  657. * std::size_t bytes_transferred
  658. * ); @endcode
  659. * A return value of 0 indicates that the read operation is complete. A non-zero
  660. * return value indicates the maximum number of bytes to be read on the next
  661. * call to the stream's read_some function.
  662. *
  663. * @param ec Set to indicate what error occurred, if any.
  664. *
  665. * @returns The number of bytes read. If an error occurs, returns the total
  666. * number of bytes successfully transferred prior to the error.
  667. */
  668. template <typename SyncReadStream, typename DynamicBuffer_v2,
  669. typename CompletionCondition>
  670. std::size_t read(SyncReadStream& s, DynamicBuffer_v2 buffers,
  671. CompletionCondition completion_condition, boost::system::error_code& ec,
  672. typename constraint<
  673. is_dynamic_buffer_v2<DynamicBuffer_v2>::value
  674. >::type = 0);
  675. /*@}*/
  676. /**
  677. * @defgroup async_read boost::asio::async_read
  678. *
  679. * @brief The @c async_read function is a composed asynchronous operation that
  680. * reads a certain amount of data from a stream before completion.
  681. */
  682. /*@{*/
  683. /// Start an asynchronous operation to read a certain amount of data from a
  684. /// stream.
  685. /**
  686. * This function is used to asynchronously read a certain number of bytes of
  687. * data from a stream. It is an initiating function for an @ref
  688. * asynchronous_operation, and always returns immediately. The asynchronous
  689. * operation will continue until one of the following conditions is true:
  690. *
  691. * @li The supplied buffers are full. That is, the bytes transferred is equal to
  692. * the sum of the buffer sizes.
  693. *
  694. * @li An error occurred.
  695. *
  696. * This operation is implemented in terms of zero or more calls to the stream's
  697. * async_read_some function, and is known as a <em>composed operation</em>. The
  698. * program must ensure that the stream performs no other read operations (such
  699. * as async_read, the stream's async_read_some function, or any other composed
  700. * operations that perform reads) until this operation completes.
  701. *
  702. * @param s The stream from which the data is to be read. The type must support
  703. * the AsyncReadStream concept.
  704. *
  705. * @param buffers One or more buffers into which the data will be read. The sum
  706. * of the buffer sizes indicates the maximum number of bytes to read from the
  707. * stream. Although the buffers object may be copied as necessary, ownership of
  708. * the underlying memory blocks is retained by the caller, which must guarantee
  709. * that they remain valid until the completion handler is called.
  710. *
  711. * @param token The @ref completion_token that will be used to produce a
  712. * completion handler, which will be called when the read completes.
  713. * Potential completion tokens include @ref use_future, @ref use_awaitable,
  714. * @ref yield_context, or a function object with the correct completion
  715. * signature. The function signature of the completion handler must be:
  716. * @code void handler(
  717. * // Result of operation.
  718. * const boost::system::error_code& error,
  719. *
  720. * // Number of bytes copied into the buffers. If an error
  721. * // occurred, this will be the number of bytes successfully
  722. * // transferred prior to the error.
  723. * std::size_t bytes_transferred
  724. * ); @endcode
  725. * Regardless of whether the asynchronous operation completes immediately or
  726. * not, the completion handler will not be invoked from within this function.
  727. * On immediate completion, invocation of the handler will be performed in a
  728. * manner equivalent to using boost::asio::post().
  729. *
  730. * @par Completion Signature
  731. * @code void(boost::system::error_code, std::size_t) @endcode
  732. *
  733. * @par Example
  734. * To read into a single data buffer use the @ref buffer function as follows:
  735. * @code
  736. * boost::asio::async_read(s, boost::asio::buffer(data, size), handler);
  737. * @endcode
  738. * See the @ref buffer documentation for information on reading into multiple
  739. * buffers in one go, and how to use it with arrays, boost::array or
  740. * std::vector.
  741. *
  742. * @note This overload is equivalent to calling:
  743. * @code boost::asio::async_read(
  744. * s, buffers,
  745. * boost::asio::transfer_all(),
  746. * handler); @endcode
  747. *
  748. * @par Per-Operation Cancellation
  749. * This asynchronous operation supports cancellation for the following
  750. * boost::asio::cancellation_type values:
  751. *
  752. * @li @c cancellation_type::terminal
  753. *
  754. * @li @c cancellation_type::partial
  755. *
  756. * if they are also supported by the @c AsyncReadStream type's
  757. * @c async_read_some operation.
  758. */
  759. template <typename AsyncReadStream, typename MutableBufferSequence,
  760. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  761. std::size_t)) ReadToken
  762. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  763. typename AsyncReadStream::executor_type)>
  764. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
  765. void (boost::system::error_code, std::size_t))
  766. async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
  767. BOOST_ASIO_MOVE_ARG(ReadToken) token
  768. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  769. typename AsyncReadStream::executor_type),
  770. typename constraint<
  771. is_mutable_buffer_sequence<MutableBufferSequence>::value
  772. >::type = 0);
  773. /// Start an asynchronous operation to read a certain amount of data from a
  774. /// stream.
  775. /**
  776. * This function is used to asynchronously read a certain number of bytes of
  777. * data from a stream. It is an initiating function for an @ref
  778. * asynchronous_operation, and always returns immediately. The asynchronous
  779. * operation will continue until one of the following conditions is true:
  780. *
  781. * @li The supplied buffers are full. That is, the bytes transferred is equal to
  782. * the sum of the buffer sizes.
  783. *
  784. * @li The completion_condition function object returns 0.
  785. *
  786. * @param s The stream from which the data is to be read. The type must support
  787. * the AsyncReadStream concept.
  788. *
  789. * @param buffers One or more buffers into which the data will be read. The sum
  790. * of the buffer sizes indicates the maximum number of bytes to read from the
  791. * stream. Although the buffers object may be copied as necessary, ownership of
  792. * the underlying memory blocks is retained by the caller, which must guarantee
  793. * that they remain valid until the completion handler is called.
  794. *
  795. * @param completion_condition The function object to be called to determine
  796. * whether the read operation is complete. The signature of the function object
  797. * must be:
  798. * @code std::size_t completion_condition(
  799. * // Result of latest async_read_some operation.
  800. * const boost::system::error_code& error,
  801. *
  802. * // Number of bytes transferred so far.
  803. * std::size_t bytes_transferred
  804. * ); @endcode
  805. * A return value of 0 indicates that the read operation is complete. A non-zero
  806. * return value indicates the maximum number of bytes to be read on the next
  807. * call to the stream's async_read_some function.
  808. *
  809. * @param token The @ref completion_token that will be used to produce a
  810. * completion handler, which will be called when the read completes.
  811. * Potential completion tokens include @ref use_future, @ref use_awaitable,
  812. * @ref yield_context, or a function object with the correct completion
  813. * signature. The function signature of the completion handler must be:
  814. * @code void handler(
  815. * // Result of operation.
  816. * const boost::system::error_code& error,
  817. *
  818. * // Number of bytes copied into the buffers. If an error
  819. * // occurred, this will be the number of bytes successfully
  820. * // transferred prior to the error.
  821. * std::size_t bytes_transferred
  822. * ); @endcode
  823. * Regardless of whether the asynchronous operation completes immediately or
  824. * not, the completion handler will not be invoked from within this function.
  825. * On immediate completion, invocation of the handler will be performed in a
  826. * manner equivalent to using boost::asio::post().
  827. *
  828. * @par Completion Signature
  829. * @code void(boost::system::error_code, std::size_t) @endcode
  830. *
  831. * @par Example
  832. * To read into a single data buffer use the @ref buffer function as follows:
  833. * @code boost::asio::async_read(s,
  834. * boost::asio::buffer(data, size),
  835. * boost::asio::transfer_at_least(32),
  836. * handler); @endcode
  837. * See the @ref buffer documentation for information on reading into multiple
  838. * buffers in one go, and how to use it with arrays, boost::array or
  839. * std::vector.
  840. *
  841. * @par Per-Operation Cancellation
  842. * This asynchronous operation supports cancellation for the following
  843. * boost::asio::cancellation_type values:
  844. *
  845. * @li @c cancellation_type::terminal
  846. *
  847. * @li @c cancellation_type::partial
  848. *
  849. * if they are also supported by the @c AsyncReadStream type's
  850. * @c async_read_some operation.
  851. */
  852. template <typename AsyncReadStream,
  853. typename MutableBufferSequence, typename CompletionCondition,
  854. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  855. std::size_t)) ReadToken
  856. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  857. typename AsyncReadStream::executor_type)>
  858. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
  859. void (boost::system::error_code, std::size_t))
  860. async_read(AsyncReadStream& s, const MutableBufferSequence& buffers,
  861. CompletionCondition completion_condition,
  862. BOOST_ASIO_MOVE_ARG(ReadToken) token
  863. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  864. typename AsyncReadStream::executor_type),
  865. typename constraint<
  866. is_mutable_buffer_sequence<MutableBufferSequence>::value
  867. >::type = 0);
  868. #if !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
  869. /// Start an asynchronous operation to read a certain amount of data from a
  870. /// stream.
  871. /**
  872. * This function is used to asynchronously read a certain number of bytes of
  873. * data from a stream. It is an initiating function for an @ref
  874. * asynchronous_operation, and always returns immediately. The asynchronous
  875. * operation will continue until one of the following conditions is true:
  876. *
  877. * @li The specified dynamic buffer sequence is full (that is, it has reached
  878. * maximum size).
  879. *
  880. * @li An error occurred.
  881. *
  882. * This operation is implemented in terms of zero or more calls to the stream's
  883. * async_read_some function, and is known as a <em>composed operation</em>. The
  884. * program must ensure that the stream performs no other read operations (such
  885. * as async_read, the stream's async_read_some function, or any other composed
  886. * operations that perform reads) until this operation completes.
  887. *
  888. * @param s The stream from which the data is to be read. The type must support
  889. * the AsyncReadStream concept.
  890. *
  891. * @param buffers The dynamic buffer sequence into which the data will be read.
  892. * Although the buffers object may be copied as necessary, ownership of the
  893. * underlying memory blocks is retained by the caller, which must guarantee
  894. * that they remain valid until the completion handler is called.
  895. *
  896. * @param token The @ref completion_token that will be used to produce a
  897. * completion handler, which will be called when the read completes.
  898. * Potential completion tokens include @ref use_future, @ref use_awaitable,
  899. * @ref yield_context, or a function object with the correct completion
  900. * signature. The function signature of the completion handler must be:
  901. * @code void handler(
  902. * // Result of operation.
  903. * const boost::system::error_code& error,
  904. *
  905. * // Number of bytes copied into the buffers. If an error
  906. * // occurred, this will be the number of bytes successfully
  907. * // transferred prior to the error.
  908. * std::size_t bytes_transferred
  909. * ); @endcode
  910. * Regardless of whether the asynchronous operation completes immediately or
  911. * not, the completion handler will not be invoked from within this function.
  912. * On immediate completion, invocation of the handler will be performed in a
  913. * manner equivalent to using boost::asio::post().
  914. *
  915. * @par Completion Signature
  916. * @code void(boost::system::error_code, std::size_t) @endcode
  917. *
  918. * @note This overload is equivalent to calling:
  919. * @code boost::asio::async_read(
  920. * s, buffers,
  921. * boost::asio::transfer_all(),
  922. * handler); @endcode
  923. *
  924. * @par Per-Operation Cancellation
  925. * This asynchronous operation supports cancellation for the following
  926. * boost::asio::cancellation_type values:
  927. *
  928. * @li @c cancellation_type::terminal
  929. *
  930. * @li @c cancellation_type::partial
  931. *
  932. * if they are also supported by the @c AsyncReadStream type's
  933. * @c async_read_some operation.
  934. */
  935. template <typename AsyncReadStream, typename DynamicBuffer_v1,
  936. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  937. std::size_t)) ReadToken
  938. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  939. typename AsyncReadStream::executor_type)>
  940. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
  941. void (boost::system::error_code, std::size_t))
  942. async_read(AsyncReadStream& s,
  943. BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
  944. BOOST_ASIO_MOVE_ARG(ReadToken) token
  945. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  946. typename AsyncReadStream::executor_type),
  947. typename constraint<
  948. is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
  949. >::type = 0,
  950. typename constraint<
  951. !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
  952. >::type = 0);
  953. /// Start an asynchronous operation to read a certain amount of data from a
  954. /// stream.
  955. /**
  956. * This function is used to asynchronously read a certain number of bytes of
  957. * data from a stream. It is an initiating function for an @ref
  958. * asynchronous_operation, and always returns immediately. The asynchronous
  959. * operation will continue until one of the following conditions is true:
  960. *
  961. * @li The specified dynamic buffer sequence is full (that is, it has reached
  962. * maximum size).
  963. *
  964. * @li The completion_condition function object returns 0.
  965. *
  966. * This operation is implemented in terms of zero or more calls to the stream's
  967. * async_read_some function, and is known as a <em>composed operation</em>. The
  968. * program must ensure that the stream performs no other read operations (such
  969. * as async_read, the stream's async_read_some function, or any other composed
  970. * operations that perform reads) until this operation completes.
  971. *
  972. * @param s The stream from which the data is to be read. The type must support
  973. * the AsyncReadStream concept.
  974. *
  975. * @param buffers The dynamic buffer sequence into which the data will be read.
  976. * Although the buffers object may be copied as necessary, ownership of the
  977. * underlying memory blocks is retained by the caller, which must guarantee
  978. * that they remain valid until the completion handler is called.
  979. *
  980. * @param completion_condition The function object to be called to determine
  981. * whether the read operation is complete. The signature of the function object
  982. * must be:
  983. * @code std::size_t completion_condition(
  984. * // Result of latest async_read_some operation.
  985. * const boost::system::error_code& error,
  986. *
  987. * // Number of bytes transferred so far.
  988. * std::size_t bytes_transferred
  989. * ); @endcode
  990. * A return value of 0 indicates that the read operation is complete. A non-zero
  991. * return value indicates the maximum number of bytes to be read on the next
  992. * call to the stream's async_read_some function.
  993. *
  994. * @param token The @ref completion_token that will be used to produce a
  995. * completion handler, which will be called when the read completes.
  996. * Potential completion tokens include @ref use_future, @ref use_awaitable,
  997. * @ref yield_context, or a function object with the correct completion
  998. * signature. The function signature of the completion handler must be:
  999. * @code void handler(
  1000. * // Result of operation.
  1001. * const boost::system::error_code& error,
  1002. *
  1003. * // Number of bytes copied into the buffers. If an error
  1004. * // occurred, this will be the number of bytes successfully
  1005. * // transferred prior to the error.
  1006. * std::size_t bytes_transferred
  1007. * ); @endcode
  1008. * Regardless of whether the asynchronous operation completes immediately or
  1009. * not, the completion handler will not be invoked from within this function.
  1010. * On immediate completion, invocation of the handler will be performed in a
  1011. * manner equivalent to using boost::asio::post().
  1012. *
  1013. * @par Completion Signature
  1014. * @code void(boost::system::error_code, std::size_t) @endcode
  1015. *
  1016. * @par Per-Operation Cancellation
  1017. * This asynchronous operation supports cancellation for the following
  1018. * boost::asio::cancellation_type values:
  1019. *
  1020. * @li @c cancellation_type::terminal
  1021. *
  1022. * @li @c cancellation_type::partial
  1023. *
  1024. * if they are also supported by the @c AsyncReadStream type's
  1025. * @c async_read_some operation.
  1026. */
  1027. template <typename AsyncReadStream,
  1028. typename DynamicBuffer_v1, typename CompletionCondition,
  1029. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  1030. std::size_t)) ReadToken
  1031. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  1032. typename AsyncReadStream::executor_type)>
  1033. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
  1034. void (boost::system::error_code, std::size_t))
  1035. async_read(AsyncReadStream& s,
  1036. BOOST_ASIO_MOVE_ARG(DynamicBuffer_v1) buffers,
  1037. CompletionCondition completion_condition,
  1038. BOOST_ASIO_MOVE_ARG(ReadToken) token
  1039. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  1040. typename AsyncReadStream::executor_type),
  1041. typename constraint<
  1042. is_dynamic_buffer_v1<typename decay<DynamicBuffer_v1>::type>::value
  1043. >::type = 0,
  1044. typename constraint<
  1045. !is_dynamic_buffer_v2<typename decay<DynamicBuffer_v1>::type>::value
  1046. >::type = 0);
  1047. #if !defined(BOOST_ASIO_NO_EXTENSIONS)
  1048. #if !defined(BOOST_ASIO_NO_IOSTREAM)
  1049. /// Start an asynchronous operation to read a certain amount of data from a
  1050. /// stream.
  1051. /**
  1052. * This function is used to asynchronously read a certain number of bytes of
  1053. * data from a stream. It is an initiating function for an @ref
  1054. * asynchronous_operation, and always returns immediately. The asynchronous
  1055. * operation will continue until one of the following conditions is true:
  1056. *
  1057. * @li The supplied buffer is full (that is, it has reached maximum size).
  1058. *
  1059. * @li An error occurred.
  1060. *
  1061. * This operation is implemented in terms of zero or more calls to the stream's
  1062. * async_read_some function, and is known as a <em>composed operation</em>. The
  1063. * program must ensure that the stream performs no other read operations (such
  1064. * as async_read, the stream's async_read_some function, or any other composed
  1065. * operations that perform reads) until this operation completes.
  1066. *
  1067. * @param s The stream from which the data is to be read. The type must support
  1068. * the AsyncReadStream concept.
  1069. *
  1070. * @param b A basic_streambuf object into which the data will be read. Ownership
  1071. * of the streambuf is retained by the caller, which must guarantee that it
  1072. * remains valid until the completion handler is called.
  1073. *
  1074. * @param token The @ref completion_token that will be used to produce a
  1075. * completion handler, which will be called when the read completes.
  1076. * Potential completion tokens include @ref use_future, @ref use_awaitable,
  1077. * @ref yield_context, or a function object with the correct completion
  1078. * signature. The function signature of the completion handler must be:
  1079. * @code void handler(
  1080. * // Result of operation.
  1081. * const boost::system::error_code& error,
  1082. *
  1083. * // Number of bytes copied into the buffers. If an error
  1084. * // occurred, this will be the number of bytes successfully
  1085. * // transferred prior to the error.
  1086. * std::size_t bytes_transferred
  1087. * ); @endcode
  1088. * Regardless of whether the asynchronous operation completes immediately or
  1089. * not, the completion handler will not be invoked from within this function.
  1090. * On immediate completion, invocation of the handler will be performed in a
  1091. * manner equivalent to using boost::asio::post().
  1092. *
  1093. * @par Completion Signature
  1094. * @code void(boost::system::error_code, std::size_t) @endcode
  1095. *
  1096. * @note This overload is equivalent to calling:
  1097. * @code boost::asio::async_read(
  1098. * s, b,
  1099. * boost::asio::transfer_all(),
  1100. * handler); @endcode
  1101. *
  1102. * @par Per-Operation Cancellation
  1103. * This asynchronous operation supports cancellation for the following
  1104. * boost::asio::cancellation_type values:
  1105. *
  1106. * @li @c cancellation_type::terminal
  1107. *
  1108. * @li @c cancellation_type::partial
  1109. *
  1110. * if they are also supported by the @c AsyncReadStream type's
  1111. * @c async_read_some operation.
  1112. */
  1113. template <typename AsyncReadStream, typename Allocator,
  1114. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  1115. std::size_t)) ReadToken
  1116. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  1117. typename AsyncReadStream::executor_type)>
  1118. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
  1119. void (boost::system::error_code, std::size_t))
  1120. async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
  1121. BOOST_ASIO_MOVE_ARG(ReadToken) token
  1122. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  1123. typename AsyncReadStream::executor_type));
  1124. /// Start an asynchronous operation to read a certain amount of data from a
  1125. /// stream.
  1126. /**
  1127. * This function is used to asynchronously read a certain number of bytes of
  1128. * data from a stream. It is an initiating function for an @ref
  1129. * asynchronous_operation, and always returns immediately. The asynchronous
  1130. * operation will continue until one of the following conditions is true:
  1131. *
  1132. * @li The supplied buffer is full (that is, it has reached maximum size).
  1133. *
  1134. * @li The completion_condition function object returns 0.
  1135. *
  1136. * This operation is implemented in terms of zero or more calls to the stream's
  1137. * async_read_some function, and is known as a <em>composed operation</em>. The
  1138. * program must ensure that the stream performs no other read operations (such
  1139. * as async_read, the stream's async_read_some function, or any other composed
  1140. * operations that perform reads) until this operation completes.
  1141. *
  1142. * @param s The stream from which the data is to be read. The type must support
  1143. * the AsyncReadStream concept.
  1144. *
  1145. * @param b A basic_streambuf object into which the data will be read. Ownership
  1146. * of the streambuf is retained by the caller, which must guarantee that it
  1147. * remains valid until the completion handler is called.
  1148. *
  1149. * @param completion_condition The function object to be called to determine
  1150. * whether the read operation is complete. The signature of the function object
  1151. * must be:
  1152. * @code std::size_t completion_condition(
  1153. * // Result of latest async_read_some operation.
  1154. * const boost::system::error_code& error,
  1155. *
  1156. * // Number of bytes transferred so far.
  1157. * std::size_t bytes_transferred
  1158. * ); @endcode
  1159. * A return value of 0 indicates that the read operation is complete. A non-zero
  1160. * return value indicates the maximum number of bytes to be read on the next
  1161. * call to the stream's async_read_some function.
  1162. *
  1163. * @param token The @ref completion_token that will be used to produce a
  1164. * completion handler, which will be called when the read completes.
  1165. * Potential completion tokens include @ref use_future, @ref use_awaitable,
  1166. * @ref yield_context, or a function object with the correct completion
  1167. * signature. The function signature of the completion handler must be:
  1168. * @code void handler(
  1169. * // Result of operation.
  1170. * const boost::system::error_code& error,
  1171. *
  1172. * // Number of bytes copied into the buffers. If an error
  1173. * // occurred, this will be the number of bytes successfully
  1174. * // transferred prior to the error.
  1175. * std::size_t bytes_transferred
  1176. * ); @endcode
  1177. * Regardless of whether the asynchronous operation completes immediately or
  1178. * not, the completion handler will not be invoked from within this function.
  1179. * On immediate completion, invocation of the handler will be performed in a
  1180. * manner equivalent to using boost::asio::post().
  1181. *
  1182. * @par Completion Signature
  1183. * @code void(boost::system::error_code, std::size_t) @endcode
  1184. *
  1185. * @par Per-Operation Cancellation
  1186. * This asynchronous operation supports cancellation for the following
  1187. * boost::asio::cancellation_type values:
  1188. *
  1189. * @li @c cancellation_type::terminal
  1190. *
  1191. * @li @c cancellation_type::partial
  1192. *
  1193. * if they are also supported by the @c AsyncReadStream type's
  1194. * @c async_read_some operation.
  1195. */
  1196. template <typename AsyncReadStream,
  1197. typename Allocator, typename CompletionCondition,
  1198. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  1199. std::size_t)) ReadToken
  1200. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  1201. typename AsyncReadStream::executor_type)>
  1202. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
  1203. void (boost::system::error_code, std::size_t))
  1204. async_read(AsyncReadStream& s, basic_streambuf<Allocator>& b,
  1205. CompletionCondition completion_condition,
  1206. BOOST_ASIO_MOVE_ARG(ReadToken) token
  1207. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  1208. typename AsyncReadStream::executor_type));
  1209. #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
  1210. #endif // !defined(BOOST_ASIO_NO_EXTENSIONS)
  1211. #endif // !defined(BOOST_ASIO_NO_DYNAMIC_BUFFER_V1)
  1212. /// Start an asynchronous operation to read a certain amount of data from a
  1213. /// stream.
  1214. /**
  1215. * This function is used to asynchronously read a certain number of bytes of
  1216. * data from a stream. It is an initiating function for an @ref
  1217. * asynchronous_operation, and always returns immediately. The asynchronous
  1218. * operation will continue until one of the following conditions is true:
  1219. *
  1220. * @li The specified dynamic buffer sequence is full (that is, it has reached
  1221. * maximum size).
  1222. *
  1223. * @li An error occurred.
  1224. *
  1225. * This operation is implemented in terms of zero or more calls to the stream's
  1226. * async_read_some function, and is known as a <em>composed operation</em>. The
  1227. * program must ensure that the stream performs no other read operations (such
  1228. * as async_read, the stream's async_read_some function, or any other composed
  1229. * operations that perform reads) until this operation completes.
  1230. *
  1231. * @param s The stream from which the data is to be read. The type must support
  1232. * the AsyncReadStream concept.
  1233. *
  1234. * @param buffers The dynamic buffer sequence into which the data will be read.
  1235. * Although the buffers object may be copied as necessary, ownership of the
  1236. * underlying memory blocks is retained by the caller, which must guarantee
  1237. * that they remain valid until the completion handler is called.
  1238. *
  1239. * @param token The @ref completion_token that will be used to produce a
  1240. * completion handler, which will be called when the read completes.
  1241. * Potential completion tokens include @ref use_future, @ref use_awaitable,
  1242. * @ref yield_context, or a function object with the correct completion
  1243. * signature. The function signature of the completion handler must be:
  1244. * @code void handler(
  1245. * // Result of operation.
  1246. * const boost::system::error_code& error,
  1247. *
  1248. * // Number of bytes copied into the buffers. If an error
  1249. * // occurred, this will be the number of bytes successfully
  1250. * // transferred prior to the error.
  1251. * std::size_t bytes_transferred
  1252. * ); @endcode
  1253. * Regardless of whether the asynchronous operation completes immediately or
  1254. * not, the completion handler will not be invoked from within this function.
  1255. * On immediate completion, invocation of the handler will be performed in a
  1256. * manner equivalent to using boost::asio::post().
  1257. *
  1258. * @par Completion Signature
  1259. * @code void(boost::system::error_code, std::size_t) @endcode
  1260. *
  1261. * @note This overload is equivalent to calling:
  1262. * @code boost::asio::async_read(
  1263. * s, buffers,
  1264. * boost::asio::transfer_all(),
  1265. * handler); @endcode
  1266. *
  1267. * @par Per-Operation Cancellation
  1268. * This asynchronous operation supports cancellation for the following
  1269. * boost::asio::cancellation_type values:
  1270. *
  1271. * @li @c cancellation_type::terminal
  1272. *
  1273. * @li @c cancellation_type::partial
  1274. *
  1275. * if they are also supported by the @c AsyncReadStream type's
  1276. * @c async_read_some operation.
  1277. */
  1278. template <typename AsyncReadStream, typename DynamicBuffer_v2,
  1279. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  1280. std::size_t)) ReadToken
  1281. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  1282. typename AsyncReadStream::executor_type)>
  1283. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
  1284. void (boost::system::error_code, std::size_t))
  1285. async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers,
  1286. BOOST_ASIO_MOVE_ARG(ReadToken) token
  1287. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  1288. typename AsyncReadStream::executor_type),
  1289. typename constraint<
  1290. is_dynamic_buffer_v2<DynamicBuffer_v2>::value
  1291. >::type = 0);
  1292. /// Start an asynchronous operation to read a certain amount of data from a
  1293. /// stream.
  1294. /**
  1295. * This function is used to asynchronously read a certain number of bytes of
  1296. * data from a stream. It is an initiating function for an @ref
  1297. * asynchronous_operation, and always returns immediately. The asynchronous
  1298. * operation will continue until one of the following conditions is true:
  1299. *
  1300. * @li The specified dynamic buffer sequence is full (that is, it has reached
  1301. * maximum size).
  1302. *
  1303. * @li The completion_condition function object returns 0.
  1304. *
  1305. * This operation is implemented in terms of zero or more calls to the stream's
  1306. * async_read_some function, and is known as a <em>composed operation</em>. The
  1307. * program must ensure that the stream performs no other read operations (such
  1308. * as async_read, the stream's async_read_some function, or any other composed
  1309. * operations that perform reads) until this operation completes.
  1310. *
  1311. * @param s The stream from which the data is to be read. The type must support
  1312. * the AsyncReadStream concept.
  1313. *
  1314. * @param buffers The dynamic buffer sequence into which the data will be read.
  1315. * Although the buffers object may be copied as necessary, ownership of the
  1316. * underlying memory blocks is retained by the caller, which must guarantee
  1317. * that they remain valid until the completion handler is called.
  1318. *
  1319. * @param completion_condition The function object to be called to determine
  1320. * whether the read operation is complete. The signature of the function object
  1321. * must be:
  1322. * @code std::size_t completion_condition(
  1323. * // Result of latest async_read_some operation.
  1324. * const boost::system::error_code& error,
  1325. *
  1326. * // Number of bytes transferred so far.
  1327. * std::size_t bytes_transferred
  1328. * ); @endcode
  1329. * A return value of 0 indicates that the read operation is complete. A non-zero
  1330. * return value indicates the maximum number of bytes to be read on the next
  1331. * call to the stream's async_read_some function.
  1332. *
  1333. * @param token The @ref completion_token that will be used to produce a
  1334. * completion handler, which will be called when the read completes.
  1335. * Potential completion tokens include @ref use_future, @ref use_awaitable,
  1336. * @ref yield_context, or a function object with the correct completion
  1337. * signature. The function signature of the completion handler must be:
  1338. * @code void handler(
  1339. * // Result of operation.
  1340. * const boost::system::error_code& error,
  1341. *
  1342. * // Number of bytes copied into the buffers. If an error
  1343. * // occurred, this will be the number of bytes successfully
  1344. * // transferred prior to the error.
  1345. * std::size_t bytes_transferred
  1346. * ); @endcode
  1347. * Regardless of whether the asynchronous operation completes immediately or
  1348. * not, the completion handler will not be invoked from within this function.
  1349. * On immediate completion, invocation of the handler will be performed in a
  1350. * manner equivalent to using boost::asio::post().
  1351. *
  1352. * @par Completion Signature
  1353. * @code void(boost::system::error_code, std::size_t) @endcode
  1354. *
  1355. * @par Per-Operation Cancellation
  1356. * This asynchronous operation supports cancellation for the following
  1357. * boost::asio::cancellation_type values:
  1358. *
  1359. * @li @c cancellation_type::terminal
  1360. *
  1361. * @li @c cancellation_type::partial
  1362. *
  1363. * if they are also supported by the @c AsyncReadStream type's
  1364. * @c async_read_some operation.
  1365. */
  1366. template <typename AsyncReadStream,
  1367. typename DynamicBuffer_v2, typename CompletionCondition,
  1368. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  1369. std::size_t)) ReadToken
  1370. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(
  1371. typename AsyncReadStream::executor_type)>
  1372. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadToken,
  1373. void (boost::system::error_code, std::size_t))
  1374. async_read(AsyncReadStream& s, DynamicBuffer_v2 buffers,
  1375. CompletionCondition completion_condition,
  1376. BOOST_ASIO_MOVE_ARG(ReadToken) token
  1377. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(
  1378. typename AsyncReadStream::executor_type),
  1379. typename constraint<
  1380. is_dynamic_buffer_v2<DynamicBuffer_v2>::value
  1381. >::type = 0);
  1382. /*@}*/
  1383. } // namespace asio
  1384. } // namespace boost
  1385. #include <boost/asio/detail/pop_options.hpp>
  1386. #include <boost/asio/impl/read.hpp>
  1387. #endif // BOOST_ASIO_READ_HPP