boost/asio/basic_raw_socket.hpp

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