PageRenderTime 72ms CodeModel.GetById 15ms app.highlight 50ms RepoModel.GetById 1ms app.codeStats 0ms

/include/boost/asio/basic_socket.hpp

https://bitbucket.org/wetterj/fg-gc
C++ Header | 1062 lines | 280 code | 52 blank | 730 comment | 14 complexity | 762b9a3d01b999f86f7f7d510ad0e2af MD5 | raw file
   1//
   2// basic_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
  11#ifndef BOOST_ASIO_BASIC_SOCKET_HPP
  12#define BOOST_ASIO_BASIC_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 <boost/asio/basic_io_object.hpp>
  20#include <boost/asio/detail/throw_error.hpp>
  21#include <boost/asio/error.hpp>
  22#include <boost/asio/socket_base.hpp>
  23
  24#include <boost/asio/detail/push_options.hpp>
  25
  26namespace boost {
  27namespace asio {
  28
  29/// Provides socket functionality.
  30/**
  31 * The basic_socket class template provides functionality that is common to both
  32 * stream-oriented and datagram-oriented sockets.
  33 *
  34 * @par Thread Safety
  35 * @e Distinct @e objects: Safe.@n
  36 * @e Shared @e objects: Unsafe.
  37 */
  38template <typename Protocol, typename SocketService>
  39class basic_socket
  40  : public basic_io_object<SocketService>,
  41    public socket_base
  42{
  43public:
  44  /// The native representation of a socket.
  45  typedef typename SocketService::native_type native_type;
  46
  47  /// The protocol type.
  48  typedef Protocol protocol_type;
  49
  50  /// The endpoint type.
  51  typedef typename Protocol::endpoint endpoint_type;
  52
  53  /// A basic_socket is always the lowest layer.
  54  typedef basic_socket<Protocol, SocketService> lowest_layer_type;
  55
  56  /// Construct a basic_socket without opening it.
  57  /**
  58   * This constructor creates a socket without opening it.
  59   *
  60   * @param io_service The io_service object that the socket will use to
  61   * dispatch handlers for any asynchronous operations performed on the socket.
  62   */
  63  explicit basic_socket(boost::asio::io_service& io_service)
  64    : basic_io_object<SocketService>(io_service)
  65  {
  66  }
  67
  68  /// Construct and open a basic_socket.
  69  /**
  70   * This constructor creates and opens a socket.
  71   *
  72   * @param io_service The io_service object that the socket will use to
  73   * dispatch handlers for any asynchronous operations performed on the socket.
  74   *
  75   * @param protocol An object specifying protocol parameters to be used.
  76   *
  77   * @throws boost::system::system_error Thrown on failure.
  78   */
  79  basic_socket(boost::asio::io_service& io_service,
  80      const protocol_type& protocol)
  81    : basic_io_object<SocketService>(io_service)
  82  {
  83    boost::system::error_code ec;
  84    this->service.open(this->implementation, protocol, ec);
  85    boost::asio::detail::throw_error(ec);
  86  }
  87
  88  /// Construct a basic_socket, opening it and binding it to the given local
  89  /// endpoint.
  90  /**
  91   * This constructor creates a socket and automatically opens it bound to the
  92   * specified endpoint on the local machine. The protocol used is the protocol
  93   * associated with the given endpoint.
  94   *
  95   * @param io_service The io_service object that the socket will use to
  96   * dispatch handlers for any asynchronous operations performed on the socket.
  97   *
  98   * @param endpoint An endpoint on the local machine to which the socket will
  99   * be bound.
 100   *
 101   * @throws boost::system::system_error Thrown on failure.
 102   */
 103  basic_socket(boost::asio::io_service& io_service,
 104      const endpoint_type& endpoint)
 105    : basic_io_object<SocketService>(io_service)
 106  {
 107    boost::system::error_code ec;
 108    this->service.open(this->implementation, endpoint.protocol(), ec);
 109    boost::asio::detail::throw_error(ec);
 110    this->service.bind(this->implementation, endpoint, ec);
 111    boost::asio::detail::throw_error(ec);
 112  }
 113
 114  /// Construct a basic_socket on an existing native socket.
 115  /**
 116   * This constructor creates a socket object to hold an existing native socket.
 117   *
 118   * @param io_service The io_service object that the socket will use to
 119   * dispatch handlers for any asynchronous operations performed on the socket.
 120   *
 121   * @param protocol An object specifying protocol parameters to be used.
 122   *
 123   * @param native_socket A native socket.
 124   *
 125   * @throws boost::system::system_error Thrown on failure.
 126   */
 127  basic_socket(boost::asio::io_service& io_service,
 128      const protocol_type& protocol, const native_type& native_socket)
 129    : basic_io_object<SocketService>(io_service)
 130  {
 131    boost::system::error_code ec;
 132    this->service.assign(this->implementation, protocol, native_socket, ec);
 133    boost::asio::detail::throw_error(ec);
 134  }
 135
 136  /// Get a reference to the lowest layer.
 137  /**
 138   * This function returns a reference to the lowest layer in a stack of
 139   * layers. Since a basic_socket cannot contain any further layers, it simply
 140   * returns a reference to itself.
 141   *
 142   * @return A reference to the lowest layer in the stack of layers. Ownership
 143   * is not transferred to the caller.
 144   */
 145  lowest_layer_type& lowest_layer()
 146  {
 147    return *this;
 148  }
 149
 150  /// Get a const reference to the lowest layer.
 151  /**
 152   * This function returns a const reference to the lowest layer in a stack of
 153   * layers. Since a basic_socket cannot contain any further layers, it simply
 154   * returns a reference to itself.
 155   *
 156   * @return A const reference to the lowest layer in the stack of layers.
 157   * Ownership is not transferred to the caller.
 158   */
 159  const lowest_layer_type& lowest_layer() const
 160  {
 161    return *this;
 162  }
 163
 164  /// Open the socket using the specified protocol.
 165  /**
 166   * This function opens the socket so that it will use the specified protocol.
 167   *
 168   * @param protocol An object specifying protocol parameters to be used.
 169   *
 170   * @throws boost::system::system_error Thrown on failure.
 171   *
 172   * @par Example
 173   * @code
 174   * boost::asio::ip::tcp::socket socket(io_service);
 175   * socket.open(boost::asio::ip::tcp::v4());
 176   * @endcode
 177   */
 178  void open(const protocol_type& protocol = protocol_type())
 179  {
 180    boost::system::error_code ec;
 181    this->service.open(this->implementation, protocol, ec);
 182    boost::asio::detail::throw_error(ec);
 183  }
 184
 185  /// Open the socket using the specified protocol.
 186  /**
 187   * This function opens the socket so that it will use the specified protocol.
 188   *
 189   * @param protocol An object specifying which protocol is to be used.
 190   *
 191   * @param ec Set to indicate what error occurred, if any.
 192   *
 193   * @par Example
 194   * @code
 195   * boost::asio::ip::tcp::socket socket(io_service);
 196   * boost::system::error_code ec;
 197   * socket.open(boost::asio::ip::tcp::v4(), ec);
 198   * if (ec)
 199   * {
 200   *   // An error occurred.
 201   * }
 202   * @endcode
 203   */
 204  boost::system::error_code open(const protocol_type& protocol,
 205      boost::system::error_code& ec)
 206  {
 207    return this->service.open(this->implementation, protocol, ec);
 208  }
 209
 210  /// Assign an existing native socket to the socket.
 211  /*
 212   * This function opens the socket to hold an existing native socket.
 213   *
 214   * @param protocol An object specifying which protocol is to be used.
 215   *
 216   * @param native_socket A native socket.
 217   *
 218   * @throws boost::system::system_error Thrown on failure.
 219   */
 220  void assign(const protocol_type& protocol, const native_type& native_socket)
 221  {
 222    boost::system::error_code ec;
 223    this->service.assign(this->implementation, protocol, native_socket, ec);
 224    boost::asio::detail::throw_error(ec);
 225  }
 226
 227  /// Assign an existing native socket to the socket.
 228  /*
 229   * This function opens the socket to hold an existing native socket.
 230   *
 231   * @param protocol An object specifying which protocol is to be used.
 232   *
 233   * @param native_socket A native socket.
 234   *
 235   * @param ec Set to indicate what error occurred, if any.
 236   */
 237  boost::system::error_code assign(const protocol_type& protocol,
 238      const native_type& native_socket, boost::system::error_code& ec)
 239  {
 240    return this->service.assign(this->implementation,
 241        protocol, native_socket, ec);
 242  }
 243
 244  /// Determine whether the socket is open.
 245  bool is_open() const
 246  {
 247    return this->service.is_open(this->implementation);
 248  }
 249
 250  /// Close the socket.
 251  /**
 252   * This function is used to close the socket. Any asynchronous send, receive
 253   * or connect operations will be cancelled immediately, and will complete
 254   * with the boost::asio::error::operation_aborted error.
 255   *
 256   * @throws boost::system::system_error Thrown on failure.
 257   *
 258   * @note For portable behaviour with respect to graceful closure of a
 259   * connected socket, call shutdown() before closing the socket.
 260   */
 261  void close()
 262  {
 263    boost::system::error_code ec;
 264    this->service.close(this->implementation, ec);
 265    boost::asio::detail::throw_error(ec);
 266  }
 267
 268  /// Close the socket.
 269  /**
 270   * This function is used to close the socket. Any asynchronous send, receive
 271   * or connect operations will be cancelled immediately, and will complete
 272   * with the boost::asio::error::operation_aborted error.
 273   *
 274   * @param ec Set to indicate what error occurred, if any.
 275   *
 276   * @par Example
 277   * @code
 278   * boost::asio::ip::tcp::socket socket(io_service);
 279   * ...
 280   * boost::system::error_code ec;
 281   * socket.close(ec);
 282   * if (ec)
 283   * {
 284   *   // An error occurred.
 285   * }
 286   * @endcode
 287   *
 288   * @note For portable behaviour with respect to graceful closure of a
 289   * connected socket, call shutdown() before closing the socket.
 290   */
 291  boost::system::error_code close(boost::system::error_code& ec)
 292  {
 293    return this->service.close(this->implementation, ec);
 294  }
 295
 296  /// Get the native socket representation.
 297  /**
 298   * This function may be used to obtain the underlying representation of the
 299   * socket. This is intended to allow access to native socket functionality
 300   * that is not otherwise provided.
 301   */
 302  native_type native()
 303  {
 304    return this->service.native(this->implementation);
 305  }
 306
 307  /// Cancel all asynchronous operations associated with the socket.
 308  /**
 309   * This function causes all outstanding asynchronous connect, send and receive
 310   * operations to finish immediately, and the handlers for cancelled operations
 311   * will be passed the boost::asio::error::operation_aborted error.
 312   *
 313   * @throws boost::system::system_error Thrown on failure.
 314   *
 315   * @note Calls to cancel() will always fail with
 316   * boost::asio::error::operation_not_supported when run on Windows XP, Windows
 317   * Server 2003, and earlier versions of Windows, unless
 318   * BOOST_ASIO_ENABLE_CANCELIO is defined. However, the CancelIo function has
 319   * two issues that should be considered before enabling its use:
 320   *
 321   * @li It will only cancel asynchronous operations that were initiated in the
 322   * current thread.
 323   *
 324   * @li It can appear to complete without error, but the request to cancel the
 325   * unfinished operations may be silently ignored by the operating system.
 326   * Whether it works or not seems to depend on the drivers that are installed.
 327   *
 328   * For portable cancellation, consider using one of the following
 329   * alternatives:
 330   *
 331   * @li Disable asio's I/O completion port backend by defining
 332   * BOOST_ASIO_DISABLE_IOCP.
 333   *
 334   * @li Use the close() function to simultaneously cancel the outstanding
 335   * operations and close the socket.
 336   *
 337   * When running on Windows Vista, Windows Server 2008, and later, the
 338   * CancelIoEx function is always used. This function does not have the
 339   * problems described above.
 340   */
 341#if defined(BOOST_MSVC) && (BOOST_MSVC >= 1400) \
 342  && (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0600) \
 343  && !defined(BOOST_ASIO_ENABLE_CANCELIO)
 344  __declspec(deprecated("By default, this function always fails with "
 345        "operation_not_supported when used on Windows XP, Windows Server 2003, "
 346        "or earlier. Consult documentation for details."))
 347#endif
 348  void cancel()
 349  {
 350    boost::system::error_code ec;
 351    this->service.cancel(this->implementation, ec);
 352    boost::asio::detail::throw_error(ec);
 353  }
 354
 355  /// Cancel all asynchronous operations associated with the socket.
 356  /**
 357   * This function causes all outstanding asynchronous connect, send and receive
 358   * operations to finish immediately, and the handlers for cancelled operations
 359   * will be passed the boost::asio::error::operation_aborted error.
 360   *
 361   * @param ec Set to indicate what error occurred, if any.
 362   *
 363   * @note Calls to cancel() will always fail with
 364   * boost::asio::error::operation_not_supported when run on Windows XP, Windows
 365   * Server 2003, and earlier versions of Windows, unless
 366   * BOOST_ASIO_ENABLE_CANCELIO is defined. However, the CancelIo function has
 367   * two issues that should be considered before enabling its use:
 368   *
 369   * @li It will only cancel asynchronous operations that were initiated in the
 370   * current thread.
 371   *
 372   * @li It can appear to complete without error, but the request to cancel the
 373   * unfinished operations may be silently ignored by the operating system.
 374   * Whether it works or not seems to depend on the drivers that are installed.
 375   *
 376   * For portable cancellation, consider using one of the following
 377   * alternatives:
 378   *
 379   * @li Disable asio's I/O completion port backend by defining
 380   * BOOST_ASIO_DISABLE_IOCP.
 381   *
 382   * @li Use the close() function to simultaneously cancel the outstanding
 383   * operations and close the socket.
 384   *
 385   * When running on Windows Vista, Windows Server 2008, and later, the
 386   * CancelIoEx function is always used. This function does not have the
 387   * problems described above.
 388   */
 389#if defined(BOOST_MSVC) && (BOOST_MSVC >= 1400) \
 390  && (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0600) \
 391  && !defined(BOOST_ASIO_ENABLE_CANCELIO)
 392  __declspec(deprecated("By default, this function always fails with "
 393        "operation_not_supported when used on Windows XP, Windows Server 2003, "
 394        "or earlier. Consult documentation for details."))
 395#endif
 396  boost::system::error_code cancel(boost::system::error_code& ec)
 397  {
 398    return this->service.cancel(this->implementation, ec);
 399  }
 400
 401  /// Determine whether the socket is at the out-of-band data mark.
 402  /**
 403   * This function is used to check whether the socket input is currently
 404   * positioned at the out-of-band data mark.
 405   *
 406   * @return A bool indicating whether the socket is at the out-of-band data
 407   * mark.
 408   *
 409   * @throws boost::system::system_error Thrown on failure.
 410   */
 411  bool at_mark() const
 412  {
 413    boost::system::error_code ec;
 414    bool b = this->service.at_mark(this->implementation, ec);
 415    boost::asio::detail::throw_error(ec);
 416    return b;
 417  }
 418
 419  /// Determine whether the socket is at the out-of-band data mark.
 420  /**
 421   * This function is used to check whether the socket input is currently
 422   * positioned at the out-of-band data mark.
 423   *
 424   * @param ec Set to indicate what error occurred, if any.
 425   *
 426   * @return A bool indicating whether the socket is at the out-of-band data
 427   * mark.
 428   */
 429  bool at_mark(boost::system::error_code& ec) const
 430  {
 431    return this->service.at_mark(this->implementation, ec);
 432  }
 433
 434  /// Determine the number of bytes available for reading.
 435  /**
 436   * This function is used to determine the number of bytes that may be read
 437   * without blocking.
 438   *
 439   * @return The number of bytes that may be read without blocking, or 0 if an
 440   * error occurs.
 441   *
 442   * @throws boost::system::system_error Thrown on failure.
 443   */
 444  std::size_t available() const
 445  {
 446    boost::system::error_code ec;
 447    std::size_t s = this->service.available(this->implementation, ec);
 448    boost::asio::detail::throw_error(ec);
 449    return s;
 450  }
 451
 452  /// Determine the number of bytes available for reading.
 453  /**
 454   * This function is used to determine the number of bytes that may be read
 455   * without blocking.
 456   *
 457   * @param ec Set to indicate what error occurred, if any.
 458   *
 459   * @return The number of bytes that may be read without blocking, or 0 if an
 460   * error occurs.
 461   */
 462  std::size_t available(boost::system::error_code& ec) const
 463  {
 464    return this->service.available(this->implementation, ec);
 465  }
 466
 467  /// Bind the socket to the given local endpoint.
 468  /**
 469   * This function binds the socket to the specified endpoint on the local
 470   * machine.
 471   *
 472   * @param endpoint An endpoint on the local machine to which the socket will
 473   * be bound.
 474   *
 475   * @throws boost::system::system_error Thrown on failure.
 476   *
 477   * @par Example
 478   * @code
 479   * boost::asio::ip::tcp::socket socket(io_service);
 480   * socket.open(boost::asio::ip::tcp::v4());
 481   * socket.bind(boost::asio::ip::tcp::endpoint(
 482   *       boost::asio::ip::tcp::v4(), 12345));
 483   * @endcode
 484   */
 485  void bind(const endpoint_type& endpoint)
 486  {
 487    boost::system::error_code ec;
 488    this->service.bind(this->implementation, endpoint, ec);
 489    boost::asio::detail::throw_error(ec);
 490  }
 491
 492  /// Bind the socket to the given local endpoint.
 493  /**
 494   * This function binds the socket to the specified endpoint on the local
 495   * machine.
 496   *
 497   * @param endpoint An endpoint on the local machine to which the socket will
 498   * be bound.
 499   *
 500   * @param ec Set to indicate what error occurred, if any.
 501   *
 502   * @par Example
 503   * @code
 504   * boost::asio::ip::tcp::socket socket(io_service);
 505   * socket.open(boost::asio::ip::tcp::v4());
 506   * boost::system::error_code ec;
 507   * socket.bind(boost::asio::ip::tcp::endpoint(
 508   *       boost::asio::ip::tcp::v4(), 12345), ec);
 509   * if (ec)
 510   * {
 511   *   // An error occurred.
 512   * }
 513   * @endcode
 514   */
 515  boost::system::error_code bind(const endpoint_type& endpoint,
 516      boost::system::error_code& ec)
 517  {
 518    return this->service.bind(this->implementation, endpoint, ec);
 519  }
 520
 521  /// Connect the socket to the specified endpoint.
 522  /**
 523   * This function is used to connect a socket to the specified remote endpoint.
 524   * The function call will block until the connection is successfully made or
 525   * an error occurs.
 526   *
 527   * The socket is automatically opened if it is not already open. If the
 528   * connect fails, and the socket was automatically opened, the socket is
 529   * not returned to the closed state.
 530   *
 531   * @param peer_endpoint The remote endpoint to which the socket will be
 532   * connected.
 533   *
 534   * @throws boost::system::system_error Thrown on failure.
 535   *
 536   * @par Example
 537   * @code
 538   * boost::asio::ip::tcp::socket socket(io_service);
 539   * boost::asio::ip::tcp::endpoint endpoint(
 540   *     boost::asio::ip::address::from_string("1.2.3.4"), 12345);
 541   * socket.connect(endpoint);
 542   * @endcode
 543   */
 544  void connect(const endpoint_type& peer_endpoint)
 545  {
 546    boost::system::error_code ec;
 547    if (!is_open())
 548    {
 549      this->service.open(this->implementation, peer_endpoint.protocol(), ec);
 550      boost::asio::detail::throw_error(ec);
 551    }
 552    this->service.connect(this->implementation, peer_endpoint, ec);
 553    boost::asio::detail::throw_error(ec);
 554  }
 555
 556  /// Connect the socket to the specified endpoint.
 557  /**
 558   * This function is used to connect a socket to the specified remote endpoint.
 559   * The function call will block until the connection is successfully made or
 560   * an error occurs.
 561   *
 562   * The socket is automatically opened if it is not already open. If the
 563   * connect fails, and the socket was automatically opened, the socket is
 564   * not returned to the closed state.
 565   *
 566   * @param peer_endpoint The remote endpoint to which the socket will be
 567   * connected.
 568   *
 569   * @param ec Set to indicate what error occurred, if any.
 570   *
 571   * @par Example
 572   * @code
 573   * boost::asio::ip::tcp::socket socket(io_service);
 574   * boost::asio::ip::tcp::endpoint endpoint(
 575   *     boost::asio::ip::address::from_string("1.2.3.4"), 12345);
 576   * boost::system::error_code ec;
 577   * socket.connect(endpoint, ec);
 578   * if (ec)
 579   * {
 580   *   // An error occurred.
 581   * }
 582   * @endcode
 583   */
 584  boost::system::error_code connect(const endpoint_type& peer_endpoint,
 585      boost::system::error_code& ec)
 586  {
 587    if (!is_open())
 588    {
 589      if (this->service.open(this->implementation,
 590            peer_endpoint.protocol(), ec))
 591      {
 592        return ec;
 593      }
 594    }
 595
 596    return this->service.connect(this->implementation, peer_endpoint, ec);
 597  }
 598
 599  /// Start an asynchronous connect.
 600  /**
 601   * This function is used to asynchronously connect a socket to the specified
 602   * remote endpoint. The function call always returns immediately.
 603   *
 604   * The socket is automatically opened if it is not already open. If the
 605   * connect fails, and the socket was automatically opened, the socket is
 606   * not returned to the closed state.
 607   *
 608   * @param peer_endpoint The remote endpoint to which the socket will be
 609   * connected. Copies will be made of the endpoint object as required.
 610   *
 611   * @param handler The handler to be called when the connection operation
 612   * completes. Copies will be made of the handler as required. The function
 613   * signature of the handler must be:
 614   * @code void handler(
 615   *   const boost::system::error_code& error // Result of operation
 616   * ); @endcode
 617   * Regardless of whether the asynchronous operation completes immediately or
 618   * not, the handler will not be invoked from within this function. Invocation
 619   * of the handler will be performed in a manner equivalent to using
 620   * boost::asio::io_service::post().
 621   *
 622   * @par Example
 623   * @code
 624   * void connect_handler(const boost::system::error_code& error)
 625   * {
 626   *   if (!error)
 627   *   {
 628   *     // Connect succeeded.
 629   *   }
 630   * }
 631   *
 632   * ...
 633   *
 634   * boost::asio::ip::tcp::socket socket(io_service);
 635   * boost::asio::ip::tcp::endpoint endpoint(
 636   *     boost::asio::ip::address::from_string("1.2.3.4"), 12345);
 637   * socket.async_connect(endpoint, connect_handler);
 638   * @endcode
 639   */
 640  template <typename ConnectHandler>
 641  void async_connect(const endpoint_type& peer_endpoint, ConnectHandler handler)
 642  {
 643    if (!is_open())
 644    {
 645      boost::system::error_code ec;
 646      if (this->service.open(this->implementation,
 647            peer_endpoint.protocol(), ec))
 648      {
 649        this->get_io_service().post(
 650            boost::asio::detail::bind_handler(handler, ec));
 651        return;
 652      }
 653    }
 654
 655    this->service.async_connect(this->implementation, peer_endpoint, handler);
 656  }
 657
 658  /// Set an option on the socket.
 659  /**
 660   * This function is used to set an option on the socket.
 661   *
 662   * @param option The new option value to be set on the socket.
 663   *
 664   * @throws boost::system::system_error Thrown on failure.
 665   *
 666   * @sa SettableSocketOption @n
 667   * boost::asio::socket_base::broadcast @n
 668   * boost::asio::socket_base::do_not_route @n
 669   * boost::asio::socket_base::keep_alive @n
 670   * boost::asio::socket_base::linger @n
 671   * boost::asio::socket_base::receive_buffer_size @n
 672   * boost::asio::socket_base::receive_low_watermark @n
 673   * boost::asio::socket_base::reuse_address @n
 674   * boost::asio::socket_base::send_buffer_size @n
 675   * boost::asio::socket_base::send_low_watermark @n
 676   * boost::asio::ip::multicast::join_group @n
 677   * boost::asio::ip::multicast::leave_group @n
 678   * boost::asio::ip::multicast::enable_loopback @n
 679   * boost::asio::ip::multicast::outbound_interface @n
 680   * boost::asio::ip::multicast::hops @n
 681   * boost::asio::ip::tcp::no_delay
 682   *
 683   * @par Example
 684   * Setting the IPPROTO_TCP/TCP_NODELAY option:
 685   * @code
 686   * boost::asio::ip::tcp::socket socket(io_service);
 687   * ...
 688   * boost::asio::ip::tcp::no_delay option(true);
 689   * socket.set_option(option);
 690   * @endcode
 691   */
 692  template <typename SettableSocketOption>
 693  void set_option(const SettableSocketOption& option)
 694  {
 695    boost::system::error_code ec;
 696    this->service.set_option(this->implementation, option, ec);
 697    boost::asio::detail::throw_error(ec);
 698  }
 699
 700  /// Set an option on the socket.
 701  /**
 702   * This function is used to set an option on the socket.
 703   *
 704   * @param option The new option value to be set on the socket.
 705   *
 706   * @param ec Set to indicate what error occurred, if any.
 707   *
 708   * @sa SettableSocketOption @n
 709   * boost::asio::socket_base::broadcast @n
 710   * boost::asio::socket_base::do_not_route @n
 711   * boost::asio::socket_base::keep_alive @n
 712   * boost::asio::socket_base::linger @n
 713   * boost::asio::socket_base::receive_buffer_size @n
 714   * boost::asio::socket_base::receive_low_watermark @n
 715   * boost::asio::socket_base::reuse_address @n
 716   * boost::asio::socket_base::send_buffer_size @n
 717   * boost::asio::socket_base::send_low_watermark @n
 718   * boost::asio::ip::multicast::join_group @n
 719   * boost::asio::ip::multicast::leave_group @n
 720   * boost::asio::ip::multicast::enable_loopback @n
 721   * boost::asio::ip::multicast::outbound_interface @n
 722   * boost::asio::ip::multicast::hops @n
 723   * boost::asio::ip::tcp::no_delay
 724   *
 725   * @par Example
 726   * Setting the IPPROTO_TCP/TCP_NODELAY option:
 727   * @code
 728   * boost::asio::ip::tcp::socket socket(io_service);
 729   * ...
 730   * boost::asio::ip::tcp::no_delay option(true);
 731   * boost::system::error_code ec;
 732   * socket.set_option(option, ec);
 733   * if (ec)
 734   * {
 735   *   // An error occurred.
 736   * }
 737   * @endcode
 738   */
 739  template <typename SettableSocketOption>
 740  boost::system::error_code set_option(const SettableSocketOption& option,
 741      boost::system::error_code& ec)
 742  {
 743    return this->service.set_option(this->implementation, option, ec);
 744  }
 745
 746  /// Get an option from the socket.
 747  /**
 748   * This function is used to get the current value of an option on the socket.
 749   *
 750   * @param option The option value to be obtained from the socket.
 751   *
 752   * @throws boost::system::system_error Thrown on failure.
 753   *
 754   * @sa GettableSocketOption @n
 755   * boost::asio::socket_base::broadcast @n
 756   * boost::asio::socket_base::do_not_route @n
 757   * boost::asio::socket_base::keep_alive @n
 758   * boost::asio::socket_base::linger @n
 759   * boost::asio::socket_base::receive_buffer_size @n
 760   * boost::asio::socket_base::receive_low_watermark @n
 761   * boost::asio::socket_base::reuse_address @n
 762   * boost::asio::socket_base::send_buffer_size @n
 763   * boost::asio::socket_base::send_low_watermark @n
 764   * boost::asio::ip::multicast::join_group @n
 765   * boost::asio::ip::multicast::leave_group @n
 766   * boost::asio::ip::multicast::enable_loopback @n
 767   * boost::asio::ip::multicast::outbound_interface @n
 768   * boost::asio::ip::multicast::hops @n
 769   * boost::asio::ip::tcp::no_delay
 770   *
 771   * @par Example
 772   * Getting the value of the SOL_SOCKET/SO_KEEPALIVE option:
 773   * @code
 774   * boost::asio::ip::tcp::socket socket(io_service);
 775   * ...
 776   * boost::asio::ip::tcp::socket::keep_alive option;
 777   * socket.get_option(option);
 778   * bool is_set = option.get();
 779   * @endcode
 780   */
 781  template <typename GettableSocketOption>
 782  void get_option(GettableSocketOption& option) const
 783  {
 784    boost::system::error_code ec;
 785    this->service.get_option(this->implementation, option, ec);
 786    boost::asio::detail::throw_error(ec);
 787  }
 788
 789  /// Get an option from the socket.
 790  /**
 791   * This function is used to get the current value of an option on the socket.
 792   *
 793   * @param option The option value to be obtained from the socket.
 794   *
 795   * @param ec Set to indicate what error occurred, if any.
 796   *
 797   * @sa GettableSocketOption @n
 798   * boost::asio::socket_base::broadcast @n
 799   * boost::asio::socket_base::do_not_route @n
 800   * boost::asio::socket_base::keep_alive @n
 801   * boost::asio::socket_base::linger @n
 802   * boost::asio::socket_base::receive_buffer_size @n
 803   * boost::asio::socket_base::receive_low_watermark @n
 804   * boost::asio::socket_base::reuse_address @n
 805   * boost::asio::socket_base::send_buffer_size @n
 806   * boost::asio::socket_base::send_low_watermark @n
 807   * boost::asio::ip::multicast::join_group @n
 808   * boost::asio::ip::multicast::leave_group @n
 809   * boost::asio::ip::multicast::enable_loopback @n
 810   * boost::asio::ip::multicast::outbound_interface @n
 811   * boost::asio::ip::multicast::hops @n
 812   * boost::asio::ip::tcp::no_delay
 813   *
 814   * @par Example
 815   * Getting the value of the SOL_SOCKET/SO_KEEPALIVE option:
 816   * @code
 817   * boost::asio::ip::tcp::socket socket(io_service);
 818   * ...
 819   * boost::asio::ip::tcp::socket::keep_alive option;
 820   * boost::system::error_code ec;
 821   * socket.get_option(option, ec);
 822   * if (ec)
 823   * {
 824   *   // An error occurred.
 825   * }
 826   * bool is_set = option.get();
 827   * @endcode
 828   */
 829  template <typename GettableSocketOption>
 830  boost::system::error_code get_option(GettableSocketOption& option,
 831      boost::system::error_code& ec) const
 832  {
 833    return this->service.get_option(this->implementation, option, ec);
 834  }
 835
 836  /// Perform an IO control command on the socket.
 837  /**
 838   * This function is used to execute an IO control command on the socket.
 839   *
 840   * @param command The IO control command to be performed on the socket.
 841   *
 842   * @throws boost::system::system_error Thrown on failure.
 843   *
 844   * @sa IoControlCommand @n
 845   * boost::asio::socket_base::bytes_readable @n
 846   * boost::asio::socket_base::non_blocking_io
 847   *
 848   * @par Example
 849   * Getting the number of bytes ready to read:
 850   * @code
 851   * boost::asio::ip::tcp::socket socket(io_service);
 852   * ...
 853   * boost::asio::ip::tcp::socket::bytes_readable command;
 854   * socket.io_control(command);
 855   * std::size_t bytes_readable = command.get();
 856   * @endcode
 857   */
 858  template <typename IoControlCommand>
 859  void io_control(IoControlCommand& command)
 860  {
 861    boost::system::error_code ec;
 862    this->service.io_control(this->implementation, command, ec);
 863    boost::asio::detail::throw_error(ec);
 864  }
 865
 866  /// Perform an IO control command on the socket.
 867  /**
 868   * This function is used to execute an IO control command on the socket.
 869   *
 870   * @param command The IO control command to be performed on the socket.
 871   *
 872   * @param ec Set to indicate what error occurred, if any.
 873   *
 874   * @sa IoControlCommand @n
 875   * boost::asio::socket_base::bytes_readable @n
 876   * boost::asio::socket_base::non_blocking_io
 877   *
 878   * @par Example
 879   * Getting the number of bytes ready to read:
 880   * @code
 881   * boost::asio::ip::tcp::socket socket(io_service);
 882   * ...
 883   * boost::asio::ip::tcp::socket::bytes_readable command;
 884   * boost::system::error_code ec;
 885   * socket.io_control(command, ec);
 886   * if (ec)
 887   * {
 888   *   // An error occurred.
 889   * }
 890   * std::size_t bytes_readable = command.get();
 891   * @endcode
 892   */
 893  template <typename IoControlCommand>
 894  boost::system::error_code io_control(IoControlCommand& command,
 895      boost::system::error_code& ec)
 896  {
 897    return this->service.io_control(this->implementation, command, ec);
 898  }
 899
 900  /// Get the local endpoint of the socket.
 901  /**
 902   * This function is used to obtain the locally bound endpoint of the socket.
 903   *
 904   * @returns An object that represents the local endpoint of the socket.
 905   *
 906   * @throws boost::system::system_error Thrown on failure.
 907   *
 908   * @par Example
 909   * @code
 910   * boost::asio::ip::tcp::socket socket(io_service);
 911   * ...
 912   * boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint();
 913   * @endcode
 914   */
 915  endpoint_type local_endpoint() const
 916  {
 917    boost::system::error_code ec;
 918    endpoint_type ep = this->service.local_endpoint(this->implementation, ec);
 919    boost::asio::detail::throw_error(ec);
 920    return ep;
 921  }
 922
 923  /// Get the local endpoint of the socket.
 924  /**
 925   * This function is used to obtain the locally bound endpoint of the socket.
 926   *
 927   * @param ec Set to indicate what error occurred, if any.
 928   *
 929   * @returns An object that represents the local endpoint of the socket.
 930   * Returns a default-constructed endpoint object if an error occurred.
 931   *
 932   * @par Example
 933   * @code
 934   * boost::asio::ip::tcp::socket socket(io_service);
 935   * ...
 936   * boost::system::error_code ec;
 937   * boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint(ec);
 938   * if (ec)
 939   * {
 940   *   // An error occurred.
 941   * }
 942   * @endcode
 943   */
 944  endpoint_type local_endpoint(boost::system::error_code& ec) const
 945  {
 946    return this->service.local_endpoint(this->implementation, ec);
 947  }
 948
 949  /// Get the remote endpoint of the socket.
 950  /**
 951   * This function is used to obtain the remote endpoint of the socket.
 952   *
 953   * @returns An object that represents the remote endpoint of the socket.
 954   *
 955   * @throws boost::system::system_error Thrown on failure.
 956   *
 957   * @par Example
 958   * @code
 959   * boost::asio::ip::tcp::socket socket(io_service);
 960   * ...
 961   * boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint();
 962   * @endcode
 963   */
 964  endpoint_type remote_endpoint() const
 965  {
 966    boost::system::error_code ec;
 967    endpoint_type ep = this->service.remote_endpoint(this->implementation, ec);
 968    boost::asio::detail::throw_error(ec);
 969    return ep;
 970  }
 971
 972  /// Get the remote endpoint of the socket.
 973  /**
 974   * This function is used to obtain the remote endpoint of the socket.
 975   *
 976   * @param ec Set to indicate what error occurred, if any.
 977   *
 978   * @returns An object that represents the remote endpoint of the socket.
 979   * Returns a default-constructed endpoint object if an error occurred.
 980   *
 981   * @par Example
 982   * @code
 983   * boost::asio::ip::tcp::socket socket(io_service);
 984   * ...
 985   * boost::system::error_code ec;
 986   * boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint(ec);
 987   * if (ec)
 988   * {
 989   *   // An error occurred.
 990   * }
 991   * @endcode
 992   */
 993  endpoint_type remote_endpoint(boost::system::error_code& ec) const
 994  {
 995    return this->service.remote_endpoint(this->implementation, ec);
 996  }
 997
 998  /// Disable sends or receives on the socket.
 999  /**
1000   * This function is used to disable send operations, receive operations, or
1001   * both.
1002   *
1003   * @param what Determines what types of operation will no longer be allowed.
1004   *
1005   * @throws boost::system::system_error Thrown on failure.
1006   *
1007   * @par Example
1008   * Shutting down the send side of the socket:
1009   * @code
1010   * boost::asio::ip::tcp::socket socket(io_service);
1011   * ...
1012   * socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send);
1013   * @endcode
1014   */
1015  void shutdown(shutdown_type what)
1016  {
1017    boost::system::error_code ec;
1018    this->service.shutdown(this->implementation, what, ec);
1019    boost::asio::detail::throw_error(ec);
1020  }
1021
1022  /// Disable sends or receives on the socket.
1023  /**
1024   * This function is used to disable send operations, receive operations, or
1025   * both.
1026   *
1027   * @param what Determines what types of operation will no longer be allowed.
1028   *
1029   * @param ec Set to indicate what error occurred, if any.
1030   *
1031   * @par Example
1032   * Shutting down the send side of the socket:
1033   * @code
1034   * boost::asio::ip::tcp::socket socket(io_service);
1035   * ...
1036   * boost::system::error_code ec;
1037   * socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send, ec);
1038   * if (ec)
1039   * {
1040   *   // An error occurred.
1041   * }
1042   * @endcode
1043   */
1044  boost::system::error_code shutdown(shutdown_type what,
1045      boost::system::error_code& ec)
1046  {
1047    return this->service.shutdown(this->implementation, what, ec);
1048  }
1049
1050protected:
1051  /// Protected destructor to prevent deletion through this type.
1052  ~basic_socket()
1053  {
1054  }
1055};
1056
1057} // namespace asio
1058} // namespace boost
1059
1060#include <boost/asio/detail/pop_options.hpp>
1061
1062#endif // BOOST_ASIO_BASIC_SOCKET_HPP