Chris@16: // Chris@16: // basic_socket.hpp Chris@16: // ~~~~~~~~~~~~~~~~ Chris@16: // Chris@101: // Copyright (c) 2003-2015 Christopher M. Kohlhoff (chris at kohlhoff dot com) Chris@16: // Chris@16: // Distributed under the Boost Software License, Version 1.0. (See accompanying Chris@16: // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Chris@16: // Chris@16: Chris@16: #ifndef BOOST_ASIO_BASIC_SOCKET_HPP Chris@16: #define BOOST_ASIO_BASIC_SOCKET_HPP Chris@16: Chris@16: #if defined(_MSC_VER) && (_MSC_VER >= 1200) Chris@16: # pragma once Chris@16: #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) Chris@16: Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: #include Chris@16: Chris@16: #include Chris@16: Chris@16: namespace boost { Chris@16: namespace asio { Chris@16: Chris@16: /// Provides socket functionality. Chris@16: /** Chris@16: * The basic_socket class template provides functionality that is common to both Chris@16: * stream-oriented and datagram-oriented sockets. Chris@16: * Chris@16: * @par Thread Safety Chris@16: * @e Distinct @e objects: Safe.@n Chris@16: * @e Shared @e objects: Unsafe. Chris@16: */ Chris@16: template Chris@16: class basic_socket Chris@16: : public basic_io_object, Chris@16: public socket_base Chris@16: { Chris@16: public: Chris@16: /// (Deprecated: Use native_handle_type.) The native representation of a Chris@16: /// socket. Chris@16: typedef typename SocketService::native_handle_type native_type; Chris@16: Chris@16: /// The native representation of a socket. Chris@16: typedef typename SocketService::native_handle_type native_handle_type; Chris@16: Chris@16: /// The protocol type. Chris@16: typedef Protocol protocol_type; Chris@16: Chris@16: /// The endpoint type. Chris@16: typedef typename Protocol::endpoint endpoint_type; Chris@16: Chris@16: /// A basic_socket is always the lowest layer. Chris@16: typedef basic_socket lowest_layer_type; Chris@16: Chris@16: /// Construct a basic_socket without opening it. Chris@16: /** Chris@16: * This constructor creates a socket without opening it. Chris@16: * Chris@16: * @param io_service The io_service object that the socket will use to Chris@16: * dispatch handlers for any asynchronous operations performed on the socket. Chris@16: */ Chris@16: explicit basic_socket(boost::asio::io_service& io_service) Chris@16: : basic_io_object(io_service) Chris@16: { Chris@16: } Chris@16: Chris@16: /// Construct and open a basic_socket. Chris@16: /** Chris@16: * This constructor creates and opens a socket. Chris@16: * Chris@16: * @param io_service The io_service object that the socket will use to Chris@16: * dispatch handlers for any asynchronous operations performed on the socket. Chris@16: * Chris@16: * @param protocol An object specifying protocol parameters to be used. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: */ Chris@16: basic_socket(boost::asio::io_service& io_service, Chris@16: const protocol_type& protocol) Chris@16: : basic_io_object(io_service) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().open(this->get_implementation(), protocol, ec); Chris@16: boost::asio::detail::throw_error(ec, "open"); Chris@16: } Chris@16: Chris@16: /// Construct a basic_socket, opening it and binding it to the given local Chris@16: /// endpoint. Chris@16: /** Chris@16: * This constructor creates a socket and automatically opens it bound to the Chris@16: * specified endpoint on the local machine. The protocol used is the protocol Chris@16: * associated with the given endpoint. Chris@16: * Chris@16: * @param io_service The io_service object that the socket will use to Chris@16: * dispatch handlers for any asynchronous operations performed on the socket. Chris@16: * Chris@16: * @param endpoint An endpoint on the local machine to which the socket will Chris@16: * be bound. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: */ Chris@16: basic_socket(boost::asio::io_service& io_service, Chris@16: const endpoint_type& endpoint) Chris@16: : basic_io_object(io_service) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: const protocol_type protocol = endpoint.protocol(); Chris@16: this->get_service().open(this->get_implementation(), protocol, ec); Chris@16: boost::asio::detail::throw_error(ec, "open"); Chris@16: this->get_service().bind(this->get_implementation(), endpoint, ec); Chris@16: boost::asio::detail::throw_error(ec, "bind"); Chris@16: } Chris@16: Chris@16: /// Construct a basic_socket on an existing native socket. Chris@16: /** Chris@16: * This constructor creates a socket object to hold an existing native socket. Chris@16: * Chris@16: * @param io_service The io_service object that the socket will use to Chris@16: * dispatch handlers for any asynchronous operations performed on the socket. Chris@16: * Chris@16: * @param protocol An object specifying protocol parameters to be used. Chris@16: * Chris@16: * @param native_socket A native socket. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: */ Chris@16: basic_socket(boost::asio::io_service& io_service, Chris@16: const protocol_type& protocol, const native_handle_type& native_socket) Chris@16: : basic_io_object(io_service) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().assign(this->get_implementation(), Chris@16: protocol, native_socket, ec); Chris@16: boost::asio::detail::throw_error(ec, "assign"); Chris@16: } Chris@16: Chris@16: #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION) Chris@16: /// Move-construct a basic_socket from another. Chris@16: /** Chris@16: * This constructor moves a socket from one object to another. Chris@16: * Chris@16: * @param other The other basic_socket object from which the move will Chris@16: * occur. Chris@16: * Chris@16: * @note Following the move, the moved-from object is in the same state as if Chris@16: * constructed using the @c basic_socket(io_service&) constructor. Chris@16: */ Chris@16: basic_socket(basic_socket&& other) Chris@16: : basic_io_object( Chris@16: BOOST_ASIO_MOVE_CAST(basic_socket)(other)) Chris@16: { Chris@16: } Chris@16: Chris@16: /// Move-assign a basic_socket from another. Chris@16: /** Chris@16: * This assignment operator moves a socket from one object to another. Chris@16: * Chris@16: * @param other The other basic_socket object from which the move will Chris@16: * occur. Chris@16: * Chris@16: * @note Following the move, the moved-from object is in the same state as if Chris@16: * constructed using the @c basic_socket(io_service&) constructor. Chris@16: */ Chris@16: basic_socket& operator=(basic_socket&& other) Chris@16: { Chris@16: basic_io_object::operator=( Chris@16: BOOST_ASIO_MOVE_CAST(basic_socket)(other)); Chris@16: return *this; Chris@16: } Chris@16: Chris@16: // All sockets have access to each other's implementations. Chris@16: template Chris@16: friend class basic_socket; Chris@16: Chris@16: /// Move-construct a basic_socket from a socket of another protocol type. Chris@16: /** Chris@16: * This constructor moves a socket from one object to another. Chris@16: * Chris@16: * @param other The other basic_socket object from which the move will Chris@16: * occur. Chris@16: * Chris@16: * @note Following the move, the moved-from object is in the same state as if Chris@16: * constructed using the @c basic_socket(io_service&) constructor. Chris@16: */ Chris@16: template Chris@16: basic_socket(basic_socket&& other, Chris@16: typename enable_if::value>::type* = 0) Chris@16: : basic_io_object(other.get_io_service()) Chris@16: { Chris@16: this->get_service().template converting_move_construct( Chris@16: this->get_implementation(), other.get_implementation()); Chris@16: } Chris@16: Chris@16: /// Move-assign a basic_socket from a socket of another protocol type. Chris@16: /** Chris@16: * This assignment operator moves a socket from one object to another. Chris@16: * Chris@16: * @param other The other basic_socket object from which the move will Chris@16: * occur. Chris@16: * Chris@16: * @note Following the move, the moved-from object is in the same state as if Chris@16: * constructed using the @c basic_socket(io_service&) constructor. Chris@16: */ Chris@16: template Chris@16: typename enable_if::value, Chris@16: basic_socket>::type& operator=( Chris@16: basic_socket&& other) Chris@16: { Chris@16: basic_socket tmp(BOOST_ASIO_MOVE_CAST2(basic_socket< Chris@16: Protocol1, SocketService1>)(other)); Chris@16: basic_io_object::operator=( Chris@16: BOOST_ASIO_MOVE_CAST(basic_socket)(tmp)); Chris@16: return *this; Chris@16: } Chris@16: #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION) Chris@16: Chris@16: /// Get a reference to the lowest layer. Chris@16: /** Chris@16: * This function returns a reference to the lowest layer in a stack of Chris@16: * layers. Since a basic_socket cannot contain any further layers, it simply Chris@16: * returns a reference to itself. Chris@16: * Chris@16: * @return A reference to the lowest layer in the stack of layers. Ownership Chris@16: * is not transferred to the caller. Chris@16: */ Chris@16: lowest_layer_type& lowest_layer() Chris@16: { Chris@16: return *this; Chris@16: } Chris@16: Chris@16: /// Get a const reference to the lowest layer. Chris@16: /** Chris@16: * This function returns a const reference to the lowest layer in a stack of Chris@16: * layers. Since a basic_socket cannot contain any further layers, it simply Chris@16: * returns a reference to itself. Chris@16: * Chris@16: * @return A const reference to the lowest layer in the stack of layers. Chris@16: * Ownership is not transferred to the caller. Chris@16: */ Chris@16: const lowest_layer_type& lowest_layer() const Chris@16: { Chris@16: return *this; Chris@16: } Chris@16: Chris@16: /// Open the socket using the specified protocol. Chris@16: /** Chris@16: * This function opens the socket so that it will use the specified protocol. Chris@16: * Chris@16: * @param protocol An object specifying protocol parameters to be used. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @par Example Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * socket.open(boost::asio::ip::tcp::v4()); Chris@16: * @endcode Chris@16: */ Chris@16: void open(const protocol_type& protocol = protocol_type()) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().open(this->get_implementation(), protocol, ec); Chris@16: boost::asio::detail::throw_error(ec, "open"); Chris@16: } Chris@16: Chris@16: /// Open the socket using the specified protocol. Chris@16: /** Chris@16: * This function opens the socket so that it will use the specified protocol. Chris@16: * Chris@16: * @param protocol An object specifying which protocol is to be used. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @par Example Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * boost::system::error_code ec; Chris@16: * socket.open(boost::asio::ip::tcp::v4(), ec); Chris@16: * if (ec) Chris@16: * { Chris@16: * // An error occurred. Chris@16: * } Chris@16: * @endcode Chris@16: */ Chris@16: boost::system::error_code open(const protocol_type& protocol, Chris@16: boost::system::error_code& ec) Chris@16: { Chris@16: return this->get_service().open(this->get_implementation(), protocol, ec); Chris@16: } Chris@16: Chris@16: /// Assign an existing native socket to the socket. Chris@16: /* Chris@16: * This function opens the socket to hold an existing native socket. Chris@16: * Chris@16: * @param protocol An object specifying which protocol is to be used. Chris@16: * Chris@16: * @param native_socket A native socket. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: */ Chris@16: void assign(const protocol_type& protocol, Chris@16: const native_handle_type& native_socket) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().assign(this->get_implementation(), Chris@16: protocol, native_socket, ec); Chris@16: boost::asio::detail::throw_error(ec, "assign"); Chris@16: } Chris@16: Chris@16: /// Assign an existing native socket to the socket. Chris@16: /* Chris@16: * This function opens the socket to hold an existing native socket. Chris@16: * Chris@16: * @param protocol An object specifying which protocol is to be used. Chris@16: * Chris@16: * @param native_socket A native socket. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: */ Chris@16: boost::system::error_code assign(const protocol_type& protocol, Chris@16: const native_handle_type& native_socket, boost::system::error_code& ec) Chris@16: { Chris@16: return this->get_service().assign(this->get_implementation(), Chris@16: protocol, native_socket, ec); Chris@16: } Chris@16: Chris@16: /// Determine whether the socket is open. Chris@16: bool is_open() const Chris@16: { Chris@16: return this->get_service().is_open(this->get_implementation()); Chris@16: } Chris@16: Chris@16: /// Close the socket. Chris@16: /** Chris@16: * This function is used to close the socket. Any asynchronous send, receive Chris@16: * or connect operations will be cancelled immediately, and will complete Chris@16: * with the boost::asio::error::operation_aborted error. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Note that, even if Chris@16: * the function indicates an error, the underlying descriptor is closed. Chris@16: * Chris@16: * @note For portable behaviour with respect to graceful closure of a Chris@16: * connected socket, call shutdown() before closing the socket. Chris@16: */ Chris@16: void close() Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().close(this->get_implementation(), ec); Chris@16: boost::asio::detail::throw_error(ec, "close"); Chris@16: } Chris@16: Chris@16: /// Close the socket. Chris@16: /** Chris@16: * This function is used to close the socket. Any asynchronous send, receive Chris@16: * or connect operations will be cancelled immediately, and will complete Chris@16: * with the boost::asio::error::operation_aborted error. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Note that, even if Chris@16: * the function indicates an error, the underlying descriptor is closed. Chris@16: * Chris@16: * @par Example Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * boost::system::error_code ec; Chris@16: * socket.close(ec); Chris@16: * if (ec) Chris@16: * { Chris@16: * // An error occurred. Chris@16: * } Chris@16: * @endcode Chris@16: * Chris@16: * @note For portable behaviour with respect to graceful closure of a Chris@16: * connected socket, call shutdown() before closing the socket. Chris@16: */ Chris@16: boost::system::error_code close(boost::system::error_code& ec) Chris@16: { Chris@16: return this->get_service().close(this->get_implementation(), ec); Chris@16: } Chris@16: Chris@16: /// (Deprecated: Use native_handle().) Get the native socket representation. Chris@16: /** Chris@16: * This function may be used to obtain the underlying representation of the Chris@16: * socket. This is intended to allow access to native socket functionality Chris@16: * that is not otherwise provided. Chris@16: */ Chris@16: native_type native() Chris@16: { Chris@16: return this->get_service().native_handle(this->get_implementation()); Chris@16: } Chris@16: Chris@16: /// Get the native socket representation. Chris@16: /** Chris@16: * This function may be used to obtain the underlying representation of the Chris@16: * socket. This is intended to allow access to native socket functionality Chris@16: * that is not otherwise provided. Chris@16: */ Chris@16: native_handle_type native_handle() Chris@16: { Chris@16: return this->get_service().native_handle(this->get_implementation()); Chris@16: } Chris@16: Chris@16: /// Cancel all asynchronous operations associated with the socket. Chris@16: /** Chris@16: * This function causes all outstanding asynchronous connect, send and receive Chris@16: * operations to finish immediately, and the handlers for cancelled operations Chris@16: * will be passed the boost::asio::error::operation_aborted error. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note Calls to cancel() will always fail with Chris@16: * boost::asio::error::operation_not_supported when run on Windows XP, Windows Chris@16: * Server 2003, and earlier versions of Windows, unless Chris@16: * BOOST_ASIO_ENABLE_CANCELIO is defined. However, the CancelIo function has Chris@16: * two issues that should be considered before enabling its use: Chris@16: * Chris@16: * @li It will only cancel asynchronous operations that were initiated in the Chris@16: * current thread. Chris@16: * Chris@16: * @li It can appear to complete without error, but the request to cancel the Chris@16: * unfinished operations may be silently ignored by the operating system. Chris@16: * Whether it works or not seems to depend on the drivers that are installed. Chris@16: * Chris@16: * For portable cancellation, consider using one of the following Chris@16: * alternatives: Chris@16: * Chris@16: * @li Disable asio's I/O completion port backend by defining Chris@16: * BOOST_ASIO_DISABLE_IOCP. Chris@16: * Chris@16: * @li Use the close() function to simultaneously cancel the outstanding Chris@16: * operations and close the socket. Chris@16: * Chris@16: * When running on Windows Vista, Windows Server 2008, and later, the Chris@16: * CancelIoEx function is always used. This function does not have the Chris@16: * problems described above. Chris@16: */ Chris@16: #if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1400) \ Chris@16: && (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0600) \ Chris@16: && !defined(BOOST_ASIO_ENABLE_CANCELIO) Chris@16: __declspec(deprecated("By default, this function always fails with " Chris@16: "operation_not_supported when used on Windows XP, Windows Server 2003, " Chris@16: "or earlier. Consult documentation for details.")) Chris@16: #endif Chris@16: void cancel() Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().cancel(this->get_implementation(), ec); Chris@16: boost::asio::detail::throw_error(ec, "cancel"); Chris@16: } Chris@16: Chris@16: /// Cancel all asynchronous operations associated with the socket. Chris@16: /** Chris@16: * This function causes all outstanding asynchronous connect, send and receive Chris@16: * operations to finish immediately, and the handlers for cancelled operations Chris@16: * will be passed the boost::asio::error::operation_aborted error. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @note Calls to cancel() will always fail with Chris@16: * boost::asio::error::operation_not_supported when run on Windows XP, Windows Chris@16: * Server 2003, and earlier versions of Windows, unless Chris@16: * BOOST_ASIO_ENABLE_CANCELIO is defined. However, the CancelIo function has Chris@16: * two issues that should be considered before enabling its use: Chris@16: * Chris@16: * @li It will only cancel asynchronous operations that were initiated in the Chris@16: * current thread. Chris@16: * Chris@16: * @li It can appear to complete without error, but the request to cancel the Chris@16: * unfinished operations may be silently ignored by the operating system. Chris@16: * Whether it works or not seems to depend on the drivers that are installed. Chris@16: * Chris@16: * For portable cancellation, consider using one of the following Chris@16: * alternatives: Chris@16: * Chris@16: * @li Disable asio's I/O completion port backend by defining Chris@16: * BOOST_ASIO_DISABLE_IOCP. Chris@16: * Chris@16: * @li Use the close() function to simultaneously cancel the outstanding Chris@16: * operations and close the socket. Chris@16: * Chris@16: * When running on Windows Vista, Windows Server 2008, and later, the Chris@16: * CancelIoEx function is always used. This function does not have the Chris@16: * problems described above. Chris@16: */ Chris@16: #if defined(BOOST_ASIO_MSVC) && (BOOST_ASIO_MSVC >= 1400) \ Chris@16: && (!defined(_WIN32_WINNT) || _WIN32_WINNT < 0x0600) \ Chris@16: && !defined(BOOST_ASIO_ENABLE_CANCELIO) Chris@16: __declspec(deprecated("By default, this function always fails with " Chris@16: "operation_not_supported when used on Windows XP, Windows Server 2003, " Chris@16: "or earlier. Consult documentation for details.")) Chris@16: #endif Chris@16: boost::system::error_code cancel(boost::system::error_code& ec) Chris@16: { Chris@16: return this->get_service().cancel(this->get_implementation(), ec); Chris@16: } Chris@16: Chris@16: /// Determine whether the socket is at the out-of-band data mark. Chris@16: /** Chris@16: * This function is used to check whether the socket input is currently Chris@16: * positioned at the out-of-band data mark. Chris@16: * Chris@16: * @return A bool indicating whether the socket is at the out-of-band data Chris@16: * mark. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: */ Chris@16: bool at_mark() const Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: bool b = this->get_service().at_mark(this->get_implementation(), ec); Chris@16: boost::asio::detail::throw_error(ec, "at_mark"); Chris@16: return b; Chris@16: } Chris@16: Chris@16: /// Determine whether the socket is at the out-of-band data mark. Chris@16: /** Chris@16: * This function is used to check whether the socket input is currently Chris@16: * positioned at the out-of-band data mark. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @return A bool indicating whether the socket is at the out-of-band data Chris@16: * mark. Chris@16: */ Chris@16: bool at_mark(boost::system::error_code& ec) const Chris@16: { Chris@16: return this->get_service().at_mark(this->get_implementation(), ec); Chris@16: } Chris@16: Chris@16: /// Determine the number of bytes available for reading. Chris@16: /** Chris@16: * This function is used to determine the number of bytes that may be read Chris@16: * without blocking. Chris@16: * Chris@16: * @return The number of bytes that may be read without blocking, or 0 if an Chris@16: * error occurs. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: */ Chris@16: std::size_t available() const Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: std::size_t s = this->get_service().available( Chris@16: this->get_implementation(), ec); Chris@16: boost::asio::detail::throw_error(ec, "available"); Chris@16: return s; Chris@16: } Chris@16: Chris@16: /// Determine the number of bytes available for reading. Chris@16: /** Chris@16: * This function is used to determine the number of bytes that may be read Chris@16: * without blocking. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @return The number of bytes that may be read without blocking, or 0 if an Chris@16: * error occurs. Chris@16: */ Chris@16: std::size_t available(boost::system::error_code& ec) const Chris@16: { Chris@16: return this->get_service().available(this->get_implementation(), ec); Chris@16: } Chris@16: Chris@16: /// Bind the socket to the given local endpoint. Chris@16: /** Chris@16: * This function binds the socket to the specified endpoint on the local Chris@16: * machine. Chris@16: * Chris@16: * @param endpoint An endpoint on the local machine to which the socket will Chris@16: * be bound. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @par Example Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * socket.open(boost::asio::ip::tcp::v4()); Chris@16: * socket.bind(boost::asio::ip::tcp::endpoint( Chris@16: * boost::asio::ip::tcp::v4(), 12345)); Chris@16: * @endcode Chris@16: */ Chris@16: void bind(const endpoint_type& endpoint) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().bind(this->get_implementation(), endpoint, ec); Chris@16: boost::asio::detail::throw_error(ec, "bind"); Chris@16: } Chris@16: Chris@16: /// Bind the socket to the given local endpoint. Chris@16: /** Chris@16: * This function binds the socket to the specified endpoint on the local Chris@16: * machine. Chris@16: * Chris@16: * @param endpoint An endpoint on the local machine to which the socket will Chris@16: * be bound. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @par Example Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * socket.open(boost::asio::ip::tcp::v4()); Chris@16: * boost::system::error_code ec; Chris@16: * socket.bind(boost::asio::ip::tcp::endpoint( Chris@16: * boost::asio::ip::tcp::v4(), 12345), ec); Chris@16: * if (ec) Chris@16: * { Chris@16: * // An error occurred. Chris@16: * } Chris@16: * @endcode Chris@16: */ Chris@16: boost::system::error_code bind(const endpoint_type& endpoint, Chris@16: boost::system::error_code& ec) Chris@16: { Chris@16: return this->get_service().bind(this->get_implementation(), endpoint, ec); Chris@16: } Chris@16: Chris@16: /// Connect the socket to the specified endpoint. Chris@16: /** Chris@16: * This function is used to connect a socket to the specified remote endpoint. Chris@16: * The function call will block until the connection is successfully made or Chris@16: * an error occurs. Chris@16: * Chris@16: * The socket is automatically opened if it is not already open. If the Chris@16: * connect fails, and the socket was automatically opened, the socket is Chris@16: * not returned to the closed state. Chris@16: * Chris@16: * @param peer_endpoint The remote endpoint to which the socket will be Chris@16: * connected. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @par Example Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * boost::asio::ip::tcp::endpoint endpoint( Chris@16: * boost::asio::ip::address::from_string("1.2.3.4"), 12345); Chris@16: * socket.connect(endpoint); Chris@16: * @endcode Chris@16: */ Chris@16: void connect(const endpoint_type& peer_endpoint) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: if (!is_open()) Chris@16: { Chris@16: this->get_service().open(this->get_implementation(), Chris@16: peer_endpoint.protocol(), ec); Chris@16: boost::asio::detail::throw_error(ec, "connect"); Chris@16: } Chris@16: this->get_service().connect(this->get_implementation(), peer_endpoint, ec); Chris@16: boost::asio::detail::throw_error(ec, "connect"); Chris@16: } Chris@16: Chris@16: /// Connect the socket to the specified endpoint. Chris@16: /** Chris@16: * This function is used to connect a socket to the specified remote endpoint. Chris@16: * The function call will block until the connection is successfully made or Chris@16: * an error occurs. Chris@16: * Chris@16: * The socket is automatically opened if it is not already open. If the Chris@16: * connect fails, and the socket was automatically opened, the socket is Chris@16: * not returned to the closed state. Chris@16: * Chris@16: * @param peer_endpoint The remote endpoint to which the socket will be Chris@16: * connected. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @par Example Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * boost::asio::ip::tcp::endpoint endpoint( Chris@16: * boost::asio::ip::address::from_string("1.2.3.4"), 12345); Chris@16: * boost::system::error_code ec; Chris@16: * socket.connect(endpoint, ec); Chris@16: * if (ec) Chris@16: * { Chris@16: * // An error occurred. Chris@16: * } Chris@16: * @endcode Chris@16: */ Chris@16: boost::system::error_code connect(const endpoint_type& peer_endpoint, Chris@16: boost::system::error_code& ec) Chris@16: { Chris@16: if (!is_open()) Chris@16: { Chris@16: if (this->get_service().open(this->get_implementation(), Chris@16: peer_endpoint.protocol(), ec)) Chris@16: { Chris@16: return ec; Chris@16: } Chris@16: } Chris@16: Chris@16: return this->get_service().connect( Chris@16: this->get_implementation(), peer_endpoint, ec); Chris@16: } Chris@16: Chris@16: /// Start an asynchronous connect. Chris@16: /** Chris@16: * This function is used to asynchronously connect a socket to the specified Chris@16: * remote endpoint. The function call always returns immediately. Chris@16: * Chris@16: * The socket is automatically opened if it is not already open. If the Chris@16: * connect fails, and the socket was automatically opened, the socket is Chris@16: * not returned to the closed state. Chris@16: * Chris@16: * @param peer_endpoint The remote endpoint to which the socket will be Chris@16: * connected. Copies will be made of the endpoint object as required. Chris@16: * Chris@16: * @param handler The handler to be called when the connection operation Chris@16: * completes. Copies will be made of the handler as required. The function Chris@16: * signature of the handler must be: Chris@16: * @code void handler( Chris@16: * const boost::system::error_code& error // Result of operation Chris@16: * ); @endcode Chris@16: * Regardless of whether the asynchronous operation completes immediately or Chris@16: * not, the handler will not be invoked from within this function. Invocation Chris@16: * of the handler will be performed in a manner equivalent to using Chris@16: * boost::asio::io_service::post(). Chris@16: * Chris@16: * @par Example Chris@16: * @code Chris@16: * void connect_handler(const boost::system::error_code& error) Chris@16: * { Chris@16: * if (!error) Chris@16: * { Chris@16: * // Connect succeeded. Chris@16: * } Chris@16: * } Chris@16: * Chris@16: * ... Chris@16: * Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * boost::asio::ip::tcp::endpoint endpoint( Chris@16: * boost::asio::ip::address::from_string("1.2.3.4"), 12345); Chris@16: * socket.async_connect(endpoint, connect_handler); Chris@16: * @endcode Chris@16: */ Chris@16: template Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ConnectHandler, Chris@16: void (boost::system::error_code)) Chris@16: async_connect(const endpoint_type& peer_endpoint, Chris@16: BOOST_ASIO_MOVE_ARG(ConnectHandler) handler) Chris@16: { Chris@16: // If you get an error on the following line it means that your handler does Chris@16: // not meet the documented type requirements for a ConnectHandler. Chris@16: BOOST_ASIO_CONNECT_HANDLER_CHECK(ConnectHandler, handler) type_check; Chris@16: Chris@16: if (!is_open()) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: const protocol_type protocol = peer_endpoint.protocol(); Chris@16: if (this->get_service().open(this->get_implementation(), protocol, ec)) Chris@16: { Chris@16: detail::async_result_init< Chris@16: ConnectHandler, void (boost::system::error_code)> init( Chris@16: BOOST_ASIO_MOVE_CAST(ConnectHandler)(handler)); Chris@16: Chris@16: this->get_io_service().post( Chris@16: boost::asio::detail::bind_handler( Chris@16: BOOST_ASIO_MOVE_CAST(BOOST_ASIO_HANDLER_TYPE( Chris@16: ConnectHandler, void (boost::system::error_code)))( Chris@16: init.handler), ec)); Chris@16: Chris@16: return init.result.get(); Chris@16: } Chris@16: } Chris@16: Chris@16: return this->get_service().async_connect(this->get_implementation(), Chris@16: peer_endpoint, BOOST_ASIO_MOVE_CAST(ConnectHandler)(handler)); Chris@16: } Chris@16: Chris@16: /// Set an option on the socket. Chris@16: /** Chris@16: * This function is used to set an option on the socket. Chris@16: * Chris@16: * @param option The new option value to be set on the socket. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @sa SettableSocketOption @n Chris@16: * boost::asio::socket_base::broadcast @n Chris@16: * boost::asio::socket_base::do_not_route @n Chris@16: * boost::asio::socket_base::keep_alive @n Chris@16: * boost::asio::socket_base::linger @n Chris@16: * boost::asio::socket_base::receive_buffer_size @n Chris@16: * boost::asio::socket_base::receive_low_watermark @n Chris@16: * boost::asio::socket_base::reuse_address @n Chris@16: * boost::asio::socket_base::send_buffer_size @n Chris@16: * boost::asio::socket_base::send_low_watermark @n Chris@16: * boost::asio::ip::multicast::join_group @n Chris@16: * boost::asio::ip::multicast::leave_group @n Chris@16: * boost::asio::ip::multicast::enable_loopback @n Chris@16: * boost::asio::ip::multicast::outbound_interface @n Chris@16: * boost::asio::ip::multicast::hops @n Chris@16: * boost::asio::ip::tcp::no_delay Chris@16: * Chris@16: * @par Example Chris@16: * Setting the IPPROTO_TCP/TCP_NODELAY option: Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * boost::asio::ip::tcp::no_delay option(true); Chris@16: * socket.set_option(option); Chris@16: * @endcode Chris@16: */ Chris@16: template Chris@16: void set_option(const SettableSocketOption& option) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().set_option(this->get_implementation(), option, ec); Chris@16: boost::asio::detail::throw_error(ec, "set_option"); Chris@16: } Chris@16: Chris@16: /// Set an option on the socket. Chris@16: /** Chris@16: * This function is used to set an option on the socket. Chris@16: * Chris@16: * @param option The new option value to be set on the socket. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @sa SettableSocketOption @n Chris@16: * boost::asio::socket_base::broadcast @n Chris@16: * boost::asio::socket_base::do_not_route @n Chris@16: * boost::asio::socket_base::keep_alive @n Chris@16: * boost::asio::socket_base::linger @n Chris@16: * boost::asio::socket_base::receive_buffer_size @n Chris@16: * boost::asio::socket_base::receive_low_watermark @n Chris@16: * boost::asio::socket_base::reuse_address @n Chris@16: * boost::asio::socket_base::send_buffer_size @n Chris@16: * boost::asio::socket_base::send_low_watermark @n Chris@16: * boost::asio::ip::multicast::join_group @n Chris@16: * boost::asio::ip::multicast::leave_group @n Chris@16: * boost::asio::ip::multicast::enable_loopback @n Chris@16: * boost::asio::ip::multicast::outbound_interface @n Chris@16: * boost::asio::ip::multicast::hops @n Chris@16: * boost::asio::ip::tcp::no_delay Chris@16: * Chris@16: * @par Example Chris@16: * Setting the IPPROTO_TCP/TCP_NODELAY option: Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * boost::asio::ip::tcp::no_delay option(true); Chris@16: * boost::system::error_code ec; Chris@16: * socket.set_option(option, ec); Chris@16: * if (ec) Chris@16: * { Chris@16: * // An error occurred. Chris@16: * } Chris@16: * @endcode Chris@16: */ Chris@16: template Chris@16: boost::system::error_code set_option(const SettableSocketOption& option, Chris@16: boost::system::error_code& ec) Chris@16: { Chris@16: return this->get_service().set_option( Chris@16: this->get_implementation(), option, ec); Chris@16: } Chris@16: Chris@16: /// Get an option from the socket. Chris@16: /** Chris@16: * This function is used to get the current value of an option on the socket. Chris@16: * Chris@16: * @param option The option value to be obtained from the socket. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @sa GettableSocketOption @n Chris@16: * boost::asio::socket_base::broadcast @n Chris@16: * boost::asio::socket_base::do_not_route @n Chris@16: * boost::asio::socket_base::keep_alive @n Chris@16: * boost::asio::socket_base::linger @n Chris@16: * boost::asio::socket_base::receive_buffer_size @n Chris@16: * boost::asio::socket_base::receive_low_watermark @n Chris@16: * boost::asio::socket_base::reuse_address @n Chris@16: * boost::asio::socket_base::send_buffer_size @n Chris@16: * boost::asio::socket_base::send_low_watermark @n Chris@16: * boost::asio::ip::multicast::join_group @n Chris@16: * boost::asio::ip::multicast::leave_group @n Chris@16: * boost::asio::ip::multicast::enable_loopback @n Chris@16: * boost::asio::ip::multicast::outbound_interface @n Chris@16: * boost::asio::ip::multicast::hops @n Chris@16: * boost::asio::ip::tcp::no_delay Chris@16: * Chris@16: * @par Example Chris@16: * Getting the value of the SOL_SOCKET/SO_KEEPALIVE option: Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * boost::asio::ip::tcp::socket::keep_alive option; Chris@16: * socket.get_option(option); Chris@16: * bool is_set = option.value(); Chris@16: * @endcode Chris@16: */ Chris@16: template Chris@16: void get_option(GettableSocketOption& option) const Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().get_option(this->get_implementation(), option, ec); Chris@16: boost::asio::detail::throw_error(ec, "get_option"); Chris@16: } Chris@16: Chris@16: /// Get an option from the socket. Chris@16: /** Chris@16: * This function is used to get the current value of an option on the socket. Chris@16: * Chris@16: * @param option The option value to be obtained from the socket. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @sa GettableSocketOption @n Chris@16: * boost::asio::socket_base::broadcast @n Chris@16: * boost::asio::socket_base::do_not_route @n Chris@16: * boost::asio::socket_base::keep_alive @n Chris@16: * boost::asio::socket_base::linger @n Chris@16: * boost::asio::socket_base::receive_buffer_size @n Chris@16: * boost::asio::socket_base::receive_low_watermark @n Chris@16: * boost::asio::socket_base::reuse_address @n Chris@16: * boost::asio::socket_base::send_buffer_size @n Chris@16: * boost::asio::socket_base::send_low_watermark @n Chris@16: * boost::asio::ip::multicast::join_group @n Chris@16: * boost::asio::ip::multicast::leave_group @n Chris@16: * boost::asio::ip::multicast::enable_loopback @n Chris@16: * boost::asio::ip::multicast::outbound_interface @n Chris@16: * boost::asio::ip::multicast::hops @n Chris@16: * boost::asio::ip::tcp::no_delay Chris@16: * Chris@16: * @par Example Chris@16: * Getting the value of the SOL_SOCKET/SO_KEEPALIVE option: Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * boost::asio::ip::tcp::socket::keep_alive option; Chris@16: * boost::system::error_code ec; Chris@16: * socket.get_option(option, ec); Chris@16: * if (ec) Chris@16: * { Chris@16: * // An error occurred. Chris@16: * } Chris@16: * bool is_set = option.value(); Chris@16: * @endcode Chris@16: */ Chris@16: template Chris@16: boost::system::error_code get_option(GettableSocketOption& option, Chris@16: boost::system::error_code& ec) const Chris@16: { Chris@16: return this->get_service().get_option( Chris@16: this->get_implementation(), option, ec); Chris@16: } Chris@16: Chris@16: /// Perform an IO control command on the socket. Chris@16: /** Chris@16: * This function is used to execute an IO control command on the socket. Chris@16: * Chris@16: * @param command The IO control command to be performed on the socket. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @sa IoControlCommand @n Chris@16: * boost::asio::socket_base::bytes_readable @n Chris@16: * boost::asio::socket_base::non_blocking_io Chris@16: * Chris@16: * @par Example Chris@16: * Getting the number of bytes ready to read: Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * boost::asio::ip::tcp::socket::bytes_readable command; Chris@16: * socket.io_control(command); Chris@16: * std::size_t bytes_readable = command.get(); Chris@16: * @endcode Chris@16: */ Chris@16: template Chris@16: void io_control(IoControlCommand& command) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().io_control(this->get_implementation(), command, ec); Chris@16: boost::asio::detail::throw_error(ec, "io_control"); Chris@16: } Chris@16: Chris@16: /// Perform an IO control command on the socket. Chris@16: /** Chris@16: * This function is used to execute an IO control command on the socket. Chris@16: * Chris@16: * @param command The IO control command to be performed on the socket. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @sa IoControlCommand @n Chris@16: * boost::asio::socket_base::bytes_readable @n Chris@16: * boost::asio::socket_base::non_blocking_io Chris@16: * Chris@16: * @par Example Chris@16: * Getting the number of bytes ready to read: Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * boost::asio::ip::tcp::socket::bytes_readable command; Chris@16: * boost::system::error_code ec; Chris@16: * socket.io_control(command, ec); Chris@16: * if (ec) Chris@16: * { Chris@16: * // An error occurred. Chris@16: * } Chris@16: * std::size_t bytes_readable = command.get(); Chris@16: * @endcode Chris@16: */ Chris@16: template Chris@16: boost::system::error_code io_control(IoControlCommand& command, Chris@16: boost::system::error_code& ec) Chris@16: { Chris@16: return this->get_service().io_control( Chris@16: this->get_implementation(), command, ec); Chris@16: } Chris@16: Chris@16: /// Gets the non-blocking mode of the socket. Chris@16: /** Chris@16: * @returns @c true if the socket's synchronous operations will fail with Chris@16: * boost::asio::error::would_block if they are unable to perform the requested Chris@16: * operation immediately. If @c false, synchronous operations will block Chris@16: * until complete. Chris@16: * Chris@16: * @note The non-blocking mode has no effect on the behaviour of asynchronous Chris@16: * operations. Asynchronous operations will never fail with the error Chris@16: * boost::asio::error::would_block. Chris@16: */ Chris@16: bool non_blocking() const Chris@16: { Chris@16: return this->get_service().non_blocking(this->get_implementation()); Chris@16: } Chris@16: Chris@16: /// Sets the non-blocking mode of the socket. Chris@16: /** Chris@16: * @param mode If @c true, the socket's synchronous operations will fail with Chris@16: * boost::asio::error::would_block if they are unable to perform the requested Chris@16: * operation immediately. If @c false, synchronous operations will block Chris@16: * until complete. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @note The non-blocking mode has no effect on the behaviour of asynchronous Chris@16: * operations. Asynchronous operations will never fail with the error Chris@16: * boost::asio::error::would_block. Chris@16: */ Chris@16: void non_blocking(bool mode) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().non_blocking(this->get_implementation(), mode, ec); Chris@16: boost::asio::detail::throw_error(ec, "non_blocking"); Chris@16: } Chris@16: Chris@16: /// Sets the non-blocking mode of the socket. Chris@16: /** Chris@16: * @param mode If @c true, the socket's synchronous operations will fail with Chris@16: * boost::asio::error::would_block if they are unable to perform the requested Chris@16: * operation immediately. If @c false, synchronous operations will block Chris@16: * until complete. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @note The non-blocking mode has no effect on the behaviour of asynchronous Chris@16: * operations. Asynchronous operations will never fail with the error Chris@16: * boost::asio::error::would_block. Chris@16: */ Chris@16: boost::system::error_code non_blocking( Chris@16: bool mode, boost::system::error_code& ec) Chris@16: { Chris@16: return this->get_service().non_blocking( Chris@16: this->get_implementation(), mode, ec); Chris@16: } Chris@16: Chris@16: /// Gets the non-blocking mode of the native socket implementation. Chris@16: /** Chris@16: * This function is used to retrieve the non-blocking mode of the underlying Chris@16: * native socket. This mode has no effect on the behaviour of the socket Chris@16: * object's synchronous operations. Chris@16: * Chris@16: * @returns @c true if the underlying socket is in non-blocking mode and Chris@16: * direct system calls may fail with boost::asio::error::would_block (or the Chris@16: * equivalent system error). Chris@16: * Chris@16: * @note The current non-blocking mode is cached by the socket object. Chris@16: * Consequently, the return value may be incorrect if the non-blocking mode Chris@16: * was set directly on the native socket. Chris@16: * Chris@16: * @par Example Chris@16: * This function is intended to allow the encapsulation of arbitrary Chris@16: * non-blocking system calls as asynchronous operations, in a way that is Chris@16: * transparent to the user of the socket object. The following example Chris@16: * illustrates how Linux's @c sendfile system call might be encapsulated: Chris@16: * @code template Chris@16: * struct sendfile_op Chris@16: * { Chris@16: * tcp::socket& sock_; Chris@16: * int fd_; Chris@16: * Handler handler_; Chris@16: * off_t offset_; Chris@16: * std::size_t total_bytes_transferred_; Chris@16: * Chris@16: * // Function call operator meeting WriteHandler requirements. Chris@16: * // Used as the handler for the async_write_some operation. Chris@16: * void operator()(boost::system::error_code ec, std::size_t) Chris@16: * { Chris@16: * // Put the underlying socket into non-blocking mode. Chris@16: * if (!ec) Chris@16: * if (!sock_.native_non_blocking()) Chris@16: * sock_.native_non_blocking(true, ec); Chris@16: * Chris@16: * if (!ec) Chris@16: * { Chris@16: * for (;;) Chris@16: * { Chris@16: * // Try the system call. Chris@16: * errno = 0; Chris@16: * int n = ::sendfile(sock_.native_handle(), fd_, &offset_, 65536); Chris@16: * ec = boost::system::error_code(n < 0 ? errno : 0, Chris@16: * boost::asio::error::get_system_category()); Chris@16: * total_bytes_transferred_ += ec ? 0 : n; Chris@16: * Chris@16: * // Retry operation immediately if interrupted by signal. Chris@16: * if (ec == boost::asio::error::interrupted) Chris@16: * continue; Chris@16: * Chris@16: * // Check if we need to run the operation again. Chris@16: * if (ec == boost::asio::error::would_block Chris@16: * || ec == boost::asio::error::try_again) Chris@16: * { Chris@16: * // We have to wait for the socket to become ready again. Chris@16: * sock_.async_write_some(boost::asio::null_buffers(), *this); Chris@16: * return; Chris@16: * } Chris@16: * Chris@16: * if (ec || n == 0) Chris@16: * { Chris@16: * // An error occurred, or we have reached the end of the file. Chris@16: * // Either way we must exit the loop so we can call the handler. Chris@16: * break; Chris@16: * } Chris@16: * Chris@16: * // Loop around to try calling sendfile again. Chris@16: * } Chris@16: * } Chris@16: * Chris@16: * // Pass result back to user's handler. Chris@16: * handler_(ec, total_bytes_transferred_); Chris@16: * } Chris@16: * }; Chris@16: * Chris@16: * template Chris@16: * void async_sendfile(tcp::socket& sock, int fd, Handler h) Chris@16: * { Chris@16: * sendfile_op op = { sock, fd, h, 0, 0 }; Chris@16: * sock.async_write_some(boost::asio::null_buffers(), op); Chris@16: * } @endcode Chris@16: */ Chris@16: bool native_non_blocking() const Chris@16: { Chris@16: return this->get_service().native_non_blocking(this->get_implementation()); Chris@16: } Chris@16: Chris@16: /// Sets the non-blocking mode of the native socket implementation. Chris@16: /** Chris@16: * This function is used to modify the non-blocking mode of the underlying Chris@16: * native socket. It has no effect on the behaviour of the socket object's Chris@16: * synchronous operations. Chris@16: * Chris@16: * @param mode If @c true, the underlying socket is put into non-blocking Chris@16: * mode and direct system calls may fail with boost::asio::error::would_block Chris@16: * (or the equivalent system error). Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. If the @c mode is Chris@16: * @c false, but the current value of @c non_blocking() is @c true, this Chris@16: * function fails with boost::asio::error::invalid_argument, as the Chris@16: * combination does not make sense. Chris@16: * Chris@16: * @par Example Chris@16: * This function is intended to allow the encapsulation of arbitrary Chris@16: * non-blocking system calls as asynchronous operations, in a way that is Chris@16: * transparent to the user of the socket object. The following example Chris@16: * illustrates how Linux's @c sendfile system call might be encapsulated: Chris@16: * @code template Chris@16: * struct sendfile_op Chris@16: * { Chris@16: * tcp::socket& sock_; Chris@16: * int fd_; Chris@16: * Handler handler_; Chris@16: * off_t offset_; Chris@16: * std::size_t total_bytes_transferred_; Chris@16: * Chris@16: * // Function call operator meeting WriteHandler requirements. Chris@16: * // Used as the handler for the async_write_some operation. Chris@16: * void operator()(boost::system::error_code ec, std::size_t) Chris@16: * { Chris@16: * // Put the underlying socket into non-blocking mode. Chris@16: * if (!ec) Chris@16: * if (!sock_.native_non_blocking()) Chris@16: * sock_.native_non_blocking(true, ec); Chris@16: * Chris@16: * if (!ec) Chris@16: * { Chris@16: * for (;;) Chris@16: * { Chris@16: * // Try the system call. Chris@16: * errno = 0; Chris@16: * int n = ::sendfile(sock_.native_handle(), fd_, &offset_, 65536); Chris@16: * ec = boost::system::error_code(n < 0 ? errno : 0, Chris@16: * boost::asio::error::get_system_category()); Chris@16: * total_bytes_transferred_ += ec ? 0 : n; Chris@16: * Chris@16: * // Retry operation immediately if interrupted by signal. Chris@16: * if (ec == boost::asio::error::interrupted) Chris@16: * continue; Chris@16: * Chris@16: * // Check if we need to run the operation again. Chris@16: * if (ec == boost::asio::error::would_block Chris@16: * || ec == boost::asio::error::try_again) Chris@16: * { Chris@16: * // We have to wait for the socket to become ready again. Chris@16: * sock_.async_write_some(boost::asio::null_buffers(), *this); Chris@16: * return; Chris@16: * } Chris@16: * Chris@16: * if (ec || n == 0) Chris@16: * { Chris@16: * // An error occurred, or we have reached the end of the file. Chris@16: * // Either way we must exit the loop so we can call the handler. Chris@16: * break; Chris@16: * } Chris@16: * Chris@16: * // Loop around to try calling sendfile again. Chris@16: * } Chris@16: * } Chris@16: * Chris@16: * // Pass result back to user's handler. Chris@16: * handler_(ec, total_bytes_transferred_); Chris@16: * } Chris@16: * }; Chris@16: * Chris@16: * template Chris@16: * void async_sendfile(tcp::socket& sock, int fd, Handler h) Chris@16: * { Chris@16: * sendfile_op op = { sock, fd, h, 0, 0 }; Chris@16: * sock.async_write_some(boost::asio::null_buffers(), op); Chris@16: * } @endcode Chris@16: */ Chris@16: void native_non_blocking(bool mode) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().native_non_blocking( Chris@16: this->get_implementation(), mode, ec); Chris@16: boost::asio::detail::throw_error(ec, "native_non_blocking"); Chris@16: } Chris@16: Chris@16: /// Sets the non-blocking mode of the native socket implementation. Chris@16: /** Chris@16: * This function is used to modify the non-blocking mode of the underlying Chris@16: * native socket. It has no effect on the behaviour of the socket object's Chris@16: * synchronous operations. Chris@16: * Chris@16: * @param mode If @c true, the underlying socket is put into non-blocking Chris@16: * mode and direct system calls may fail with boost::asio::error::would_block Chris@16: * (or the equivalent system error). Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. If the @c mode is Chris@16: * @c false, but the current value of @c non_blocking() is @c true, this Chris@16: * function fails with boost::asio::error::invalid_argument, as the Chris@16: * combination does not make sense. Chris@16: * Chris@16: * @par Example Chris@16: * This function is intended to allow the encapsulation of arbitrary Chris@16: * non-blocking system calls as asynchronous operations, in a way that is Chris@16: * transparent to the user of the socket object. The following example Chris@16: * illustrates how Linux's @c sendfile system call might be encapsulated: Chris@16: * @code template Chris@16: * struct sendfile_op Chris@16: * { Chris@16: * tcp::socket& sock_; Chris@16: * int fd_; Chris@16: * Handler handler_; Chris@16: * off_t offset_; Chris@16: * std::size_t total_bytes_transferred_; Chris@16: * Chris@16: * // Function call operator meeting WriteHandler requirements. Chris@16: * // Used as the handler for the async_write_some operation. Chris@16: * void operator()(boost::system::error_code ec, std::size_t) Chris@16: * { Chris@16: * // Put the underlying socket into non-blocking mode. Chris@16: * if (!ec) Chris@16: * if (!sock_.native_non_blocking()) Chris@16: * sock_.native_non_blocking(true, ec); Chris@16: * Chris@16: * if (!ec) Chris@16: * { Chris@16: * for (;;) Chris@16: * { Chris@16: * // Try the system call. Chris@16: * errno = 0; Chris@16: * int n = ::sendfile(sock_.native_handle(), fd_, &offset_, 65536); Chris@16: * ec = boost::system::error_code(n < 0 ? errno : 0, Chris@16: * boost::asio::error::get_system_category()); Chris@16: * total_bytes_transferred_ += ec ? 0 : n; Chris@16: * Chris@16: * // Retry operation immediately if interrupted by signal. Chris@16: * if (ec == boost::asio::error::interrupted) Chris@16: * continue; Chris@16: * Chris@16: * // Check if we need to run the operation again. Chris@16: * if (ec == boost::asio::error::would_block Chris@16: * || ec == boost::asio::error::try_again) Chris@16: * { Chris@16: * // We have to wait for the socket to become ready again. Chris@16: * sock_.async_write_some(boost::asio::null_buffers(), *this); Chris@16: * return; Chris@16: * } Chris@16: * Chris@16: * if (ec || n == 0) Chris@16: * { Chris@16: * // An error occurred, or we have reached the end of the file. Chris@16: * // Either way we must exit the loop so we can call the handler. Chris@16: * break; Chris@16: * } Chris@16: * Chris@16: * // Loop around to try calling sendfile again. Chris@16: * } Chris@16: * } Chris@16: * Chris@16: * // Pass result back to user's handler. Chris@16: * handler_(ec, total_bytes_transferred_); Chris@16: * } Chris@16: * }; Chris@16: * Chris@16: * template Chris@16: * void async_sendfile(tcp::socket& sock, int fd, Handler h) Chris@16: * { Chris@16: * sendfile_op op = { sock, fd, h, 0, 0 }; Chris@16: * sock.async_write_some(boost::asio::null_buffers(), op); Chris@16: * } @endcode Chris@16: */ Chris@16: boost::system::error_code native_non_blocking( Chris@16: bool mode, boost::system::error_code& ec) Chris@16: { Chris@16: return this->get_service().native_non_blocking( Chris@16: this->get_implementation(), mode, ec); Chris@16: } Chris@16: Chris@16: /// Get the local endpoint of the socket. Chris@16: /** Chris@16: * This function is used to obtain the locally bound endpoint of the socket. Chris@16: * Chris@16: * @returns An object that represents the local endpoint of the socket. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @par Example Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint(); Chris@16: * @endcode Chris@16: */ Chris@16: endpoint_type local_endpoint() const Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: endpoint_type ep = this->get_service().local_endpoint( Chris@16: this->get_implementation(), ec); Chris@16: boost::asio::detail::throw_error(ec, "local_endpoint"); Chris@16: return ep; Chris@16: } Chris@16: Chris@16: /// Get the local endpoint of the socket. Chris@16: /** Chris@16: * This function is used to obtain the locally bound endpoint of the socket. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @returns An object that represents the local endpoint of the socket. Chris@16: * Returns a default-constructed endpoint object if an error occurred. Chris@16: * Chris@16: * @par Example Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * boost::system::error_code ec; Chris@16: * boost::asio::ip::tcp::endpoint endpoint = socket.local_endpoint(ec); Chris@16: * if (ec) Chris@16: * { Chris@16: * // An error occurred. Chris@16: * } Chris@16: * @endcode Chris@16: */ Chris@16: endpoint_type local_endpoint(boost::system::error_code& ec) const Chris@16: { Chris@16: return this->get_service().local_endpoint(this->get_implementation(), ec); Chris@16: } Chris@16: Chris@16: /// Get the remote endpoint of the socket. Chris@16: /** Chris@16: * This function is used to obtain the remote endpoint of the socket. Chris@16: * Chris@16: * @returns An object that represents the remote endpoint of the socket. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @par Example Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint(); Chris@16: * @endcode Chris@16: */ Chris@16: endpoint_type remote_endpoint() const Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: endpoint_type ep = this->get_service().remote_endpoint( Chris@16: this->get_implementation(), ec); Chris@16: boost::asio::detail::throw_error(ec, "remote_endpoint"); Chris@16: return ep; Chris@16: } Chris@16: Chris@16: /// Get the remote endpoint of the socket. Chris@16: /** Chris@16: * This function is used to obtain the remote endpoint of the socket. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @returns An object that represents the remote endpoint of the socket. Chris@16: * Returns a default-constructed endpoint object if an error occurred. Chris@16: * Chris@16: * @par Example Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * boost::system::error_code ec; Chris@16: * boost::asio::ip::tcp::endpoint endpoint = socket.remote_endpoint(ec); Chris@16: * if (ec) Chris@16: * { Chris@16: * // An error occurred. Chris@16: * } Chris@16: * @endcode Chris@16: */ Chris@16: endpoint_type remote_endpoint(boost::system::error_code& ec) const Chris@16: { Chris@16: return this->get_service().remote_endpoint(this->get_implementation(), ec); Chris@16: } Chris@16: Chris@16: /// Disable sends or receives on the socket. Chris@16: /** Chris@16: * This function is used to disable send operations, receive operations, or Chris@16: * both. Chris@16: * Chris@16: * @param what Determines what types of operation will no longer be allowed. Chris@16: * Chris@16: * @throws boost::system::system_error Thrown on failure. Chris@16: * Chris@16: * @par Example Chris@16: * Shutting down the send side of the socket: Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send); Chris@16: * @endcode Chris@16: */ Chris@16: void shutdown(shutdown_type what) Chris@16: { Chris@16: boost::system::error_code ec; Chris@16: this->get_service().shutdown(this->get_implementation(), what, ec); Chris@16: boost::asio::detail::throw_error(ec, "shutdown"); Chris@16: } Chris@16: Chris@16: /// Disable sends or receives on the socket. Chris@16: /** Chris@16: * This function is used to disable send operations, receive operations, or Chris@16: * both. Chris@16: * Chris@16: * @param what Determines what types of operation will no longer be allowed. Chris@16: * Chris@16: * @param ec Set to indicate what error occurred, if any. Chris@16: * Chris@16: * @par Example Chris@16: * Shutting down the send side of the socket: Chris@16: * @code Chris@16: * boost::asio::ip::tcp::socket socket(io_service); Chris@16: * ... Chris@16: * boost::system::error_code ec; Chris@16: * socket.shutdown(boost::asio::ip::tcp::socket::shutdown_send, ec); Chris@16: * if (ec) Chris@16: * { Chris@16: * // An error occurred. Chris@16: * } Chris@16: * @endcode Chris@16: */ Chris@16: boost::system::error_code shutdown(shutdown_type what, Chris@16: boost::system::error_code& ec) Chris@16: { Chris@16: return this->get_service().shutdown(this->get_implementation(), what, ec); Chris@16: } Chris@16: Chris@16: protected: Chris@16: /// Protected destructor to prevent deletion through this type. Chris@16: ~basic_socket() Chris@16: { Chris@16: } Chris@16: }; Chris@16: Chris@16: } // namespace asio Chris@16: } // namespace boost Chris@16: Chris@16: #include Chris@16: Chris@16: #endif // BOOST_ASIO_BASIC_SOCKET_HPP