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

http://hadesmem.googlecode.com/ · C++ Header · 888 lines · 241 code · 46 blank · 601 comment · 2 complexity · 83775706ce1a157fa3e4bce93a9bbce5 MD5 · raw file

  1. //
  2. // basic_datagram_socket.hpp
  3. // ~~~~~~~~~~~~~~~~~~~~~~~~~
  4. //
  5. // Copyright (c) 2003-2011 Christopher M. Kohlhoff (chris at kohlhoff dot com)
  6. //
  7. // Distributed under the Boost Software License, Version 1.0. (See accompanying
  8. // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
  9. //
  10. #ifndef BOOST_ASIO_BASIC_DATAGRAM_SOCKET_HPP
  11. #define BOOST_ASIO_BASIC_DATAGRAM_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/datagram_socket_service.hpp>
  19. #include <boost/asio/detail/handler_type_requirements.hpp>
  20. #include <boost/asio/detail/throw_error.hpp>
  21. #include <boost/asio/error.hpp>
  22. #include <boost/asio/detail/push_options.hpp>
  23. namespace boost {
  24. namespace asio {
  25. /// Provides datagram-oriented socket functionality.
  26. /**
  27. * The basic_datagram_socket class template provides asynchronous and blocking
  28. * datagram-oriented socket functionality.
  29. *
  30. * @par Thread Safety
  31. * @e Distinct @e objects: Safe.@n
  32. * @e Shared @e objects: Unsafe.
  33. */
  34. template <typename Protocol,
  35. typename DatagramSocketService = datagram_socket_service<Protocol> >
  36. class basic_datagram_socket
  37. : public basic_socket<Protocol, DatagramSocketService>
  38. {
  39. public:
  40. /// (Deprecated: Use native_handle_type.) The native representation of a
  41. /// socket.
  42. typedef typename DatagramSocketService::native_handle_type native_type;
  43. /// The native representation of a socket.
  44. typedef typename DatagramSocketService::native_handle_type native_handle_type;
  45. /// The protocol type.
  46. typedef Protocol protocol_type;
  47. /// The endpoint type.
  48. typedef typename Protocol::endpoint endpoint_type;
  49. /// Construct a basic_datagram_socket without opening it.
  50. /**
  51. * This constructor creates a datagram socket without opening it. The open()
  52. * function must be called before data can be sent or received on the socket.
  53. *
  54. * @param io_service The io_service object that the datagram socket will use
  55. * to dispatch handlers for any asynchronous operations performed on the
  56. * socket.
  57. */
  58. explicit basic_datagram_socket(boost::asio::io_service& io_service)
  59. : basic_socket<Protocol, DatagramSocketService>(io_service)
  60. {
  61. }
  62. /// Construct and open a basic_datagram_socket.
  63. /**
  64. * This constructor creates and opens a datagram socket.
  65. *
  66. * @param io_service The io_service object that the datagram socket will use
  67. * to dispatch handlers for any asynchronous operations performed on the
  68. * socket.
  69. *
  70. * @param protocol An object specifying protocol parameters to be used.
  71. *
  72. * @throws boost::system::system_error Thrown on failure.
  73. */
  74. basic_datagram_socket(boost::asio::io_service& io_service,
  75. const protocol_type& protocol)
  76. : basic_socket<Protocol, DatagramSocketService>(io_service, protocol)
  77. {
  78. }
  79. /// Construct a basic_datagram_socket, opening it and binding it to the given
  80. /// local endpoint.
  81. /**
  82. * This constructor creates a datagram socket and automatically opens it bound
  83. * to the specified endpoint on the local machine. The protocol used is the
  84. * protocol associated with the given endpoint.
  85. *
  86. * @param io_service The io_service object that the datagram socket will use
  87. * to dispatch handlers for any asynchronous operations performed on the
  88. * socket.
  89. *
  90. * @param endpoint An endpoint on the local machine to which the datagram
  91. * socket will be bound.
  92. *
  93. * @throws boost::system::system_error Thrown on failure.
  94. */
  95. basic_datagram_socket(boost::asio::io_service& io_service,
  96. const endpoint_type& endpoint)
  97. : basic_socket<Protocol, DatagramSocketService>(io_service, endpoint)
  98. {
  99. }
  100. /// Construct a basic_datagram_socket on an existing native socket.
  101. /**
  102. * This constructor creates a datagram socket object to hold an existing
  103. * native socket.
  104. *
  105. * @param io_service The io_service object that the datagram socket will use
  106. * to dispatch handlers for any asynchronous operations performed on the
  107. * socket.
  108. *
  109. * @param protocol An object specifying protocol parameters to be used.
  110. *
  111. * @param native_socket The new underlying socket implementation.
  112. *
  113. * @throws boost::system::system_error Thrown on failure.
  114. */
  115. basic_datagram_socket(boost::asio::io_service& io_service,
  116. const protocol_type& protocol, const native_handle_type& native_socket)
  117. : basic_socket<Protocol, DatagramSocketService>(
  118. io_service, protocol, native_socket)
  119. {
  120. }
  121. #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  122. /// Move-construct a basic_datagram_socket from another.
  123. /**
  124. * This constructor moves a datagram socket from one object to another.
  125. *
  126. * @param other The other basic_datagram_socket object from which the move
  127. * will occur.
  128. *
  129. * @note Following the move, the moved-from object is in the same state as if
  130. * constructed using the @c basic_datagram_socket(io_service&) constructor.
  131. */
  132. basic_datagram_socket(basic_datagram_socket&& other)
  133. : basic_socket<Protocol, DatagramSocketService>(
  134. BOOST_ASIO_MOVE_CAST(basic_datagram_socket)(other))
  135. {
  136. }
  137. /// Move-assign a basic_datagram_socket from another.
  138. /**
  139. * This assignment operator moves a datagram socket from one object to
  140. * another.
  141. *
  142. * @param other The other basic_datagram_socket object from which the move
  143. * will occur.
  144. *
  145. * @note Following the move, the moved-from object is in the same state as if
  146. * constructed using the @c basic_datagram_socket(io_service&) constructor.
  147. */
  148. basic_datagram_socket& operator=(basic_datagram_socket&& other)
  149. {
  150. basic_socket<Protocol, DatagramSocketService>::operator=(
  151. BOOST_ASIO_MOVE_CAST(basic_datagram_socket)(other));
  152. return *this;
  153. }
  154. #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
  155. /// Send some data on a connected socket.
  156. /**
  157. * This function is used to send data on the datagram socket. The function
  158. * call will block until the data has been sent successfully or an error
  159. * occurs.
  160. *
  161. * @param buffers One ore more data buffers to be sent on the socket.
  162. *
  163. * @returns The number of bytes sent.
  164. *
  165. * @throws boost::system::system_error Thrown on failure.
  166. *
  167. * @note The send operation can only be used with a connected socket. Use
  168. * the send_to function to send data on an unconnected datagram socket.
  169. *
  170. * @par Example
  171. * To send a single data buffer use the @ref buffer function as follows:
  172. * @code socket.send(boost::asio::buffer(data, size)); @endcode
  173. * See the @ref buffer documentation for information on sending multiple
  174. * buffers in one go, and how to use it with arrays, boost::array or
  175. * std::vector.
  176. */
  177. template <typename ConstBufferSequence>
  178. std::size_t send(const ConstBufferSequence& buffers)
  179. {
  180. boost::system::error_code ec;
  181. std::size_t s = this->get_service().send(
  182. this->get_implementation(), buffers, 0, ec);
  183. boost::asio::detail::throw_error(ec, "send");
  184. return s;
  185. }
  186. /// Send some data on a connected socket.
  187. /**
  188. * This function is used to send data on the datagram socket. The function
  189. * call will block until the data has been sent successfully or an error
  190. * occurs.
  191. *
  192. * @param buffers One ore more data buffers to be sent on the socket.
  193. *
  194. * @param flags Flags specifying how the send call is to be made.
  195. *
  196. * @returns The number of bytes sent.
  197. *
  198. * @throws boost::system::system_error Thrown on failure.
  199. *
  200. * @note The send operation can only be used with a connected socket. Use
  201. * the send_to function to send data on an unconnected datagram socket.
  202. */
  203. template <typename ConstBufferSequence>
  204. std::size_t send(const ConstBufferSequence& buffers,
  205. socket_base::message_flags flags)
  206. {
  207. boost::system::error_code ec;
  208. std::size_t s = this->get_service().send(
  209. this->get_implementation(), buffers, flags, ec);
  210. boost::asio::detail::throw_error(ec, "send");
  211. return s;
  212. }
  213. /// Send some data on a connected socket.
  214. /**
  215. * This function is used to send data on the datagram socket. The function
  216. * call will block until the data has been sent successfully or an error
  217. * occurs.
  218. *
  219. * @param buffers One or more data buffers to be sent on the socket.
  220. *
  221. * @param flags Flags specifying how the send call is to be made.
  222. *
  223. * @param ec Set to indicate what error occurred, if any.
  224. *
  225. * @returns The number of bytes sent.
  226. *
  227. * @note The send operation can only be used with a connected socket. Use
  228. * the send_to function to send data on an unconnected datagram socket.
  229. */
  230. template <typename ConstBufferSequence>
  231. std::size_t send(const ConstBufferSequence& buffers,
  232. socket_base::message_flags flags, boost::system::error_code& ec)
  233. {
  234. return this->get_service().send(
  235. this->get_implementation(), buffers, flags, ec);
  236. }
  237. /// Start an asynchronous send on a connected socket.
  238. /**
  239. * This function is used to send data on the datagram socket. The function
  240. * call will block until the data has been sent successfully or an error
  241. * occurs.
  242. *
  243. * @param buffers One or more data buffers to be sent on the socket. Although
  244. * the buffers object may be copied as necessary, ownership of the underlying
  245. * memory blocks is retained by the caller, which must guarantee that they
  246. * remain valid until the handler is called.
  247. *
  248. * @param handler The handler to be called when the send operation completes.
  249. * Copies will be made of the handler as required. The function signature of
  250. * the handler must be:
  251. * @code void handler(
  252. * const boost::system::error_code& error, // Result of operation.
  253. * std::size_t bytes_transferred // Number of bytes sent.
  254. * ); @endcode
  255. * Regardless of whether the asynchronous operation completes immediately or
  256. * not, the handler will not be invoked from within this function. Invocation
  257. * of the handler will be performed in a manner equivalent to using
  258. * boost::asio::io_service::post().
  259. *
  260. * @note The async_send operation can only be used with a connected socket.
  261. * Use the async_send_to function to send data on an unconnected datagram
  262. * socket.
  263. *
  264. * @par Example
  265. * To send a single data buffer use the @ref buffer function as follows:
  266. * @code
  267. * socket.async_send(boost::asio::buffer(data, size), handler);
  268. * @endcode
  269. * See the @ref buffer documentation for information on sending multiple
  270. * buffers in one go, and how to use it with arrays, boost::array or
  271. * std::vector.
  272. */
  273. template <typename ConstBufferSequence, typename WriteHandler>
  274. void async_send(const ConstBufferSequence& buffers,
  275. BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
  276. {
  277. // If you get an error on the following line it means that your handler does
  278. // not meet the documented type requirements for a WriteHandler.
  279. BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
  280. this->get_service().async_send(this->get_implementation(),
  281. buffers, 0, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
  282. }
  283. /// Start an asynchronous send on a connected socket.
  284. /**
  285. * This function is used to send data on the datagram socket. The function
  286. * call will block until the data has been sent successfully or an error
  287. * occurs.
  288. *
  289. * @param buffers One or more data buffers to be sent on the socket. Although
  290. * the buffers object may be copied as necessary, ownership of the underlying
  291. * memory blocks is retained by the caller, which must guarantee that they
  292. * remain valid until the handler is called.
  293. *
  294. * @param flags Flags specifying how the send call is to be made.
  295. *
  296. * @param handler The handler to be called when the send operation completes.
  297. * Copies will be made of the handler as required. The function signature of
  298. * the handler must be:
  299. * @code void handler(
  300. * const boost::system::error_code& error, // Result of operation.
  301. * std::size_t bytes_transferred // Number of bytes sent.
  302. * ); @endcode
  303. * Regardless of whether the asynchronous operation completes immediately or
  304. * not, the handler will not be invoked from within this function. Invocation
  305. * of the handler will be performed in a manner equivalent to using
  306. * boost::asio::io_service::post().
  307. *
  308. * @note The async_send operation can only be used with a connected socket.
  309. * Use the async_send_to function to send data on an unconnected datagram
  310. * socket.
  311. */
  312. template <typename ConstBufferSequence, typename WriteHandler>
  313. void async_send(const ConstBufferSequence& buffers,
  314. socket_base::message_flags flags,
  315. BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
  316. {
  317. // If you get an error on the following line it means that your handler does
  318. // not meet the documented type requirements for a WriteHandler.
  319. BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
  320. this->get_service().async_send(this->get_implementation(),
  321. buffers, flags, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
  322. }
  323. /// Send a datagram to the specified endpoint.
  324. /**
  325. * This function is used to send a datagram to the specified remote endpoint.
  326. * The function call will block until the data has been sent successfully or
  327. * an error occurs.
  328. *
  329. * @param buffers One or more data buffers to be sent to the remote endpoint.
  330. *
  331. * @param destination The remote endpoint to which the data will be sent.
  332. *
  333. * @returns The number of bytes sent.
  334. *
  335. * @throws boost::system::system_error Thrown on failure.
  336. *
  337. * @par Example
  338. * To send a single data buffer use the @ref buffer function as follows:
  339. * @code
  340. * boost::asio::ip::udp::endpoint destination(
  341. * boost::asio::ip::address::from_string("1.2.3.4"), 12345);
  342. * socket.send_to(boost::asio::buffer(data, size), destination);
  343. * @endcode
  344. * See the @ref buffer documentation for information on sending multiple
  345. * buffers in one go, and how to use it with arrays, boost::array or
  346. * std::vector.
  347. */
  348. template <typename ConstBufferSequence>
  349. std::size_t send_to(const ConstBufferSequence& buffers,
  350. const endpoint_type& destination)
  351. {
  352. boost::system::error_code ec;
  353. std::size_t s = this->get_service().send_to(
  354. this->get_implementation(), buffers, destination, 0, ec);
  355. boost::asio::detail::throw_error(ec, "send_to");
  356. return s;
  357. }
  358. /// Send a datagram to the specified endpoint.
  359. /**
  360. * This function is used to send a datagram to the specified remote endpoint.
  361. * The function call will block until the data has been sent successfully or
  362. * an error occurs.
  363. *
  364. * @param buffers One or more data buffers to be sent to the remote endpoint.
  365. *
  366. * @param destination The remote endpoint to which the data will be sent.
  367. *
  368. * @param flags Flags specifying how the send call is to be made.
  369. *
  370. * @returns The number of bytes sent.
  371. *
  372. * @throws boost::system::system_error Thrown on failure.
  373. */
  374. template <typename ConstBufferSequence>
  375. std::size_t send_to(const ConstBufferSequence& buffers,
  376. const endpoint_type& destination, socket_base::message_flags flags)
  377. {
  378. boost::system::error_code ec;
  379. std::size_t s = this->get_service().send_to(
  380. this->get_implementation(), buffers, destination, flags, ec);
  381. boost::asio::detail::throw_error(ec, "send_to");
  382. return s;
  383. }
  384. /// Send a datagram to the specified endpoint.
  385. /**
  386. * This function is used to send a datagram to the specified remote endpoint.
  387. * The function call will block until the data has been sent successfully or
  388. * an error occurs.
  389. *
  390. * @param buffers One or more data buffers to be sent to the remote endpoint.
  391. *
  392. * @param destination The remote endpoint to which the data will be sent.
  393. *
  394. * @param flags Flags specifying how the send call is to be made.
  395. *
  396. * @param ec Set to indicate what error occurred, if any.
  397. *
  398. * @returns The number of bytes sent.
  399. */
  400. template <typename ConstBufferSequence>
  401. std::size_t send_to(const ConstBufferSequence& buffers,
  402. const endpoint_type& destination, socket_base::message_flags flags,
  403. boost::system::error_code& ec)
  404. {
  405. return this->get_service().send_to(this->get_implementation(),
  406. buffers, destination, flags, ec);
  407. }
  408. /// Start an asynchronous send.
  409. /**
  410. * This function is used to asynchronously send a datagram to the specified
  411. * remote endpoint. The function call always returns immediately.
  412. *
  413. * @param buffers One or more data buffers to be sent to the remote endpoint.
  414. * Although the buffers object may be copied as necessary, ownership of the
  415. * underlying memory blocks is retained by the caller, which must guarantee
  416. * that they remain valid until the handler is called.
  417. *
  418. * @param destination The remote endpoint to which the data will be sent.
  419. * Copies will be made of the endpoint as required.
  420. *
  421. * @param handler The handler to be called when the send operation completes.
  422. * Copies will be made of the handler as required. The function signature of
  423. * the handler must be:
  424. * @code void handler(
  425. * const boost::system::error_code& error, // Result of operation.
  426. * std::size_t bytes_transferred // Number of bytes sent.
  427. * ); @endcode
  428. * Regardless of whether the asynchronous operation completes immediately or
  429. * not, the handler will not be invoked from within this function. Invocation
  430. * of the handler will be performed in a manner equivalent to using
  431. * boost::asio::io_service::post().
  432. *
  433. * @par Example
  434. * To send a single data buffer use the @ref buffer function as follows:
  435. * @code
  436. * boost::asio::ip::udp::endpoint destination(
  437. * boost::asio::ip::address::from_string("1.2.3.4"), 12345);
  438. * socket.async_send_to(
  439. * boost::asio::buffer(data, size), destination, handler);
  440. * @endcode
  441. * See the @ref buffer documentation for information on sending multiple
  442. * buffers in one go, and how to use it with arrays, boost::array or
  443. * std::vector.
  444. */
  445. template <typename ConstBufferSequence, typename WriteHandler>
  446. void async_send_to(const ConstBufferSequence& buffers,
  447. const endpoint_type& destination,
  448. BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
  449. {
  450. // If you get an error on the following line it means that your handler does
  451. // not meet the documented type requirements for a WriteHandler.
  452. BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
  453. this->get_service().async_send_to(this->get_implementation(), buffers,
  454. destination, 0, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
  455. }
  456. /// Start an asynchronous send.
  457. /**
  458. * This function is used to asynchronously send a datagram to the specified
  459. * remote endpoint. The function call always returns immediately.
  460. *
  461. * @param buffers One or more data buffers to be sent to the remote endpoint.
  462. * Although the buffers object may be copied as necessary, ownership of the
  463. * underlying memory blocks is retained by the caller, which must guarantee
  464. * that they remain valid until the handler is called.
  465. *
  466. * @param flags Flags specifying how the send call is to be made.
  467. *
  468. * @param destination The remote endpoint to which the data will be sent.
  469. * Copies will be made of the endpoint as required.
  470. *
  471. * @param handler The handler to be called when the send operation completes.
  472. * Copies will be made of the handler as required. The function signature of
  473. * the handler must be:
  474. * @code void handler(
  475. * const boost::system::error_code& error, // Result of operation.
  476. * std::size_t bytes_transferred // Number of bytes sent.
  477. * ); @endcode
  478. * Regardless of whether the asynchronous operation completes immediately or
  479. * not, the handler will not be invoked from within this function. Invocation
  480. * of the handler will be performed in a manner equivalent to using
  481. * boost::asio::io_service::post().
  482. */
  483. template <typename ConstBufferSequence, typename WriteHandler>
  484. void async_send_to(const ConstBufferSequence& buffers,
  485. const endpoint_type& destination, socket_base::message_flags flags,
  486. BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
  487. {
  488. // If you get an error on the following line it means that your handler does
  489. // not meet the documented type requirements for a WriteHandler.
  490. BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
  491. this->get_service().async_send_to(this->get_implementation(), buffers,
  492. destination, flags, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
  493. }
  494. /// Receive some data on a connected socket.
  495. /**
  496. * This function is used to receive data on the datagram socket. The function
  497. * call will block until data has been received successfully or an error
  498. * occurs.
  499. *
  500. * @param buffers One or more buffers into which the data will be received.
  501. *
  502. * @returns The number of bytes received.
  503. *
  504. * @throws boost::system::system_error Thrown on failure.
  505. *
  506. * @note The receive operation can only be used with a connected socket. Use
  507. * the receive_from function to receive data on an unconnected datagram
  508. * socket.
  509. *
  510. * @par Example
  511. * To receive into a single data buffer use the @ref buffer function as
  512. * follows:
  513. * @code socket.receive(boost::asio::buffer(data, size)); @endcode
  514. * See the @ref buffer documentation for information on receiving into
  515. * multiple buffers in one go, and how to use it with arrays, boost::array or
  516. * std::vector.
  517. */
  518. template <typename MutableBufferSequence>
  519. std::size_t receive(const MutableBufferSequence& buffers)
  520. {
  521. boost::system::error_code ec;
  522. std::size_t s = this->get_service().receive(
  523. this->get_implementation(), buffers, 0, ec);
  524. boost::asio::detail::throw_error(ec, "receive");
  525. return s;
  526. }
  527. /// Receive some data on a connected socket.
  528. /**
  529. * This function is used to receive data on the datagram socket. The function
  530. * call will block until data has been received successfully or an error
  531. * occurs.
  532. *
  533. * @param buffers One or more buffers into which the data will be received.
  534. *
  535. * @param flags Flags specifying how the receive call is to be made.
  536. *
  537. * @returns The number of bytes received.
  538. *
  539. * @throws boost::system::system_error Thrown on failure.
  540. *
  541. * @note The receive operation can only be used with a connected socket. Use
  542. * the receive_from function to receive data on an unconnected datagram
  543. * socket.
  544. */
  545. template <typename MutableBufferSequence>
  546. std::size_t receive(const MutableBufferSequence& buffers,
  547. socket_base::message_flags flags)
  548. {
  549. boost::system::error_code ec;
  550. std::size_t s = this->get_service().receive(
  551. this->get_implementation(), buffers, flags, ec);
  552. boost::asio::detail::throw_error(ec, "receive");
  553. return s;
  554. }
  555. /// Receive some data on a connected socket.
  556. /**
  557. * This function is used to receive data on the datagram socket. The function
  558. * call will block until data has been received successfully or an error
  559. * occurs.
  560. *
  561. * @param buffers One or more buffers into which the data will be received.
  562. *
  563. * @param flags Flags specifying how the receive call is to be made.
  564. *
  565. * @param ec Set to indicate what error occurred, if any.
  566. *
  567. * @returns The number of bytes received.
  568. *
  569. * @note The receive operation can only be used with a connected socket. Use
  570. * the receive_from function to receive data on an unconnected datagram
  571. * socket.
  572. */
  573. template <typename MutableBufferSequence>
  574. std::size_t receive(const MutableBufferSequence& buffers,
  575. socket_base::message_flags flags, boost::system::error_code& ec)
  576. {
  577. return this->get_service().receive(
  578. this->get_implementation(), buffers, flags, ec);
  579. }
  580. /// Start an asynchronous receive on a connected socket.
  581. /**
  582. * This function is used to asynchronously receive data from the datagram
  583. * 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 handler The handler to be called when the receive operation
  591. * completes. Copies will be made of the handler as required. The function
  592. * signature of the handler must be:
  593. * @code void handler(
  594. * const boost::system::error_code& error, // Result of operation.
  595. * std::size_t bytes_transferred // Number of bytes received.
  596. * ); @endcode
  597. * Regardless of whether the asynchronous operation completes immediately or
  598. * not, the handler will not be invoked from within this function. Invocation
  599. * of the handler will be performed in a manner equivalent to using
  600. * boost::asio::io_service::post().
  601. *
  602. * @note The async_receive operation can only be used with a connected socket.
  603. * Use the async_receive_from function to receive data on an unconnected
  604. * datagram socket.
  605. *
  606. * @par Example
  607. * To receive into a single data buffer use the @ref buffer function as
  608. * follows:
  609. * @code
  610. * socket.async_receive(boost::asio::buffer(data, size), handler);
  611. * @endcode
  612. * See the @ref buffer documentation for information on receiving into
  613. * multiple buffers in one go, and how to use it with arrays, boost::array or
  614. * std::vector.
  615. */
  616. template <typename MutableBufferSequence, typename ReadHandler>
  617. void async_receive(const MutableBufferSequence& buffers,
  618. BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
  619. {
  620. // If you get an error on the following line it means that your handler does
  621. // not meet the documented type requirements for a ReadHandler.
  622. BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
  623. this->get_service().async_receive(this->get_implementation(),
  624. buffers, 0, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
  625. }
  626. /// Start an asynchronous receive on a connected socket.
  627. /**
  628. * This function is used to asynchronously receive data from the datagram
  629. * socket. The function call always returns immediately.
  630. *
  631. * @param buffers One or more buffers into which the data will be received.
  632. * Although the buffers object may be copied as necessary, ownership of the
  633. * underlying memory blocks is retained by the caller, which must guarantee
  634. * that they remain valid until the handler is called.
  635. *
  636. * @param flags Flags specifying how the receive call is to be made.
  637. *
  638. * @param handler The handler to be called when the receive operation
  639. * completes. Copies will be made of the handler as required. The function
  640. * signature of the handler must be:
  641. * @code void handler(
  642. * const boost::system::error_code& error, // Result of operation.
  643. * std::size_t bytes_transferred // Number of bytes received.
  644. * ); @endcode
  645. * Regardless of whether the asynchronous operation completes immediately or
  646. * not, the handler will not be invoked from within this function. Invocation
  647. * of the handler will be performed in a manner equivalent to using
  648. * boost::asio::io_service::post().
  649. *
  650. * @note The async_receive operation can only be used with a connected socket.
  651. * Use the async_receive_from function to receive data on an unconnected
  652. * datagram socket.
  653. */
  654. template <typename MutableBufferSequence, typename ReadHandler>
  655. void async_receive(const MutableBufferSequence& buffers,
  656. socket_base::message_flags flags,
  657. BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
  658. {
  659. // If you get an error on the following line it means that your handler does
  660. // not meet the documented type requirements for a ReadHandler.
  661. BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
  662. this->get_service().async_receive(this->get_implementation(),
  663. buffers, flags, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
  664. }
  665. /// Receive a datagram with the endpoint of the sender.
  666. /**
  667. * This function is used to receive a datagram. The function call will block
  668. * until data has been received successfully or an error occurs.
  669. *
  670. * @param buffers One or more buffers into which the data will be received.
  671. *
  672. * @param sender_endpoint An endpoint object that receives the endpoint of
  673. * the remote sender of the datagram.
  674. *
  675. * @returns The number of bytes received.
  676. *
  677. * @throws boost::system::system_error Thrown on failure.
  678. *
  679. * @par Example
  680. * To receive into a single data buffer use the @ref buffer function as
  681. * follows:
  682. * @code
  683. * boost::asio::ip::udp::endpoint sender_endpoint;
  684. * socket.receive_from(
  685. * boost::asio::buffer(data, size), sender_endpoint);
  686. * @endcode
  687. * See the @ref buffer documentation for information on receiving into
  688. * multiple buffers in one go, and how to use it with arrays, boost::array or
  689. * std::vector.
  690. */
  691. template <typename MutableBufferSequence>
  692. std::size_t receive_from(const MutableBufferSequence& buffers,
  693. endpoint_type& sender_endpoint)
  694. {
  695. boost::system::error_code ec;
  696. std::size_t s = this->get_service().receive_from(
  697. this->get_implementation(), buffers, sender_endpoint, 0, ec);
  698. boost::asio::detail::throw_error(ec, "receive_from");
  699. return s;
  700. }
  701. /// Receive a datagram with the endpoint of the sender.
  702. /**
  703. * This function is used to receive a datagram. The function call will block
  704. * until data has been received successfully or an error occurs.
  705. *
  706. * @param buffers One or more buffers into which the data will be received.
  707. *
  708. * @param sender_endpoint An endpoint object that receives the endpoint of
  709. * the remote sender of the datagram.
  710. *
  711. * @param flags Flags specifying how the receive call is to be made.
  712. *
  713. * @returns The number of bytes received.
  714. *
  715. * @throws boost::system::system_error Thrown on failure.
  716. */
  717. template <typename MutableBufferSequence>
  718. std::size_t receive_from(const MutableBufferSequence& buffers,
  719. endpoint_type& sender_endpoint, socket_base::message_flags flags)
  720. {
  721. boost::system::error_code ec;
  722. std::size_t s = this->get_service().receive_from(
  723. this->get_implementation(), buffers, sender_endpoint, flags, ec);
  724. boost::asio::detail::throw_error(ec, "receive_from");
  725. return s;
  726. }
  727. /// Receive a datagram with the endpoint of the sender.
  728. /**
  729. * This function is used to receive a datagram. The function call will block
  730. * until data has been received successfully or an error occurs.
  731. *
  732. * @param buffers One or more buffers into which the data will be received.
  733. *
  734. * @param sender_endpoint An endpoint object that receives the endpoint of
  735. * the remote sender of the datagram.
  736. *
  737. * @param flags Flags specifying how the receive call is to be made.
  738. *
  739. * @param ec Set to indicate what error occurred, if any.
  740. *
  741. * @returns The number of bytes received.
  742. */
  743. template <typename MutableBufferSequence>
  744. std::size_t receive_from(const MutableBufferSequence& buffers,
  745. endpoint_type& sender_endpoint, socket_base::message_flags flags,
  746. boost::system::error_code& ec)
  747. {
  748. return this->get_service().receive_from(this->get_implementation(),
  749. buffers, sender_endpoint, flags, ec);
  750. }
  751. /// Start an asynchronous receive.
  752. /**
  753. * This function is used to asynchronously receive a datagram. The function
  754. * call always returns immediately.
  755. *
  756. * @param buffers One or more buffers into which the data will be received.
  757. * Although the buffers object may be copied as necessary, ownership of the
  758. * underlying memory blocks is retained by the caller, which must guarantee
  759. * that they remain valid until the handler is called.
  760. *
  761. * @param sender_endpoint An endpoint object that receives the endpoint of
  762. * the remote sender of the datagram. Ownership of the sender_endpoint object
  763. * is retained by the caller, which must guarantee that it is valid until the
  764. * handler is called.
  765. *
  766. * @param handler The handler to be called when the receive operation
  767. * completes. Copies will be made of the handler as required. The function
  768. * signature of the handler must be:
  769. * @code void handler(
  770. * const boost::system::error_code& error, // Result of operation.
  771. * std::size_t bytes_transferred // Number of bytes received.
  772. * ); @endcode
  773. * Regardless of whether the asynchronous operation completes immediately or
  774. * not, the handler will not be invoked from within this function. Invocation
  775. * of the handler will be performed in a manner equivalent to using
  776. * boost::asio::io_service::post().
  777. *
  778. * @par Example
  779. * To receive into a single data buffer use the @ref buffer function as
  780. * follows:
  781. * @code socket.async_receive_from(
  782. * boost::asio::buffer(data, size), 0, sender_endpoint, handler); @endcode
  783. * See the @ref buffer documentation for information on receiving into
  784. * multiple buffers in one go, and how to use it with arrays, boost::array or
  785. * std::vector.
  786. */
  787. template <typename MutableBufferSequence, typename ReadHandler>
  788. void async_receive_from(const MutableBufferSequence& buffers,
  789. endpoint_type& sender_endpoint,
  790. BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
  791. {
  792. // If you get an error on the following line it means that your handler does
  793. // not meet the documented type requirements for a ReadHandler.
  794. BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
  795. this->get_service().async_receive_from(this->get_implementation(), buffers,
  796. sender_endpoint, 0, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
  797. }
  798. /// Start an asynchronous receive.
  799. /**
  800. * This function is used to asynchronously receive a datagram. The function
  801. * call always returns immediately.
  802. *
  803. * @param buffers One or more buffers into which the data will be received.
  804. * Although the buffers object may be copied as necessary, ownership of the
  805. * underlying memory blocks is retained by the caller, which must guarantee
  806. * that they remain valid until the handler is called.
  807. *
  808. * @param sender_endpoint An endpoint object that receives the endpoint of
  809. * the remote sender of the datagram. Ownership of the sender_endpoint object
  810. * is retained by the caller, which must guarantee that it is valid until the
  811. * handler is called.
  812. *
  813. * @param flags Flags specifying how the receive call is to be made.
  814. *
  815. * @param handler The handler to be called when the receive operation
  816. * completes. Copies will be made of the handler as required. The function
  817. * signature of the handler must be:
  818. * @code void handler(
  819. * const boost::system::error_code& error, // Result of operation.
  820. * std::size_t bytes_transferred // Number of bytes received.
  821. * ); @endcode
  822. * Regardless of whether the asynchronous operation completes immediately or
  823. * not, the handler will not be invoked from within this function. Invocation
  824. * of the handler will be performed in a manner equivalent to using
  825. * boost::asio::io_service::post().
  826. */
  827. template <typename MutableBufferSequence, typename ReadHandler>
  828. void async_receive_from(const MutableBufferSequence& buffers,
  829. endpoint_type& sender_endpoint, socket_base::message_flags flags,
  830. BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
  831. {
  832. // If you get an error on the following line it means that your handler does
  833. // not meet the documented type requirements for a ReadHandler.
  834. BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
  835. this->get_service().async_receive_from(this->get_implementation(), buffers,
  836. sender_endpoint, flags, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
  837. }
  838. };
  839. } // namespace asio
  840. } // namespace boost
  841. #include <boost/asio/detail/pop_options.hpp>
  842. #endif // BOOST_ASIO_BASIC_DATAGRAM_SOCKET_HPP