basic_seq_packet_socket.hpp 28 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758
  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) BOOST_ASIO_NOEXCEPT
  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,
  404. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  405. std::size_t)) WriteHandler
  406. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
  407. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(WriteHandler,
  408. void (boost::system::error_code, std::size_t))
  409. async_send(const ConstBufferSequence& buffers,
  410. socket_base::message_flags flags,
  411. BOOST_ASIO_MOVE_ARG(WriteHandler) handler
  412. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
  413. {
  414. return async_initiate<WriteHandler,
  415. void (boost::system::error_code, std::size_t)>(
  416. initiate_async_send(this), handler, buffers, flags);
  417. }
  418. /// Receive some data on the socket.
  419. /**
  420. * This function is used to receive data on the sequenced packet socket. The
  421. * function call will block until data has been received successfully, or
  422. * until an error occurs.
  423. *
  424. * @param buffers One or more buffers into which the data will be received.
  425. *
  426. * @param out_flags After the receive call completes, contains flags
  427. * associated with the received data. For example, if the
  428. * socket_base::message_end_of_record bit is set then the received data marks
  429. * the end of a record.
  430. *
  431. * @returns The number of bytes received.
  432. *
  433. * @throws boost::system::system_error Thrown on failure. An error code of
  434. * boost::asio::error::eof indicates that the connection was closed by the
  435. * peer.
  436. *
  437. * @par Example
  438. * To receive into a single data buffer use the @ref buffer function as
  439. * follows:
  440. * @code
  441. * socket.receive(boost::asio::buffer(data, size), out_flags);
  442. * @endcode
  443. * See the @ref buffer documentation for information on receiving into
  444. * multiple buffers in one go, and how to use it with arrays, boost::array or
  445. * std::vector.
  446. */
  447. template <typename MutableBufferSequence>
  448. std::size_t receive(const MutableBufferSequence& buffers,
  449. socket_base::message_flags& out_flags)
  450. {
  451. boost::system::error_code ec;
  452. std::size_t s = this->impl_.get_service().receive_with_flags(
  453. this->impl_.get_implementation(), buffers, 0, out_flags, ec);
  454. boost::asio::detail::throw_error(ec, "receive");
  455. return s;
  456. }
  457. /// Receive some data on the socket.
  458. /**
  459. * This function is used to receive data on the sequenced packet socket. The
  460. * function call will block until data has been received successfully, or
  461. * until an error occurs.
  462. *
  463. * @param buffers One or more buffers into which the data will be received.
  464. *
  465. * @param in_flags Flags specifying how the receive call is to be made.
  466. *
  467. * @param out_flags After the receive call completes, contains flags
  468. * associated with the received data. For example, if the
  469. * socket_base::message_end_of_record bit is set then the received data marks
  470. * the end of a record.
  471. *
  472. * @returns The number of bytes received.
  473. *
  474. * @throws boost::system::system_error Thrown on failure. An error code of
  475. * boost::asio::error::eof indicates that the connection was closed by the
  476. * peer.
  477. *
  478. * @note The receive operation may not receive all of the requested number of
  479. * bytes. Consider using the @ref read function if you need to ensure that the
  480. * requested amount of data is read before the blocking operation completes.
  481. *
  482. * @par Example
  483. * To receive into a single data buffer use the @ref buffer function as
  484. * follows:
  485. * @code
  486. * socket.receive(boost::asio::buffer(data, size), 0, out_flags);
  487. * @endcode
  488. * See the @ref buffer documentation for information on receiving into
  489. * multiple buffers in one go, and how to use it with arrays, boost::array or
  490. * std::vector.
  491. */
  492. template <typename MutableBufferSequence>
  493. std::size_t receive(const MutableBufferSequence& buffers,
  494. socket_base::message_flags in_flags,
  495. socket_base::message_flags& out_flags)
  496. {
  497. boost::system::error_code ec;
  498. std::size_t s = this->impl_.get_service().receive_with_flags(
  499. this->impl_.get_implementation(), buffers, in_flags, out_flags, ec);
  500. boost::asio::detail::throw_error(ec, "receive");
  501. return s;
  502. }
  503. /// Receive some data on a connected socket.
  504. /**
  505. * This function is used to receive data on the sequenced packet socket. The
  506. * function call will block until data has been received successfully, or
  507. * until an error occurs.
  508. *
  509. * @param buffers One or more buffers into which the data will be received.
  510. *
  511. * @param in_flags Flags specifying how the receive call is to be made.
  512. *
  513. * @param out_flags After the receive call completes, contains flags
  514. * associated with the received data. For example, if the
  515. * socket_base::message_end_of_record bit is set then the received data marks
  516. * the end of a record.
  517. *
  518. * @param ec Set to indicate what error occurred, if any.
  519. *
  520. * @returns The number of bytes received. Returns 0 if an error occurred.
  521. *
  522. * @note The receive operation may not receive all of the requested number of
  523. * bytes. Consider using the @ref read function if you need to ensure that the
  524. * requested amount of data is read before the blocking operation completes.
  525. */
  526. template <typename MutableBufferSequence>
  527. std::size_t receive(const MutableBufferSequence& buffers,
  528. socket_base::message_flags in_flags,
  529. socket_base::message_flags& out_flags, boost::system::error_code& ec)
  530. {
  531. return this->impl_.get_service().receive_with_flags(
  532. this->impl_.get_implementation(), buffers, in_flags, out_flags, ec);
  533. }
  534. /// Start an asynchronous receive.
  535. /**
  536. * This function is used to asynchronously receive data from the sequenced
  537. * packet socket. The function call always returns immediately.
  538. *
  539. * @param buffers One or more buffers into which the data will be received.
  540. * Although the buffers object may be copied as necessary, ownership of the
  541. * underlying memory blocks is retained by the caller, which must guarantee
  542. * that they remain valid until the handler is called.
  543. *
  544. * @param out_flags Once the asynchronous operation completes, contains flags
  545. * associated with the received data. For example, if the
  546. * socket_base::message_end_of_record bit is set then the received data marks
  547. * the end of a record. The caller must guarantee that the referenced
  548. * variable remains valid until the handler is called.
  549. *
  550. * @param handler The handler to be called when the receive operation
  551. * completes. Copies will be made of the handler as required. The function
  552. * signature of the handler must be:
  553. * @code void handler(
  554. * const boost::system::error_code& error, // Result of operation.
  555. * std::size_t bytes_transferred // Number of bytes received.
  556. * ); @endcode
  557. * Regardless of whether the asynchronous operation completes immediately or
  558. * not, the handler will not be invoked from within this function. On
  559. * immediate completion, invocation of the handler will be performed in a
  560. * manner equivalent to using boost::asio::post().
  561. *
  562. * @par Example
  563. * To receive into a single data buffer use the @ref buffer function as
  564. * follows:
  565. * @code
  566. * socket.async_receive(boost::asio::buffer(data, size), out_flags, handler);
  567. * @endcode
  568. * See the @ref buffer documentation for information on receiving into
  569. * multiple buffers in one go, and how to use it with arrays, boost::array or
  570. * std::vector.
  571. */
  572. template <typename MutableBufferSequence,
  573. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  574. std::size_t)) ReadHandler
  575. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
  576. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
  577. void (boost::system::error_code, std::size_t))
  578. async_receive(const MutableBufferSequence& buffers,
  579. socket_base::message_flags& out_flags,
  580. BOOST_ASIO_MOVE_ARG(ReadHandler) handler
  581. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
  582. {
  583. return async_initiate<ReadHandler,
  584. void (boost::system::error_code, std::size_t)>(
  585. initiate_async_receive_with_flags(this), handler,
  586. buffers, socket_base::message_flags(0), &out_flags);
  587. }
  588. /// Start an asynchronous receive.
  589. /**
  590. * This function is used to asynchronously receive data from the sequenced
  591. * data socket. The function call always returns immediately.
  592. *
  593. * @param buffers One or more buffers into which the data will be received.
  594. * Although the buffers object may be copied as necessary, ownership of the
  595. * underlying memory blocks is retained by the caller, which must guarantee
  596. * that they remain valid until the handler is called.
  597. *
  598. * @param in_flags Flags specifying how the receive call is to be made.
  599. *
  600. * @param out_flags Once the asynchronous operation completes, contains flags
  601. * associated with the received data. For example, if the
  602. * socket_base::message_end_of_record bit is set then the received data marks
  603. * the end of a record. The caller must guarantee that the referenced
  604. * variable remains valid until the handler is called.
  605. *
  606. * @param handler The handler to be called when the receive operation
  607. * completes. Copies will be made of the handler as required. The function
  608. * signature of the handler must be:
  609. * @code void handler(
  610. * const boost::system::error_code& error, // Result of operation.
  611. * std::size_t bytes_transferred // Number of bytes received.
  612. * ); @endcode
  613. * Regardless of whether the asynchronous operation completes immediately or
  614. * not, the handler will not be invoked from within this function. On
  615. * immediate completion, invocation of the handler will be performed in a
  616. * manner equivalent to using boost::asio::post().
  617. *
  618. * @par Example
  619. * To receive into a single data buffer use the @ref buffer function as
  620. * follows:
  621. * @code
  622. * socket.async_receive(
  623. * boost::asio::buffer(data, size),
  624. * 0, out_flags, handler);
  625. * @endcode
  626. * See the @ref buffer documentation for information on receiving into
  627. * multiple buffers in one go, and how to use it with arrays, boost::array or
  628. * std::vector.
  629. */
  630. template <typename MutableBufferSequence,
  631. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  632. std::size_t)) ReadHandler
  633. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
  634. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ReadHandler,
  635. void (boost::system::error_code, std::size_t))
  636. async_receive(const MutableBufferSequence& buffers,
  637. socket_base::message_flags in_flags,
  638. socket_base::message_flags& out_flags,
  639. BOOST_ASIO_MOVE_ARG(ReadHandler) handler
  640. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
  641. {
  642. return async_initiate<ReadHandler,
  643. void (boost::system::error_code, std::size_t)>(
  644. initiate_async_receive_with_flags(this),
  645. handler, buffers, in_flags, &out_flags);
  646. }
  647. private:
  648. class initiate_async_send
  649. {
  650. public:
  651. typedef Executor executor_type;
  652. explicit initiate_async_send(basic_seq_packet_socket* self)
  653. : self_(self)
  654. {
  655. }
  656. executor_type get_executor() const BOOST_ASIO_NOEXCEPT
  657. {
  658. return self_->get_executor();
  659. }
  660. template <typename WriteHandler, typename ConstBufferSequence>
  661. void operator()(BOOST_ASIO_MOVE_ARG(WriteHandler) handler,
  662. const ConstBufferSequence& buffers,
  663. socket_base::message_flags flags) const
  664. {
  665. // If you get an error on the following line it means that your handler
  666. // does not meet the documented type requirements for a WriteHandler.
  667. BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
  668. detail::non_const_lvalue<WriteHandler> handler2(handler);
  669. self_->impl_.get_service().async_send(
  670. self_->impl_.get_implementation(), buffers, flags,
  671. handler2.value, self_->impl_.get_implementation_executor());
  672. }
  673. private:
  674. basic_seq_packet_socket* self_;
  675. };
  676. class initiate_async_receive_with_flags
  677. {
  678. public:
  679. typedef Executor executor_type;
  680. explicit initiate_async_receive_with_flags(basic_seq_packet_socket* self)
  681. : self_(self)
  682. {
  683. }
  684. executor_type get_executor() const BOOST_ASIO_NOEXCEPT
  685. {
  686. return self_->get_executor();
  687. }
  688. template <typename ReadHandler, typename MutableBufferSequence>
  689. void operator()(BOOST_ASIO_MOVE_ARG(ReadHandler) handler,
  690. const MutableBufferSequence& buffers,
  691. socket_base::message_flags in_flags,
  692. socket_base::message_flags* out_flags) const
  693. {
  694. // If you get an error on the following line it means that your handler
  695. // does not meet the documented type requirements for a ReadHandler.
  696. BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
  697. detail::non_const_lvalue<ReadHandler> handler2(handler);
  698. self_->impl_.get_service().async_receive_with_flags(
  699. self_->impl_.get_implementation(), buffers, in_flags, *out_flags,
  700. handler2.value, self_->impl_.get_implementation_executor());
  701. }
  702. private:
  703. basic_seq_packet_socket* self_;
  704. };
  705. };
  706. } // namespace asio
  707. } // namespace boost
  708. #include <boost/asio/detail/pop_options.hpp>
  709. #endif // BOOST_ASIO_BASIC_SEQ_PACKET_SOCKET_HPP