basic_seq_packet_socket.hpp 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715
  1. //
  2. // basic_seq_packet_socket.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_BASIC_SEQ_PACKET_SOCKET_HPP
  11. #define BOOST_ASIO_BASIC_SEQ_PACKET_SOCKET_HPP
  12. #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  13. # pragma once
  14. #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  15. #include <boost/asio/detail/config.hpp>
  16. #include <cstddef>
  17. #include <boost/asio/basic_socket.hpp>
  18. #include <boost/asio/detail/handler_type_requirements.hpp>
  19. #include <boost/asio/detail/throw_error.hpp>
  20. #include <boost/asio/error.hpp>
  21. #include <boost/asio/detail/push_options.hpp>
  22. namespace boost {
  23. namespace asio {
  24. #if !defined(BOOST_ASIO_BASIC_SEQ_PACKET_SOCKET_FWD_DECL)
  25. #define BOOST_ASIO_BASIC_SEQ_PACKET_SOCKET_FWD_DECL
  26. // Forward declaration with defaulted arguments.
  27. template <typename Protocol, typename Executor = executor>
  28. class basic_seq_packet_socket;
  29. #endif // !defined(BOOST_ASIO_BASIC_SEQ_PACKET_SOCKET_FWD_DECL)
  30. /// Provides sequenced packet socket functionality.
  31. /**
  32. * The basic_seq_packet_socket class template provides asynchronous and blocking
  33. * sequenced packet socket functionality.
  34. *
  35. * @par Thread Safety
  36. * @e Distinct @e objects: Safe.@n
  37. * @e Shared @e objects: Unsafe.
  38. */
  39. template <typename Protocol, typename Executor>
  40. class basic_seq_packet_socket
  41. : public basic_socket<Protocol, Executor>
  42. {
  43. public:
  44. /// The type of the executor associated with the object.
  45. typedef Executor executor_type;
  46. /// Rebinds the socket type to another executor.
  47. template <typename Executor1>
  48. struct rebind_executor
  49. {
  50. /// The socket type when rebound to the specified executor.
  51. typedef basic_seq_packet_socket<Protocol, Executor1> other;
  52. };
  53. /// The native representation of a socket.
  54. #if defined(GENERATING_DOCUMENTATION)
  55. typedef implementation_defined native_handle_type;
  56. #else
  57. typedef typename basic_socket<Protocol,
  58. Executor>::native_handle_type native_handle_type;
  59. #endif
  60. /// The protocol type.
  61. typedef Protocol protocol_type;
  62. /// The endpoint type.
  63. typedef typename Protocol::endpoint endpoint_type;
  64. /// Construct a basic_seq_packet_socket without opening it.
  65. /**
  66. * This constructor creates a sequenced packet socket without opening it. The
  67. * socket needs to be opened and then connected or accepted before data can
  68. * be sent or received on it.
  69. *
  70. * @param ex The I/O executor that the socket will use, by default, to
  71. * dispatch handlers for any asynchronous operations performed on the socket.
  72. */
  73. explicit basic_seq_packet_socket(const executor_type& ex)
  74. : basic_socket<Protocol, Executor>(ex)
  75. {
  76. }
  77. /// Construct a basic_seq_packet_socket without opening it.
  78. /**
  79. * This constructor creates a sequenced packet socket without opening it. The
  80. * socket needs to be opened and then connected or accepted before data can
  81. * be sent or received on it.
  82. *
  83. * @param context An execution context which provides the I/O executor that
  84. * the socket will use, by default, to dispatch handlers for any asynchronous
  85. * operations performed on the socket.
  86. */
  87. template <typename ExecutionContext>
  88. explicit basic_seq_packet_socket(ExecutionContext& context,
  89. typename enable_if<
  90. is_convertible<ExecutionContext&, execution_context&>::value
  91. >::type* = 0)
  92. : basic_socket<Protocol, Executor>(context)
  93. {
  94. }
  95. /// Construct and open a basic_seq_packet_socket.
  96. /**
  97. * This constructor creates and opens a sequenced_packet socket. The socket
  98. * needs to be connected or accepted before data can be sent or received on
  99. * it.
  100. *
  101. * @param ex The I/O executor that the socket will use, by default, to
  102. * dispatch handlers for any asynchronous operations performed on the socket.
  103. *
  104. * @param protocol An object specifying protocol parameters to be used.
  105. *
  106. * @throws boost::system::system_error Thrown on failure.
  107. */
  108. basic_seq_packet_socket(const executor_type& ex,
  109. const protocol_type& protocol)
  110. : basic_socket<Protocol, Executor>(ex, protocol)
  111. {
  112. }
  113. /// Construct and open a basic_seq_packet_socket.
  114. /**
  115. * This constructor creates and opens a sequenced_packet socket. The socket
  116. * needs to be connected or accepted before data can be sent or received on
  117. * it.
  118. *
  119. * @param context An execution context which provides the I/O executor that
  120. * the socket will use, by default, to dispatch handlers for any asynchronous
  121. * operations performed on the socket.
  122. *
  123. * @param protocol An object specifying protocol parameters to be used.
  124. *
  125. * @throws boost::system::system_error Thrown on failure.
  126. */
  127. template <typename ExecutionContext>
  128. basic_seq_packet_socket(ExecutionContext& context,
  129. const protocol_type& protocol,
  130. typename enable_if<
  131. is_convertible<ExecutionContext&, execution_context&>::value
  132. >::type* = 0)
  133. : basic_socket<Protocol, Executor>(context, protocol)
  134. {
  135. }
  136. /// Construct a basic_seq_packet_socket, opening it and binding it to the
  137. /// given local endpoint.
  138. /**
  139. * This constructor creates a sequenced packet socket and automatically opens
  140. * it bound to the specified endpoint on the local machine. The protocol used
  141. * is the protocol associated with the given endpoint.
  142. *
  143. * @param ex The I/O executor that the socket will use, by default, to
  144. * dispatch handlers for any asynchronous operations performed on the socket.
  145. *
  146. * @param endpoint An endpoint on the local machine to which the sequenced
  147. * packet socket will be bound.
  148. *
  149. * @throws boost::system::system_error Thrown on failure.
  150. */
  151. basic_seq_packet_socket(const executor_type& ex,
  152. const endpoint_type& endpoint)
  153. : basic_socket<Protocol, Executor>(ex, endpoint)
  154. {
  155. }
  156. /// Construct a basic_seq_packet_socket, opening it and binding it to the
  157. /// given local endpoint.
  158. /**
  159. * This constructor creates a sequenced packet socket and automatically opens
  160. * it bound to the specified endpoint on the local machine. The protocol used
  161. * is the protocol associated with the given endpoint.
  162. *
  163. * @param context An execution context which provides the I/O executor that
  164. * the socket will use, by default, to dispatch handlers for any asynchronous
  165. * operations performed on the socket.
  166. *
  167. * @param endpoint An endpoint on the local machine to which the sequenced
  168. * packet socket will be bound.
  169. *
  170. * @throws boost::system::system_error Thrown on failure.
  171. */
  172. template <typename ExecutionContext>
  173. basic_seq_packet_socket(ExecutionContext& context,
  174. const endpoint_type& endpoint,
  175. typename enable_if<
  176. is_convertible<ExecutionContext&, execution_context&>::value
  177. >::type* = 0)
  178. : basic_socket<Protocol, Executor>(context, endpoint)
  179. {
  180. }
  181. /// Construct a basic_seq_packet_socket on an existing native socket.
  182. /**
  183. * This constructor creates a sequenced packet socket object to hold an
  184. * existing native socket.
  185. *
  186. * @param ex The I/O executor that the socket will use, by default, to
  187. * dispatch handlers for any asynchronous operations performed on the socket.
  188. *
  189. * @param protocol An object specifying protocol parameters to be used.
  190. *
  191. * @param native_socket The new underlying socket implementation.
  192. *
  193. * @throws boost::system::system_error Thrown on failure.
  194. */
  195. basic_seq_packet_socket(const executor_type& ex,
  196. const protocol_type& protocol, const native_handle_type& native_socket)
  197. : basic_socket<Protocol, Executor>(ex, protocol, native_socket)
  198. {
  199. }
  200. /// Construct a basic_seq_packet_socket on an existing native socket.
  201. /**
  202. * This constructor creates a sequenced packet socket object to hold an
  203. * existing native socket.
  204. *
  205. * @param context An execution context which provides the I/O executor that
  206. * the socket will use, by default, to dispatch handlers for any asynchronous
  207. * operations performed on the socket.
  208. *
  209. * @param protocol An object specifying protocol parameters to be used.
  210. *
  211. * @param native_socket The new underlying socket implementation.
  212. *
  213. * @throws boost::system::system_error Thrown on failure.
  214. */
  215. template <typename ExecutionContext>
  216. basic_seq_packet_socket(ExecutionContext& context,
  217. const protocol_type& protocol, const native_handle_type& native_socket,
  218. typename enable_if<
  219. is_convertible<ExecutionContext&, execution_context&>::value
  220. >::type* = 0)
  221. : basic_socket<Protocol, Executor>(context, protocol, native_socket)
  222. {
  223. }
  224. #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  225. /// Move-construct a basic_seq_packet_socket from another.
  226. /**
  227. * This constructor moves a sequenced packet socket from one object to
  228. * another.
  229. *
  230. * @param other The other basic_seq_packet_socket object from which the move
  231. * will occur.
  232. *
  233. * @note Following the move, the moved-from object is in the same state as if
  234. * constructed using the @c basic_seq_packet_socket(const executor_type&)
  235. * constructor.
  236. */
  237. basic_seq_packet_socket(basic_seq_packet_socket&& other)
  238. : basic_socket<Protocol, Executor>(std::move(other))
  239. {
  240. }
  241. /// Move-assign a basic_seq_packet_socket from another.
  242. /**
  243. * This assignment operator moves a sequenced packet socket from one object to
  244. * another.
  245. *
  246. * @param other The other basic_seq_packet_socket object from which the move
  247. * will occur.
  248. *
  249. * @note Following the move, the moved-from object is in the same state as if
  250. * constructed using the @c basic_seq_packet_socket(const executor_type&)
  251. * constructor.
  252. */
  253. basic_seq_packet_socket& operator=(basic_seq_packet_socket&& other)
  254. {
  255. basic_socket<Protocol, Executor>::operator=(std::move(other));
  256. return *this;
  257. }
  258. /// Move-construct a basic_seq_packet_socket from a socket of another protocol
  259. /// type.
  260. /**
  261. * This constructor moves a sequenced packet socket from one object to
  262. * another.
  263. *
  264. * @param other The other basic_seq_packet_socket object from which the move
  265. * will occur.
  266. *
  267. * @note Following the move, the moved-from object is in the same state as if
  268. * constructed using the @c basic_seq_packet_socket(const executor_type&)
  269. * constructor.
  270. */
  271. template <typename Protocol1, typename Executor1>
  272. basic_seq_packet_socket(basic_seq_packet_socket<Protocol1, Executor1>&& other,
  273. typename enable_if<
  274. is_convertible<Protocol1, Protocol>::value
  275. && is_convertible<Executor1, Executor>::value
  276. >::type* = 0)
  277. : basic_socket<Protocol, Executor>(std::move(other))
  278. {
  279. }
  280. /// Move-assign a basic_seq_packet_socket from a socket of another protocol
  281. /// type.
  282. /**
  283. * This assignment operator moves a sequenced packet socket from one object to
  284. * another.
  285. *
  286. * @param other The other basic_seq_packet_socket object from which the move
  287. * will occur.
  288. *
  289. * @note Following the move, the moved-from object is in the same state as if
  290. * constructed using the @c basic_seq_packet_socket(const executor_type&)
  291. * constructor.
  292. */
  293. template <typename Protocol1, typename Executor1>
  294. typename enable_if<
  295. is_convertible<Protocol1, Protocol>::value
  296. && is_convertible<Executor1, Executor>::value,
  297. basic_seq_packet_socket&
  298. >::type operator=(basic_seq_packet_socket<Protocol1, Executor1>&& other)
  299. {
  300. basic_socket<Protocol, Executor>::operator=(std::move(other));
  301. return *this;
  302. }
  303. #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  304. /// Destroys the socket.
  305. /**
  306. * This function destroys the socket, cancelling any outstanding asynchronous
  307. * operations associated with the socket as if by calling @c cancel.
  308. */
  309. ~basic_seq_packet_socket()
  310. {
  311. }
  312. /// Send some data on the socket.
  313. /**
  314. * This function is used to send data on the sequenced packet socket. The
  315. * function call will block until the data has been sent successfully, or an
  316. * until error occurs.
  317. *
  318. * @param buffers One or more data buffers to be sent on the socket.
  319. *
  320. * @param flags Flags specifying how the send call is to be made.
  321. *
  322. * @returns The number of bytes sent.
  323. *
  324. * @throws boost::system::system_error Thrown on failure.
  325. *
  326. * @par Example
  327. * To send a single data buffer use the @ref buffer function as follows:
  328. * @code
  329. * socket.send(boost::asio::buffer(data, size), 0);
  330. * @endcode
  331. * See the @ref buffer documentation for information on sending multiple
  332. * buffers in one go, and how to use it with arrays, boost::array or
  333. * std::vector.
  334. */
  335. template <typename ConstBufferSequence>
  336. std::size_t send(const ConstBufferSequence& buffers,
  337. socket_base::message_flags flags)
  338. {
  339. boost::system::error_code ec;
  340. std::size_t s = this->impl_.get_service().send(
  341. this->impl_.get_implementation(), buffers, flags, ec);
  342. boost::asio::detail::throw_error(ec, "send");
  343. return s;
  344. }
  345. /// Send some data on the socket.
  346. /**
  347. * This function is used to send data on the sequenced packet socket. The
  348. * function call will block the data has been sent successfully, or an until
  349. * error occurs.
  350. *
  351. * @param buffers One or more data buffers to be sent on the socket.
  352. *
  353. * @param flags Flags specifying how the send call is to be made.
  354. *
  355. * @param ec Set to indicate what error occurred, if any.
  356. *
  357. * @returns The number of bytes sent. Returns 0 if an error occurred.
  358. *
  359. * @note The send operation may not transmit all of the data to the peer.
  360. * Consider using the @ref write function if you need to ensure that all data
  361. * is written before the blocking operation completes.
  362. */
  363. template <typename ConstBufferSequence>
  364. std::size_t send(const ConstBufferSequence& buffers,
  365. socket_base::message_flags flags, boost::system::error_code& ec)
  366. {
  367. return this->impl_.get_service().send(
  368. this->impl_.get_implementation(), buffers, flags, ec);
  369. }
  370. /// Start an asynchronous send.
  371. /**
  372. * This function is used to asynchronously send data on the sequenced packet
  373. * socket. The function call always returns immediately.
  374. *
  375. * @param buffers One or more data buffers to be sent on the socket. Although
  376. * the buffers object may be copied as necessary, ownership of the underlying
  377. * memory blocks is retained by the caller, which must guarantee that they
  378. * remain valid until the handler is called.
  379. *
  380. * @param flags Flags specifying how the send call is to be made.
  381. *
  382. * @param handler The handler to be called when the send operation completes.
  383. * Copies will be made of the handler as required. The function signature of
  384. * the handler must be:
  385. * @code void handler(
  386. * const boost::system::error_code& error, // Result of operation.
  387. * std::size_t bytes_transferred // Number of bytes sent.
  388. * ); @endcode
  389. * Regardless of whether the asynchronous operation completes immediately or
  390. * not, the handler will not be invoked from within this function. On
  391. * immediate completion, invocation of the handler will be performed in a
  392. * manner equivalent to using boost::asio::post().
  393. *
  394. * @par Example
  395. * To send a single data buffer use the @ref buffer function as follows:
  396. * @code
  397. * socket.async_send(boost::asio::buffer(data, size), 0, handler);
  398. * @endcode
  399. * See the @ref buffer documentation for information on sending multiple
  400. * buffers in one go, and how to use it with arrays, boost::array or
  401. * std::vector.
  402. */
  403. template <typename ConstBufferSequence, typename WriteHandler>
  404. BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
  405. void (boost::system::error_code, std::size_t))
  406. async_send(const ConstBufferSequence& buffers,
  407. socket_base::message_flags flags,
  408. BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
  409. {
  410. return async_initiate<WriteHandler,
  411. void (boost::system::error_code, std::size_t)>(
  412. initiate_async_send(), handler, this, buffers, flags);
  413. }
  414. /// Receive some data on the socket.
  415. /**
  416. * This function is used to receive data on the sequenced packet socket. The
  417. * function call will block until data has been received successfully, or
  418. * until an error occurs.
  419. *
  420. * @param buffers One or more buffers into which the data will be received.
  421. *
  422. * @param out_flags After the receive call completes, contains flags
  423. * associated with the received data. For example, if the
  424. * socket_base::message_end_of_record bit is set then the received data marks
  425. * the end of a record.
  426. *
  427. * @returns The number of bytes received.
  428. *
  429. * @throws boost::system::system_error Thrown on failure. An error code of
  430. * boost::asio::error::eof indicates that the connection was closed by the
  431. * peer.
  432. *
  433. * @par Example
  434. * To receive into a single data buffer use the @ref buffer function as
  435. * follows:
  436. * @code
  437. * socket.receive(boost::asio::buffer(data, size), out_flags);
  438. * @endcode
  439. * See the @ref buffer documentation for information on receiving into
  440. * multiple buffers in one go, and how to use it with arrays, boost::array or
  441. * std::vector.
  442. */
  443. template <typename MutableBufferSequence>
  444. std::size_t receive(const MutableBufferSequence& buffers,
  445. socket_base::message_flags& out_flags)
  446. {
  447. boost::system::error_code ec;
  448. std::size_t s = this->impl_.get_service().receive_with_flags(
  449. this->impl_.get_implementation(), buffers, 0, out_flags, ec);
  450. boost::asio::detail::throw_error(ec, "receive");
  451. return s;
  452. }
  453. /// Receive some data on the socket.
  454. /**
  455. * This function is used to receive data on the sequenced packet socket. The
  456. * function call will block until data has been received successfully, or
  457. * until an error occurs.
  458. *
  459. * @param buffers One or more buffers into which the data will be received.
  460. *
  461. * @param in_flags Flags specifying how the receive call is to be made.
  462. *
  463. * @param out_flags After the receive call completes, contains flags
  464. * associated with the received data. For example, if the
  465. * socket_base::message_end_of_record bit is set then the received data marks
  466. * the end of a record.
  467. *
  468. * @returns The number of bytes received.
  469. *
  470. * @throws boost::system::system_error Thrown on failure. An error code of
  471. * boost::asio::error::eof indicates that the connection was closed by the
  472. * peer.
  473. *
  474. * @note The receive operation may not receive all of the requested number of
  475. * bytes. Consider using the @ref read function if you need to ensure that the
  476. * requested amount of data is read before the blocking operation completes.
  477. *
  478. * @par Example
  479. * To receive into a single data buffer use the @ref buffer function as
  480. * follows:
  481. * @code
  482. * socket.receive(boost::asio::buffer(data, size), 0, out_flags);
  483. * @endcode
  484. * See the @ref buffer documentation for information on receiving into
  485. * multiple buffers in one go, and how to use it with arrays, boost::array or
  486. * std::vector.
  487. */
  488. template <typename MutableBufferSequence>
  489. std::size_t receive(const MutableBufferSequence& buffers,
  490. socket_base::message_flags in_flags,
  491. socket_base::message_flags& out_flags)
  492. {
  493. boost::system::error_code ec;
  494. std::size_t s = this->impl_.get_service().receive_with_flags(
  495. this->impl_.get_implementation(), buffers, in_flags, out_flags, ec);
  496. boost::asio::detail::throw_error(ec, "receive");
  497. return s;
  498. }
  499. /// Receive some data on a connected socket.
  500. /**
  501. * This function is used to receive data on the sequenced packet socket. The
  502. * function call will block until data has been received successfully, or
  503. * until an error occurs.
  504. *
  505. * @param buffers One or more buffers into which the data will be received.
  506. *
  507. * @param in_flags Flags specifying how the receive call is to be made.
  508. *
  509. * @param out_flags After the receive call completes, contains flags
  510. * associated with the received data. For example, if the
  511. * socket_base::message_end_of_record bit is set then the received data marks
  512. * the end of a record.
  513. *
  514. * @param ec Set to indicate what error occurred, if any.
  515. *
  516. * @returns The number of bytes received. Returns 0 if an error occurred.
  517. *
  518. * @note The receive operation may not receive all of the requested number of
  519. * bytes. Consider using the @ref read function if you need to ensure that the
  520. * requested amount of data is read before the blocking operation completes.
  521. */
  522. template <typename MutableBufferSequence>
  523. std::size_t receive(const MutableBufferSequence& buffers,
  524. socket_base::message_flags in_flags,
  525. socket_base::message_flags& out_flags, boost::system::error_code& ec)
  526. {
  527. return this->impl_.get_service().receive_with_flags(
  528. this->impl_.get_implementation(), buffers, in_flags, out_flags, ec);
  529. }
  530. /// Start an asynchronous receive.
  531. /**
  532. * This function is used to asynchronously receive data from the sequenced
  533. * packet socket. The function call always returns immediately.
  534. *
  535. * @param buffers One or more buffers into which the data will be received.
  536. * Although the buffers object may be copied as necessary, ownership of the
  537. * underlying memory blocks is retained by the caller, which must guarantee
  538. * that they remain valid until the handler is called.
  539. *
  540. * @param out_flags Once the asynchronous operation completes, contains flags
  541. * associated with the received data. For example, if the
  542. * socket_base::message_end_of_record bit is set then the received data marks
  543. * the end of a record. The caller must guarantee that the referenced
  544. * variable remains valid until the handler is called.
  545. *
  546. * @param handler The handler to be called when the receive operation
  547. * completes. Copies will be made of the handler as required. The function
  548. * signature of the handler must be:
  549. * @code void handler(
  550. * const boost::system::error_code& error, // Result of operation.
  551. * std::size_t bytes_transferred // Number of bytes received.
  552. * ); @endcode
  553. * Regardless of whether the asynchronous operation completes immediately or
  554. * not, the handler will not be invoked from within this function. On
  555. * immediate completion, invocation of the handler will be performed in a
  556. * manner equivalent to using boost::asio::post().
  557. *
  558. * @par Example
  559. * To receive into a single data buffer use the @ref buffer function as
  560. * follows:
  561. * @code
  562. * socket.async_receive(boost::asio::buffer(data, size), out_flags, handler);
  563. * @endcode
  564. * See the @ref buffer documentation for information on receiving into
  565. * multiple buffers in one go, and how to use it with arrays, boost::array or
  566. * std::vector.
  567. */
  568. template <typename MutableBufferSequence, typename ReadHandler>
  569. BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
  570. void (boost::system::error_code, std::size_t))
  571. async_receive(const MutableBufferSequence& buffers,
  572. socket_base::message_flags& out_flags,
  573. BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
  574. {
  575. return async_initiate<ReadHandler,
  576. void (boost::system::error_code, std::size_t)>(
  577. initiate_async_receive_with_flags(), handler, this,
  578. buffers, socket_base::message_flags(0), &out_flags);
  579. }
  580. /// Start an asynchronous receive.
  581. /**
  582. * This function is used to asynchronously receive data from the sequenced
  583. * data socket. The function call always returns immediately.
  584. *
  585. * @param buffers One or more buffers into which the data will be received.
  586. * Although the buffers object may be copied as necessary, ownership of the
  587. * underlying memory blocks is retained by the caller, which must guarantee
  588. * that they remain valid until the handler is called.
  589. *
  590. * @param in_flags Flags specifying how the receive call is to be made.
  591. *
  592. * @param out_flags Once the asynchronous operation completes, contains flags
  593. * associated with the received data. For example, if the
  594. * socket_base::message_end_of_record bit is set then the received data marks
  595. * the end of a record. The caller must guarantee that the referenced
  596. * variable remains valid until the handler is called.
  597. *
  598. * @param handler The handler to be called when the receive operation
  599. * completes. Copies will be made of the handler as required. The function
  600. * signature of the handler must be:
  601. * @code void handler(
  602. * const boost::system::error_code& error, // Result of operation.
  603. * std::size_t bytes_transferred // Number of bytes received.
  604. * ); @endcode
  605. * Regardless of whether the asynchronous operation completes immediately or
  606. * not, the handler will not be invoked from within this function. On
  607. * immediate completion, invocation of the handler will be performed in a
  608. * manner equivalent to using boost::asio::post().
  609. *
  610. * @par Example
  611. * To receive into a single data buffer use the @ref buffer function as
  612. * follows:
  613. * @code
  614. * socket.async_receive(
  615. * boost::asio::buffer(data, size),
  616. * 0, out_flags, handler);
  617. * @endcode
  618. * See the @ref buffer documentation for information on receiving into
  619. * multiple buffers in one go, and how to use it with arrays, boost::array or
  620. * std::vector.
  621. */
  622. template <typename MutableBufferSequence, typename ReadHandler>
  623. BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
  624. void (boost::system::error_code, std::size_t))
  625. async_receive(const MutableBufferSequence& buffers,
  626. socket_base::message_flags in_flags,
  627. socket_base::message_flags& out_flags,
  628. BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
  629. {
  630. return async_initiate<ReadHandler,
  631. void (boost::system::error_code, std::size_t)>(
  632. initiate_async_receive_with_flags(), handler,
  633. this, buffers, in_flags, &out_flags);
  634. }
  635. private:
  636. struct initiate_async_send
  637. {
  638. template <typename WriteHandler, typename ConstBufferSequence>
  639. void operator()(BOOST_ASIO_MOVE_ARG(WriteHandler) handler,
  640. basic_seq_packet_socket* self, const ConstBufferSequence& buffers,
  641. socket_base::message_flags flags) const
  642. {
  643. // If you get an error on the following line it means that your handler
  644. // does not meet the documented type requirements for a WriteHandler.
  645. BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
  646. detail::non_const_lvalue<WriteHandler> handler2(handler);
  647. self->impl_.get_service().async_send(
  648. self->impl_.get_implementation(), buffers, flags,
  649. handler2.value, self->impl_.get_implementation_executor());
  650. }
  651. };
  652. struct initiate_async_receive_with_flags
  653. {
  654. template <typename ReadHandler, typename MutableBufferSequence>
  655. void operator()(BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
  656. basic_seq_packet_socket* self, const MutableBufferSequence& buffers,
  657. socket_base::message_flags in_flags,
  658. socket_base::message_flags* out_flags) const
  659. {
  660. // If you get an error on the following line it means that your handler
  661. // does not meet the documented type requirements for a ReadHandler.
  662. BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
  663. detail::non_const_lvalue<ReadHandler> handler2(handler);
  664. self->impl_.get_service().async_receive_with_flags(
  665. self->impl_.get_implementation(), buffers, in_flags, *out_flags,
  666. handler2.value, self->impl_.get_implementation_executor());
  667. }
  668. };
  669. };
  670. } // namespace asio
  671. } // namespace boost
  672. #include <boost/asio/detail/pop_options.hpp>
  673. #endif // BOOST_ASIO_BASIC_SEQ_PACKET_SOCKET_HPP