ceph/src/boost/boost/asio/basic_datagram_socket.hpp

   1 //
   2 // basic_datagram_socket.hpp
   3 // ~~~~~~~~~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2017 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
  11 #ifndef BOOST_ASIO_BASIC_DATAGRAM_SOCKET_HPP
  12 #define BOOST_ASIO_BASIC_DATAGRAM_SOCKET_HPP
  13
  14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  15 # pragma once
  16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  17
  18 #include <boost/asio/detail/config.hpp>
  19 #include <cstddef>
  20 #include <boost/asio/basic_socket.hpp>
  21 #include <boost/asio/detail/handler_type_requirements.hpp>
  22 #include <boost/asio/detail/throw_error.hpp>
  23 #include <boost/asio/detail/type_traits.hpp>
  24 #include <boost/asio/error.hpp>
  25
  26 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
  27 # include <boost/asio/datagram_socket_service.hpp>
  28 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
  29
  30 #include <boost/asio/detail/push_options.hpp>
  31
  32 namespace boost {
  33 namespace asio {
  34
  35 /// Provides datagram-oriented socket functionality.
  36 /**
  37  * The basic_datagram_socket class template provides asynchronous and blocking
  38  * datagram-oriented socket functionality.
  39  *
  40  * @par Thread Safety
  41  * @e Distinct @e objects: Safe.@n
  42  * @e Shared @e objects: Unsafe.
  43  */
  44 template <typename Protocol
  45     BOOST_ASIO_SVC_TPARAM_DEF1(= datagram_socket_service<Protocol>)>
  46 class basic_datagram_socket
  47   : public basic_socket<Protocol BOOST_ASIO_SVC_TARG>
  48 {
  49 public:
  50   /// The native representation of a socket.
  51 #if defined(GENERATING_DOCUMENTATION)
  52   typedef implementation_defined native_handle_type;
  53 #else
  54   typedef typename basic_socket<
  55     Protocol BOOST_ASIO_SVC_TARG>::native_handle_type native_handle_type;
  56 #endif
  57
  58   /// The protocol type.
  59   typedef Protocol protocol_type;
  60
  61   /// The endpoint type.
  62   typedef typename Protocol::endpoint endpoint_type;
  63
  64   /// Construct a basic_datagram_socket without opening it.
  65   /**
  66    * This constructor creates a datagram socket without opening it. The open()
  67    * function must be called before data can be sent or received on the socket.
  68    *
  69    * @param io_context The io_context object that the datagram socket will use
  70    * to dispatch handlers for any asynchronous operations performed on the
  71    * socket.
  72    */
  73   explicit basic_datagram_socket(boost::asio::io_context& io_context)
  74     : basic_socket<Protocol BOOST_ASIO_SVC_TARG>(io_context)
  75   {
  76   }
  77
  78   /// Construct and open a basic_datagram_socket.
  79   /**
  80    * This constructor creates and opens a datagram socket.
  81    *
  82    * @param io_context The io_context object that the datagram socket will use
  83    * to dispatch handlers for any asynchronous operations performed on the
  84    * socket.
  85    *
  86    * @param protocol An object specifying protocol parameters to be used.
  87    *
  88    * @throws boost::system::system_error Thrown on failure.
  89    */
  90   basic_datagram_socket(boost::asio::io_context& io_context,
  91       const protocol_type& protocol)
  92     : basic_socket<Protocol BOOST_ASIO_SVC_TARG>(io_context, protocol)
  93   {
  94   }
  95
  96   /// Construct a basic_datagram_socket, opening it and binding it to the given
  97   /// local endpoint.
  98   /**
  99    * This constructor creates a datagram socket and automatically opens it bound
 100    * to the specified endpoint on the local machine. The protocol used is the
 101    * protocol associated with the given endpoint.
 102    *
 103    * @param io_context The io_context object that the datagram socket will use
 104    * to dispatch handlers for any asynchronous operations performed on the
 105    * socket.
 106    *
 107    * @param endpoint An endpoint on the local machine to which the datagram
 108    * socket will be bound.
 109    *
 110    * @throws boost::system::system_error Thrown on failure.
 111    */
 112   basic_datagram_socket(boost::asio::io_context& io_context,
 113       const endpoint_type& endpoint)
 114     : basic_socket<Protocol BOOST_ASIO_SVC_TARG>(io_context, endpoint)
 115   {
 116   }
 117
 118   /// Construct a basic_datagram_socket on an existing native socket.
 119   /**
 120    * This constructor creates a datagram socket object to hold an existing
 121    * native socket.
 122    *
 123    * @param io_context The io_context object that the datagram socket will use
 124    * to dispatch handlers for any asynchronous operations performed on the
 125    * socket.
 126    *
 127    * @param protocol An object specifying protocol parameters to be used.
 128    *
 129    * @param native_socket The new underlying socket implementation.
 130    *
 131    * @throws boost::system::system_error Thrown on failure.
 132    */
 133   basic_datagram_socket(boost::asio::io_context& io_context,
 134       const protocol_type& protocol, const native_handle_type& native_socket)
 135     : basic_socket<Protocol BOOST_ASIO_SVC_TARG>(
 136         io_context, protocol, native_socket)
 137   {
 138   }
 139
 140 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 141   /// Move-construct a basic_datagram_socket from another.
 142   /**
 143    * This constructor moves a datagram socket from one object to another.
 144    *
 145    * @param other The other basic_datagram_socket object from which the move
 146    * will occur.
 147    *
 148    * @note Following the move, the moved-from object is in the same state as if
 149    * constructed using the @c basic_datagram_socket(io_context&) constructor.
 150    */
 151   basic_datagram_socket(basic_datagram_socket&& other)
 152     : basic_socket<Protocol BOOST_ASIO_SVC_TARG>(std::move(other))
 153   {
 154   }
 155
 156   /// Move-assign a basic_datagram_socket from another.
 157   /**
 158    * This assignment operator moves a datagram socket from one object to
 159    * another.
 160    *
 161    * @param other The other basic_datagram_socket object from which the move
 162    * will occur.
 163    *
 164    * @note Following the move, the moved-from object is in the same state as if
 165    * constructed using the @c basic_datagram_socket(io_context&) constructor.
 166    */
 167   basic_datagram_socket& operator=(basic_datagram_socket&& other)
 168   {
 169     basic_socket<Protocol BOOST_ASIO_SVC_TARG>::operator=(std::move(other));
 170     return *this;
 171   }
 172
 173   /// Move-construct a basic_datagram_socket from a socket of another protocol
 174   /// type.
 175   /**
 176    * This constructor moves a datagram socket from one object to another.
 177    *
 178    * @param other The other basic_datagram_socket object from which the move
 179    * will occur.
 180    *
 181    * @note Following the move, the moved-from object is in the same state as if
 182    * constructed using the @c basic_datagram_socket(io_context&) constructor.
 183    */
 184   template <typename Protocol1 BOOST_ASIO_SVC_TPARAM1>
 185   basic_datagram_socket(
 186       basic_datagram_socket<Protocol1 BOOST_ASIO_SVC_TARG1>&& other,
 187       typename enable_if<is_convertible<Protocol1, Protocol>::value>::type* = 0)
 188     : basic_socket<Protocol BOOST_ASIO_SVC_TARG>(std::move(other))
 189   {
 190   }
 191
 192   /// Move-assign a basic_datagram_socket from a socket of another protocol
 193   /// type.
 194   /**
 195    * This assignment operator moves a datagram socket from one object to
 196    * another.
 197    *
 198    * @param other The other basic_datagram_socket object from which the move
 199    * will occur.
 200    *
 201    * @note Following the move, the moved-from object is in the same state as if
 202    * constructed using the @c basic_datagram_socket(io_context&) constructor.
 203    */
 204   template <typename Protocol1 BOOST_ASIO_SVC_TPARAM1>
 205   typename enable_if<is_convertible<Protocol1, Protocol>::value,
 206       basic_datagram_socket>::type& operator=(
 207         basic_datagram_socket<Protocol1 BOOST_ASIO_SVC_TARG1>&& other)
 208   {
 209     basic_socket<Protocol BOOST_ASIO_SVC_TARG>::operator=(std::move(other));
 210     return *this;
 211   }
 212 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 213
 214   /// Destroys the socket.
 215   /**
 216    * This function destroys the socket, cancelling any outstanding asynchronous
 217    * operations associated with the socket as if by calling @c cancel.
 218    */
 219   ~basic_datagram_socket()
 220   {
 221   }
 222
 223   /// Send some data on a connected socket.
 224   /**
 225    * This function is used to send data on the datagram socket. The function
 226    * call will block until the data has been sent successfully or an error
 227    * occurs.
 228    *
 229    * @param buffers One ore more data buffers to be sent on the socket.
 230    *
 231    * @returns The number of bytes sent.
 232    *
 233    * @throws boost::system::system_error Thrown on failure.
 234    *
 235    * @note The send operation can only be used with a connected socket. Use
 236    * the send_to function to send data on an unconnected datagram socket.
 237    *
 238    * @par Example
 239    * To send a single data buffer use the @ref buffer function as follows:
 240    * @code socket.send(boost::asio::buffer(data, size)); @endcode
 241    * See the @ref buffer documentation for information on sending multiple
 242    * buffers in one go, and how to use it with arrays, boost::array or
 243    * std::vector.
 244    */
 245   template <typename ConstBufferSequence>
 246   std::size_t send(const ConstBufferSequence& buffers)
 247   {
 248     boost::system::error_code ec;
 249     std::size_t s = this->get_service().send(
 250         this->get_implementation(), buffers, 0, ec);
 251     boost::asio::detail::throw_error(ec, "send");
 252     return s;
 253   }
 254
 255   /// Send some data on a connected socket.
 256   /**
 257    * This function is used to send data on the datagram socket. The function
 258    * call will block until the data has been sent successfully or an error
 259    * occurs.
 260    *
 261    * @param buffers One ore more data buffers to be sent on the socket.
 262    *
 263    * @param flags Flags specifying how the send call is to be made.
 264    *
 265    * @returns The number of bytes sent.
 266    *
 267    * @throws boost::system::system_error Thrown on failure.
 268    *
 269    * @note The send operation can only be used with a connected socket. Use
 270    * the send_to function to send data on an unconnected datagram socket.
 271    */
 272   template <typename ConstBufferSequence>
 273   std::size_t send(const ConstBufferSequence& buffers,
 274       socket_base::message_flags flags)
 275   {
 276     boost::system::error_code ec;
 277     std::size_t s = this->get_service().send(
 278         this->get_implementation(), buffers, flags, ec);
 279     boost::asio::detail::throw_error(ec, "send");
 280     return s;
 281   }
 282
 283   /// Send some data 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.
 290    *
 291    * @param flags Flags specifying how the send call is to be made.
 292    *
 293    * @param ec Set to indicate what error occurred, if any.
 294    *
 295    * @returns The number of bytes sent.
 296    *
 297    * @note The send operation can only be used with a connected socket. Use
 298    * the send_to function to send data on an unconnected datagram socket.
 299    */
 300   template <typename ConstBufferSequence>
 301   std::size_t send(const ConstBufferSequence& buffers,
 302       socket_base::message_flags flags, boost::system::error_code& ec)
 303   {
 304     return this->get_service().send(
 305         this->get_implementation(), buffers, flags, ec);
 306   }
 307
 308   /// Start an asynchronous send on a connected socket.
 309   /**
 310    * This function is used to asynchronously send data on the datagram socket.
 311    * The function call always returns immediately.
 312    *
 313    * @param buffers One or more data buffers to be sent on the socket. Although
 314    * the buffers object may be copied as necessary, ownership of the underlying
 315    * memory blocks is retained by the caller, which must guarantee that they
 316    * remain valid until the handler is called.
 317    *
 318    * @param handler The handler to be called when the send operation completes.
 319    * Copies will be made of the handler as required. The function signature of
 320    * the handler must be:
 321    * @code void handler(
 322    *   const boost::system::error_code& error, // Result of operation.
 323    *   std::size_t bytes_transferred           // Number of bytes sent.
 324    * ); @endcode
 325    * Regardless of whether the asynchronous operation completes immediately or
 326    * not, the handler will not be invoked from within this function. Invocation
 327    * of the handler will be performed in a manner equivalent to using
 328    * boost::asio::io_context::post().
 329    *
 330    * @note The async_send operation can only be used with a connected socket.
 331    * Use the async_send_to function to send data on an unconnected datagram
 332    * socket.
 333    *
 334    * @par Example
 335    * To send a single data buffer use the @ref buffer function as follows:
 336    * @code
 337    * socket.async_send(boost::asio::buffer(data, size), handler);
 338    * @endcode
 339    * See the @ref buffer documentation for information on sending multiple
 340    * buffers in one go, and how to use it with arrays, boost::array or
 341    * std::vector.
 342    */
 343   template <typename ConstBufferSequence, typename WriteHandler>
 344   BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
 345       void (boost::system::error_code, std::size_t))
 346   async_send(const ConstBufferSequence& buffers,
 347       BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
 348   {
 349     // If you get an error on the following line it means that your handler does
 350     // not meet the documented type requirements for a WriteHandler.
 351     BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
 352
 353 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 354     return this->get_service().async_send(this->get_implementation(),
 355         buffers, 0, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
 356 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 357     async_completion<WriteHandler,
 358       void (boost::system::error_code, std::size_t)> init(handler);
 359
 360     this->get_service().async_send(this->get_implementation(),
 361         buffers, 0, init.completion_handler);
 362
 363     return init.result.get();
 364 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 365   }
 366
 367   /// Start an asynchronous send on a connected socket.
 368   /**
 369    * This function is used to asynchronously send data on the datagram socket.
 370    * The function call always returns immediately.
 371    *
 372    * @param buffers One or more data buffers to be sent on the socket. Although
 373    * the buffers object may be copied as necessary, ownership of the underlying
 374    * memory blocks is retained by the caller, which must guarantee that they
 375    * remain valid until the handler is called.
 376    *
 377    * @param flags Flags specifying how the send call is to be made.
 378    *
 379    * @param handler The handler to be called when the send operation completes.
 380    * Copies will be made of the handler as required. The function signature of
 381    * the handler must be:
 382    * @code void handler(
 383    *   const boost::system::error_code& error, // Result of operation.
 384    *   std::size_t bytes_transferred           // Number of bytes sent.
 385    * ); @endcode
 386    * Regardless of whether the asynchronous operation completes immediately or
 387    * not, the handler will not be invoked from within this function. Invocation
 388    * of the handler will be performed in a manner equivalent to using
 389    * boost::asio::io_context::post().
 390    *
 391    * @note The async_send operation can only be used with a connected socket.
 392    * Use the async_send_to function to send data on an unconnected datagram
 393    * socket.
 394    */
 395   template <typename ConstBufferSequence, typename WriteHandler>
 396   BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
 397       void (boost::system::error_code, std::size_t))
 398   async_send(const ConstBufferSequence& buffers,
 399       socket_base::message_flags flags,
 400       BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
 401   {
 402     // If you get an error on the following line it means that your handler does
 403     // not meet the documented type requirements for a WriteHandler.
 404     BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
 405
 406 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 407     return this->get_service().async_send(this->get_implementation(),
 408         buffers, flags, BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
 409 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 410     async_completion<WriteHandler,
 411       void (boost::system::error_code, std::size_t)> init(handler);
 412
 413     this->get_service().async_send(this->get_implementation(),
 414         buffers, flags, init.completion_handler);
 415
 416     return init.result.get();
 417 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 418   }
 419
 420   /// Send a datagram to the specified endpoint.
 421   /**
 422    * This function is used to send a datagram to the specified remote endpoint.
 423    * The function call will block until the data has been sent successfully or
 424    * an error occurs.
 425    *
 426    * @param buffers One or more data buffers to be sent to the remote endpoint.
 427    *
 428    * @param destination The remote endpoint to which the data will be sent.
 429    *
 430    * @returns The number of bytes sent.
 431    *
 432    * @throws boost::system::system_error Thrown on failure.
 433    *
 434    * @par Example
 435    * To send a single data buffer use the @ref buffer function as follows:
 436    * @code
 437    * boost::asio::ip::udp::endpoint destination(
 438    *     boost::asio::ip::address::from_string("1.2.3.4"), 12345);
 439    * socket.send_to(boost::asio::buffer(data, size), destination);
 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>
 446   std::size_t send_to(const ConstBufferSequence& buffers,
 447       const endpoint_type& destination)
 448   {
 449     boost::system::error_code ec;
 450     std::size_t s = this->get_service().send_to(
 451         this->get_implementation(), buffers, destination, 0, ec);
 452     boost::asio::detail::throw_error(ec, "send_to");
 453     return s;
 454   }
 455
 456   /// Send a datagram to the specified endpoint.
 457   /**
 458    * This function is used to send a datagram to the specified remote endpoint.
 459    * The function call will block until the data has been sent successfully or
 460    * an error occurs.
 461    *
 462    * @param buffers One or more data buffers to be sent to the remote endpoint.
 463    *
 464    * @param destination The remote endpoint to which the data will be sent.
 465    *
 466    * @param flags Flags specifying how the send call is to be made.
 467    *
 468    * @returns The number of bytes sent.
 469    *
 470    * @throws boost::system::system_error Thrown on failure.
 471    */
 472   template <typename ConstBufferSequence>
 473   std::size_t send_to(const ConstBufferSequence& buffers,
 474       const endpoint_type& destination, socket_base::message_flags flags)
 475   {
 476     boost::system::error_code ec;
 477     std::size_t s = this->get_service().send_to(
 478         this->get_implementation(), buffers, destination, flags, ec);
 479     boost::asio::detail::throw_error(ec, "send_to");
 480     return s;
 481   }
 482
 483   /// Send a datagram to the specified endpoint.
 484   /**
 485    * This function is used to send a datagram to the specified remote endpoint.
 486    * The function call will block until the data has been sent successfully or
 487    * an error occurs.
 488    *
 489    * @param buffers One or more data buffers to be sent to the remote endpoint.
 490    *
 491    * @param destination The remote endpoint to which the data will be sent.
 492    *
 493    * @param flags Flags specifying how the send call is to be made.
 494    *
 495    * @param ec Set to indicate what error occurred, if any.
 496    *
 497    * @returns The number of bytes sent.
 498    */
 499   template <typename ConstBufferSequence>
 500   std::size_t send_to(const ConstBufferSequence& buffers,
 501       const endpoint_type& destination, socket_base::message_flags flags,
 502       boost::system::error_code& ec)
 503   {
 504     return this->get_service().send_to(this->get_implementation(),
 505         buffers, destination, flags, ec);
 506   }
 507
 508   /// Start an asynchronous send.
 509   /**
 510    * This function is used to asynchronously send a datagram to the specified
 511    * remote endpoint. The function call always returns immediately.
 512    *
 513    * @param buffers One or more data buffers to be sent to the remote endpoint.
 514    * Although the buffers object may be copied as necessary, ownership of the
 515    * underlying memory blocks is retained by the caller, which must guarantee
 516    * that they remain valid until the handler is called.
 517    *
 518    * @param destination The remote endpoint to which the data will be sent.
 519    * Copies will be made of the endpoint as required.
 520    *
 521    * @param handler The handler to be called when the send operation completes.
 522    * Copies will be made of the handler as required. The function signature of
 523    * the handler must be:
 524    * @code void handler(
 525    *   const boost::system::error_code& error, // Result of operation.
 526    *   std::size_t bytes_transferred           // Number of bytes sent.
 527    * ); @endcode
 528    * Regardless of whether the asynchronous operation completes immediately or
 529    * not, the handler will not be invoked from within this function. Invocation
 530    * of the handler will be performed in a manner equivalent to using
 531    * boost::asio::io_context::post().
 532    *
 533    * @par Example
 534    * To send a single data buffer use the @ref buffer function as follows:
 535    * @code
 536    * boost::asio::ip::udp::endpoint destination(
 537    *     boost::asio::ip::address::from_string("1.2.3.4"), 12345);
 538    * socket.async_send_to(
 539    *     boost::asio::buffer(data, size), destination, handler);
 540    * @endcode
 541    * See the @ref buffer documentation for information on sending multiple
 542    * buffers in one go, and how to use it with arrays, boost::array or
 543    * std::vector.
 544    */
 545   template <typename ConstBufferSequence, typename WriteHandler>
 546   BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
 547       void (boost::system::error_code, std::size_t))
 548   async_send_to(const ConstBufferSequence& buffers,
 549       const endpoint_type& destination,
 550       BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
 551   {
 552     // If you get an error on the following line it means that your handler does
 553     // not meet the documented type requirements for a WriteHandler.
 554     BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
 555
 556 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 557     return this->get_service().async_send_to(
 558         this->get_implementation(), buffers, destination, 0,
 559         BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
 560 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 561     async_completion<WriteHandler,
 562       void (boost::system::error_code, std::size_t)> init(handler);
 563
 564     this->get_service().async_send_to(
 565         this->get_implementation(), buffers, destination, 0,
 566         init.completion_handler);
 567
 568     return init.result.get();
 569 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 570   }
 571
 572   /// Start an asynchronous send.
 573   /**
 574    * This function is used to asynchronously send a datagram to the specified
 575    * remote endpoint. The function call always returns immediately.
 576    *
 577    * @param buffers One or more data buffers to be sent to the remote endpoint.
 578    * Although the buffers object may be copied as necessary, ownership of the
 579    * underlying memory blocks is retained by the caller, which must guarantee
 580    * that they remain valid until the handler is called.
 581    *
 582    * @param flags Flags specifying how the send call is to be made.
 583    *
 584    * @param destination The remote endpoint to which the data will be sent.
 585    * Copies will be made of the endpoint as required.
 586    *
 587    * @param handler The handler to be called when the send operation completes.
 588    * Copies will be made of the handler as required. The function signature of
 589    * the handler must be:
 590    * @code void handler(
 591    *   const boost::system::error_code& error, // Result of operation.
 592    *   std::size_t bytes_transferred           // Number of bytes sent.
 593    * ); @endcode
 594    * Regardless of whether the asynchronous operation completes immediately or
 595    * not, the handler will not be invoked from within this function. Invocation
 596    * of the handler will be performed in a manner equivalent to using
 597    * boost::asio::io_context::post().
 598    */
 599   template <typename ConstBufferSequence, typename WriteHandler>
 600   BOOST_ASIO_INITFN_RESULT_TYPE(WriteHandler,
 601       void (boost::system::error_code, std::size_t))
 602   async_send_to(const ConstBufferSequence& buffers,
 603       const endpoint_type& destination, socket_base::message_flags flags,
 604       BOOST_ASIO_MOVE_ARG(WriteHandler) handler)
 605   {
 606     // If you get an error on the following line it means that your handler does
 607     // not meet the documented type requirements for a WriteHandler.
 608     BOOST_ASIO_WRITE_HANDLER_CHECK(WriteHandler, handler) type_check;
 609
 610 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 611     return this->get_service().async_send_to(
 612         this->get_implementation(), buffers, destination, flags,
 613         BOOST_ASIO_MOVE_CAST(WriteHandler)(handler));
 614 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 615     async_completion<WriteHandler,
 616       void (boost::system::error_code, std::size_t)> init(handler);
 617
 618     this->get_service().async_send_to(
 619         this->get_implementation(), buffers, destination, flags,
 620         init.completion_handler);
 621
 622     return init.result.get();
 623 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 624   }
 625
 626   /// Receive some data on a connected socket.
 627   /**
 628    * This function is used to receive data on the datagram socket. The function
 629    * call will block until data has been received successfully or an error
 630    * occurs.
 631    *
 632    * @param buffers One or more buffers into which the data will be received.
 633    *
 634    * @returns The number of bytes received.
 635    *
 636    * @throws boost::system::system_error Thrown on failure.
 637    *
 638    * @note The receive operation can only be used with a connected socket. Use
 639    * the receive_from function to receive data on an unconnected datagram
 640    * socket.
 641    *
 642    * @par Example
 643    * To receive into a single data buffer use the @ref buffer function as
 644    * follows:
 645    * @code socket.receive(boost::asio::buffer(data, size)); @endcode
 646    * See the @ref buffer documentation for information on receiving into
 647    * multiple buffers in one go, and how to use it with arrays, boost::array or
 648    * std::vector.
 649    */
 650   template <typename MutableBufferSequence>
 651   std::size_t receive(const MutableBufferSequence& buffers)
 652   {
 653     boost::system::error_code ec;
 654     std::size_t s = this->get_service().receive(
 655         this->get_implementation(), buffers, 0, ec);
 656     boost::asio::detail::throw_error(ec, "receive");
 657     return s;
 658   }
 659
 660   /// Receive some data on a connected socket.
 661   /**
 662    * This function is used to receive data on the datagram socket. The function
 663    * call will block until data has been received successfully or an error
 664    * occurs.
 665    *
 666    * @param buffers One or more buffers into which the data will be received.
 667    *
 668    * @param flags Flags specifying how the receive call is to be made.
 669    *
 670    * @returns The number of bytes received.
 671    *
 672    * @throws boost::system::system_error Thrown on failure.
 673    *
 674    * @note The receive operation can only be used with a connected socket. Use
 675    * the receive_from function to receive data on an unconnected datagram
 676    * socket.
 677    */
 678   template <typename MutableBufferSequence>
 679   std::size_t receive(const MutableBufferSequence& buffers,
 680       socket_base::message_flags flags)
 681   {
 682     boost::system::error_code ec;
 683     std::size_t s = this->get_service().receive(
 684         this->get_implementation(), buffers, flags, ec);
 685     boost::asio::detail::throw_error(ec, "receive");
 686     return s;
 687   }
 688
 689   /// Receive some data on a connected socket.
 690   /**
 691    * This function is used to receive data on the datagram socket. The function
 692    * call will block until data has been received successfully or an error
 693    * occurs.
 694    *
 695    * @param buffers One or more buffers into which the data will be received.
 696    *
 697    * @param flags Flags specifying how the receive call is to be made.
 698    *
 699    * @param ec Set to indicate what error occurred, if any.
 700    *
 701    * @returns The number of bytes received.
 702    *
 703    * @note The receive operation can only be used with a connected socket. Use
 704    * the receive_from function to receive data on an unconnected datagram
 705    * socket.
 706    */
 707   template <typename MutableBufferSequence>
 708   std::size_t receive(const MutableBufferSequence& buffers,
 709       socket_base::message_flags flags, boost::system::error_code& ec)
 710   {
 711     return this->get_service().receive(
 712         this->get_implementation(), buffers, flags, ec);
 713   }
 714
 715   /// Start an asynchronous receive on a connected socket.
 716   /**
 717    * This function is used to asynchronously receive data from the datagram
 718    * socket. The function call always returns immediately.
 719    *
 720    * @param buffers One or more buffers into which the data will be received.
 721    * Although the buffers object may be copied as necessary, ownership of the
 722    * underlying memory blocks is retained by the caller, which must guarantee
 723    * that they remain valid until the handler is called.
 724    *
 725    * @param handler The handler to be called when the receive operation
 726    * completes. Copies will be made of the handler as required. The function
 727    * signature of the handler must be:
 728    * @code void handler(
 729    *   const boost::system::error_code& error, // Result of operation.
 730    *   std::size_t bytes_transferred           // Number of bytes received.
 731    * ); @endcode
 732    * Regardless of whether the asynchronous operation completes immediately or
 733    * not, the handler will not be invoked from within this function. Invocation
 734    * of the handler will be performed in a manner equivalent to using
 735    * boost::asio::io_context::post().
 736    *
 737    * @note The async_receive operation can only be used with a connected socket.
 738    * Use the async_receive_from function to receive data on an unconnected
 739    * datagram socket.
 740    *
 741    * @par Example
 742    * To receive into a single data buffer use the @ref buffer function as
 743    * follows:
 744    * @code
 745    * socket.async_receive(boost::asio::buffer(data, size), handler);
 746    * @endcode
 747    * See the @ref buffer documentation for information on receiving into
 748    * multiple buffers in one go, and how to use it with arrays, boost::array or
 749    * std::vector.
 750    */
 751   template <typename MutableBufferSequence, typename ReadHandler>
 752   BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 753       void (boost::system::error_code, std::size_t))
 754   async_receive(const MutableBufferSequence& buffers,
 755       BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
 756   {
 757     // If you get an error on the following line it means that your handler does
 758     // not meet the documented type requirements for a ReadHandler.
 759     BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
 760
 761 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 762     return this->get_service().async_receive(this->get_implementation(),
 763         buffers, 0, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
 764 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 765     async_completion<ReadHandler,
 766       void (boost::system::error_code, std::size_t)> init(handler);
 767
 768     this->get_service().async_receive(this->get_implementation(),
 769         buffers, 0, init.completion_handler);
 770
 771     return init.result.get();
 772 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 773   }
 774
 775   /// Start an asynchronous receive on a connected socket.
 776   /**
 777    * This function is used to asynchronously receive data from the datagram
 778    * socket. The function call always returns immediately.
 779    *
 780    * @param buffers One or more buffers into which the data will be received.
 781    * Although the buffers object may be copied as necessary, ownership of the
 782    * underlying memory blocks is retained by the caller, which must guarantee
 783    * that they remain valid until the handler is called.
 784    *
 785    * @param flags Flags specifying how the receive call is to be made.
 786    *
 787    * @param handler The handler to be called when the receive operation
 788    * completes. Copies will be made of the handler as required. The function
 789    * signature of the handler must be:
 790    * @code void handler(
 791    *   const boost::system::error_code& error, // Result of operation.
 792    *   std::size_t bytes_transferred           // Number of bytes received.
 793    * ); @endcode
 794    * Regardless of whether the asynchronous operation completes immediately or
 795    * not, the handler will not be invoked from within this function. Invocation
 796    * of the handler will be performed in a manner equivalent to using
 797    * boost::asio::io_context::post().
 798    *
 799    * @note The async_receive operation can only be used with a connected socket.
 800    * Use the async_receive_from function to receive data on an unconnected
 801    * datagram socket.
 802    */
 803   template <typename MutableBufferSequence, typename ReadHandler>
 804   BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 805       void (boost::system::error_code, std::size_t))
 806   async_receive(const MutableBufferSequence& buffers,
 807       socket_base::message_flags flags,
 808       BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
 809   {
 810     // If you get an error on the following line it means that your handler does
 811     // not meet the documented type requirements for a ReadHandler.
 812     BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
 813
 814 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 815     return this->get_service().async_receive(this->get_implementation(),
 816         buffers, flags, BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
 817 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 818     async_completion<ReadHandler,
 819       void (boost::system::error_code, std::size_t)> init(handler);
 820
 821     this->get_service().async_receive(this->get_implementation(),
 822         buffers, flags, init.completion_handler);
 823
 824     return init.result.get();
 825 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 826   }
 827
 828   /// Receive a datagram with the endpoint of the sender.
 829   /**
 830    * This function is used to receive a datagram. The function call will block
 831    * until data has been received successfully or an error occurs.
 832    *
 833    * @param buffers One or more buffers into which the data will be received.
 834    *
 835    * @param sender_endpoint An endpoint object that receives the endpoint of
 836    * the remote sender of the datagram.
 837    *
 838    * @returns The number of bytes received.
 839    *
 840    * @throws boost::system::system_error Thrown on failure.
 841    *
 842    * @par Example
 843    * To receive into a single data buffer use the @ref buffer function as
 844    * follows:
 845    * @code
 846    * boost::asio::ip::udp::endpoint sender_endpoint;
 847    * socket.receive_from(
 848    *     boost::asio::buffer(data, size), sender_endpoint);
 849    * @endcode
 850    * See the @ref buffer documentation for information on receiving into
 851    * multiple buffers in one go, and how to use it with arrays, boost::array or
 852    * std::vector.
 853    */
 854   template <typename MutableBufferSequence>
 855   std::size_t receive_from(const MutableBufferSequence& buffers,
 856       endpoint_type& sender_endpoint)
 857   {
 858     boost::system::error_code ec;
 859     std::size_t s = this->get_service().receive_from(
 860         this->get_implementation(), buffers, sender_endpoint, 0, ec);
 861     boost::asio::detail::throw_error(ec, "receive_from");
 862     return s;
 863   }
 864
 865   /// Receive a datagram with the endpoint of the sender.
 866   /**
 867    * This function is used to receive a datagram. The function call will block
 868    * until data has been received successfully or an error occurs.
 869    *
 870    * @param buffers One or more buffers into which the data will be received.
 871    *
 872    * @param sender_endpoint An endpoint object that receives the endpoint of
 873    * the remote sender of the datagram.
 874    *
 875    * @param flags Flags specifying how the receive call is to be made.
 876    *
 877    * @returns The number of bytes received.
 878    *
 879    * @throws boost::system::system_error Thrown on failure.
 880    */
 881   template <typename MutableBufferSequence>
 882   std::size_t receive_from(const MutableBufferSequence& buffers,
 883       endpoint_type& sender_endpoint, socket_base::message_flags flags)
 884   {
 885     boost::system::error_code ec;
 886     std::size_t s = this->get_service().receive_from(
 887         this->get_implementation(), buffers, sender_endpoint, flags, ec);
 888     boost::asio::detail::throw_error(ec, "receive_from");
 889     return s;
 890   }
 891
 892   /// Receive a datagram with the endpoint of the sender.
 893   /**
 894    * This function is used to receive a datagram. The function call will block
 895    * until data has been received successfully or an error occurs.
 896    *
 897    * @param buffers One or more buffers into which the data will be received.
 898    *
 899    * @param sender_endpoint An endpoint object that receives the endpoint of
 900    * the remote sender of the datagram.
 901    *
 902    * @param flags Flags specifying how the receive call is to be made.
 903    *
 904    * @param ec Set to indicate what error occurred, if any.
 905    *
 906    * @returns The number of bytes received.
 907    */
 908   template <typename MutableBufferSequence>
 909   std::size_t receive_from(const MutableBufferSequence& buffers,
 910       endpoint_type& sender_endpoint, socket_base::message_flags flags,
 911       boost::system::error_code& ec)
 912   {
 913     return this->get_service().receive_from(this->get_implementation(),
 914         buffers, sender_endpoint, flags, ec);
 915   }
 916
 917   /// Start an asynchronous receive.
 918   /**
 919    * This function is used to asynchronously receive a datagram. The function
 920    * call always returns immediately.
 921    *
 922    * @param buffers One or more buffers into which the data will be received.
 923    * Although the buffers object may be copied as necessary, ownership of the
 924    * underlying memory blocks is retained by the caller, which must guarantee
 925    * that they remain valid until the handler is called.
 926    *
 927    * @param sender_endpoint An endpoint object that receives the endpoint of
 928    * the remote sender of the datagram. Ownership of the sender_endpoint object
 929    * is retained by the caller, which must guarantee that it is valid until the
 930    * handler is called.
 931    *
 932    * @param handler The handler to be called when the receive operation
 933    * completes. Copies will be made of the handler as required. The function
 934    * signature of the handler must be:
 935    * @code void handler(
 936    *   const boost::system::error_code& error, // Result of operation.
 937    *   std::size_t bytes_transferred           // Number of bytes received.
 938    * ); @endcode
 939    * Regardless of whether the asynchronous operation completes immediately or
 940    * not, the handler will not be invoked from within this function. Invocation
 941    * of the handler will be performed in a manner equivalent to using
 942    * boost::asio::io_context::post().
 943    *
 944    * @par Example
 945    * To receive into a single data buffer use the @ref buffer function as
 946    * follows:
 947    * @code socket.async_receive_from(
 948    *     boost::asio::buffer(data, size), sender_endpoint, handler); @endcode
 949    * See the @ref buffer documentation for information on receiving into
 950    * multiple buffers in one go, and how to use it with arrays, boost::array or
 951    * std::vector.
 952    */
 953   template <typename MutableBufferSequence, typename ReadHandler>
 954   BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
 955       void (boost::system::error_code, std::size_t))
 956   async_receive_from(const MutableBufferSequence& buffers,
 957       endpoint_type& sender_endpoint,
 958       BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
 959   {
 960     // If you get an error on the following line it means that your handler does
 961     // not meet the documented type requirements for a ReadHandler.
 962     BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
 963
 964 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 965     return this->get_service().async_receive_from(
 966         this->get_implementation(), buffers, sender_endpoint, 0,
 967         BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
 968 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 969     async_completion<ReadHandler,
 970       void (boost::system::error_code, std::size_t)> init(handler);
 971
 972     this->get_service().async_receive_from(
 973         this->get_implementation(), buffers, sender_endpoint, 0,
 974         init.completion_handler);
 975
 976     return init.result.get();
 977 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
 978   }
 979
 980   /// Start an asynchronous receive.
 981   /**
 982    * This function is used to asynchronously receive a datagram. The function
 983    * call always returns immediately.
 984    *
 985    * @param buffers One or more buffers into which the data will be received.
 986    * Although the buffers object may be copied as necessary, ownership of the
 987    * underlying memory blocks is retained by the caller, which must guarantee
 988    * that they remain valid until the handler is called.
 989    *
 990    * @param sender_endpoint An endpoint object that receives the endpoint of
 991    * the remote sender of the datagram. Ownership of the sender_endpoint object
 992    * is retained by the caller, which must guarantee that it is valid until the
 993    * handler is called.
 994    *
 995    * @param flags Flags specifying how the receive call is to be made.
 996    *
 997    * @param handler The handler to be called when the receive operation
 998    * completes. Copies will be made of the handler as required. The function
 999    * signature of the handler must be:
1000    * @code void handler(
1001    *   const boost::system::error_code& error, // Result of operation.
1002    *   std::size_t bytes_transferred           // Number of bytes received.
1003    * ); @endcode
1004    * Regardless of whether the asynchronous operation completes immediately or
1005    * not, the handler will not be invoked from within this function. Invocation
1006    * of the handler will be performed in a manner equivalent to using
1007    * boost::asio::io_context::post().
1008    */
1009   template <typename MutableBufferSequence, typename ReadHandler>
1010   BOOST_ASIO_INITFN_RESULT_TYPE(ReadHandler,
1011       void (boost::system::error_code, std::size_t))
1012   async_receive_from(const MutableBufferSequence& buffers,
1013       endpoint_type& sender_endpoint, socket_base::message_flags flags,
1014       BOOST_ASIO_MOVE_ARG(ReadHandler) handler)
1015   {
1016     // If you get an error on the following line it means that your handler does
1017     // not meet the documented type requirements for a ReadHandler.
1018     BOOST_ASIO_READ_HANDLER_CHECK(ReadHandler, handler) type_check;
1019
1020 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
1021     return this->get_service().async_receive_from(
1022         this->get_implementation(), buffers, sender_endpoint, flags,
1023         BOOST_ASIO_MOVE_CAST(ReadHandler)(handler));
1024 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
1025     async_completion<ReadHandler,
1026       void (boost::system::error_code, std::size_t)> init(handler);
1027
1028     this->get_service().async_receive_from(
1029         this->get_implementation(), buffers, sender_endpoint, flags,
1030         init.completion_handler);
1031
1032     return init.result.get();
1033 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
1034   }
1035 };
1036
1037 } // namespace asio
1038 } // namespace boost
1039
1040 #include <boost/asio/detail/pop_options.hpp>
1041
1042 #endif // BOOST_ASIO_BASIC_DATAGRAM_SOCKET_HPP