diff options
Diffstat (limited to 'boost/asio/connect.hpp')
| -rw-r--r-- | boost/asio/connect.hpp | 686 |
1 files changed, 461 insertions, 225 deletions
diff --git a/boost/asio/connect.hpp b/boost/asio/connect.hpp index 635a8ad9bd..e31e8c92cd 100644 --- a/boost/asio/connect.hpp +++ b/boost/asio/connect.hpp @@ -18,6 +18,7 @@ #include <boost/asio/detail/config.hpp> #include <boost/asio/async_result.hpp> #include <boost/asio/basic_socket.hpp> +#include <boost/asio/detail/type_traits.hpp> #include <boost/asio/error.hpp> #include <boost/asio/detail/push_options.hpp> @@ -25,6 +26,36 @@ namespace boost { namespace asio { +namespace detail +{ + char (&has_iterator_helper(...))[2]; + + template <typename T> + char has_iterator_helper(T*, typename T::iterator* = 0); + + template <typename T> + struct has_iterator_typedef + { + enum { value = (sizeof((has_iterator_helper)((T*)(0))) == 1) }; + }; +} // namespace detail + +/// Type trait used to determine whether a type is an endpoint sequence that can +/// be used with with @c connect and @c async_connect. +template <typename T> +struct is_endpoint_sequence +{ +#if defined(GENERATING_DOCUMENTATION) + /// The value member is true if the type may be used as an endpoint sequence. + static const bool value; +#else + enum + { + value = detail::has_iterator_typedef<T>::value + }; +#endif +}; + /** * @defgroup connect boost::asio::connect * @@ -42,27 +73,26 @@ namespace asio { * @param s The socket to be connected. If the socket is already open, it will * be closed. * - * @param begin An iterator pointing to the start of a sequence of endpoints. + * @param endpoints A sequence of endpoints. * - * @returns On success, an iterator denoting the successfully connected - * endpoint. Otherwise, the end iterator. + * @returns The successfully connected endpoint. * * @throws boost::system::system_error Thrown on failure. If the sequence is * empty, the associated @c error_code is boost::asio::error::not_found. * Otherwise, contains the error from the last connection attempt. * - * @note This overload assumes that a default constructed object of type @c - * Iterator represents the end of the sequence. This is a valid assumption for - * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. - * * @par Example - * @code tcp::resolver r(io_service); + * @code tcp::resolver r(io_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_service); + * tcp::socket s(io_context); * boost::asio::connect(s, r.resolve(q)); @endcode */ -template <typename Protocol, typename SocketService, typename Iterator> -Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin); +template <typename Protocol BOOST_ASIO_SVC_TPARAM, typename EndpointSequence> +typename Protocol::endpoint connect( + basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, + const EndpointSequence& endpoints, + typename enable_if<is_endpoint_sequence< + EndpointSequence>::value>::type* = 0); /// Establishes a socket connection by trying each endpoint in a sequence. /** @@ -74,23 +104,19 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin); * @param s The socket to be connected. If the socket is already open, it will * be closed. * - * @param begin An iterator pointing to the start of a sequence of endpoints. + * @param endpoints A sequence of endpoints. * * @param ec Set to indicate what error occurred, if any. If the sequence is * empty, set to boost::asio::error::not_found. Otherwise, contains the error * from the last connection attempt. * - * @returns On success, an iterator denoting the successfully connected - * endpoint. Otherwise, the end iterator. - * - * @note This overload assumes that a default constructed object of type @c - * Iterator represents the end of the sequence. This is a valid assumption for - * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. + * @returns On success, the successfully connected endpoint. Otherwise, a + * default-constructed endpoint. * * @par Example - * @code tcp::resolver r(io_service); + * @code tcp::resolver r(io_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_service); + * tcp::socket s(io_context); * boost::system::error_code ec; * boost::asio::connect(s, r.resolve(q), ec); * if (ec) @@ -98,11 +124,16 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin); * // An error occurred. * } @endcode */ -template <typename Protocol, typename SocketService, typename Iterator> -Iterator connect(basic_socket<Protocol, SocketService>& s, - Iterator begin, boost::system::error_code& ec); +template <typename Protocol BOOST_ASIO_SVC_TPARAM, typename EndpointSequence> +typename Protocol::endpoint connect( + basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, + const EndpointSequence& endpoints, boost::system::error_code& ec, + typename enable_if<is_endpoint_sequence< + EndpointSequence>::value>::type* = 0); -/// Establishes a socket connection by trying each endpoint in a sequence. +#if !defined(BOOST_ASIO_NO_DEPRECATED) +/// (Deprecated.) Establishes a socket connection by trying each endpoint in a +/// sequence. /** * This function attempts to connect a socket to one of a sequence of * endpoints. It does this by repeated calls to the socket's @c connect member @@ -114,24 +145,80 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, * * @param begin An iterator pointing to the start of a sequence of endpoints. * - * @param end An iterator pointing to the end of a sequence of endpoints. + * @returns On success, an iterator denoting the successfully connected + * endpoint. Otherwise, the end iterator. + * + * @throws boost::system::system_error Thrown on failure. If the sequence is + * empty, the associated @c error_code is boost::asio::error::not_found. + * Otherwise, contains the error from the last connection attempt. + * + * @note This overload assumes that a default constructed object of type @c + * Iterator represents the end of the sequence. This is a valid assumption for + * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. + */ +template <typename Protocol BOOST_ASIO_SVC_TPARAM, typename Iterator> +Iterator connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, Iterator begin, + typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0); + +/// (Deprecated.) Establishes a socket connection by trying each endpoint in a +/// sequence. +/** + * This function attempts to connect a socket to one of a sequence of + * endpoints. It does this by repeated calls to the socket's @c connect member + * function, once for each endpoint in the sequence, until a connection is + * successfully established. + * + * @param s The socket to be connected. If the socket is already open, it will + * be closed. + * + * @param begin An iterator pointing to the start of a sequence of endpoints. + * + * @param ec Set to indicate what error occurred, if any. If the sequence is + * empty, set to boost::asio::error::not_found. Otherwise, contains the error + * from the last connection attempt. * * @returns On success, an iterator denoting the successfully connected * endpoint. Otherwise, the end iterator. * + * @note This overload assumes that a default constructed object of type @c + * Iterator represents the end of the sequence. This is a valid assumption for + * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. + */ +template <typename Protocol BOOST_ASIO_SVC_TPARAM, typename Iterator> +Iterator connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, + Iterator begin, boost::system::error_code& ec, + typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0); +#endif // !defined(BOOST_ASIO_NO_DEPRECATED) + +/// Establishes a socket connection by trying each endpoint in a sequence. +/** + * This function attempts to connect a socket to one of a sequence of + * endpoints. It does this by repeated calls to the socket's @c connect member + * function, once for each endpoint in the sequence, until a connection is + * successfully established. + * + * @param s The socket to be connected. If the socket is already open, it will + * be closed. + * + * @param begin An iterator pointing to the start of a sequence of endpoints. + * + * @param end An iterator pointing to the end of a sequence of endpoints. + * + * @returns An iterator denoting the successfully connected endpoint. + * * @throws boost::system::system_error Thrown on failure. If the sequence is * empty, the associated @c error_code is boost::asio::error::not_found. * Otherwise, contains the error from the last connection attempt. * * @par Example - * @code tcp::resolver r(io_service); + * @code tcp::resolver r(io_context); * tcp::resolver::query q("host", "service"); - * tcp::resolver::iterator i = r.resolve(q), end; - * tcp::socket s(io_service); - * boost::asio::connect(s, i, end); @endcode + * tcp::resolver::results_type e = r.resolve(q); + * tcp::socket s(io_context); + * boost::asio::connect(s, e.begin(), e.end()); @endcode */ -template <typename Protocol, typename SocketService, typename Iterator> -Iterator connect(basic_socket<Protocol, SocketService>& s, +template <typename Protocol BOOST_ASIO_SVC_TPARAM, typename Iterator> +Iterator connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, Iterator begin, Iterator end); /// Establishes a socket connection by trying each endpoint in a sequence. @@ -156,19 +243,19 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, * endpoint. Otherwise, the end iterator. * * @par Example - * @code tcp::resolver r(io_service); + * @code tcp::resolver r(io_context); * tcp::resolver::query q("host", "service"); - * tcp::resolver::iterator i = r.resolve(q), end; - * tcp::socket s(io_service); + * tcp::resolver::results_type e = r.resolve(q); + * tcp::socket s(io_context); * boost::system::error_code ec; - * boost::asio::connect(s, i, end, ec); + * boost::asio::connect(s, e.begin(), e.end(), ec); * if (ec) * { * // An error occurred. * } @endcode */ -template <typename Protocol, typename SocketService, typename Iterator> -Iterator connect(basic_socket<Protocol, SocketService>& s, +template <typename Protocol BOOST_ASIO_SVC_TPARAM, typename Iterator> +Iterator connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, Iterator begin, Iterator end, boost::system::error_code& ec); /// Establishes a socket connection by trying each endpoint in a sequence. @@ -181,59 +268,54 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, * @param s The socket to be connected. If the socket is already open, it will * be closed. * - * @param begin An iterator pointing to the start of a sequence of endpoints. + * @param endpoints A sequence of endpoints. * * @param connect_condition A function object that is called prior to each * connection attempt. The signature of the function object must be: - * @code Iterator connect_condition( + * @code bool connect_condition( * const boost::system::error_code& ec, - * Iterator next); @endcode + * const typename Protocol::endpoint& next); @endcode * The @c ec parameter contains the result from the most recent connect * operation. Before the first connection attempt, @c ec is always set to - * indicate success. The @c next parameter is an iterator pointing to the next - * endpoint to be tried. The function object should return the next iterator, - * but is permitted to return a different iterator so that endpoints may be - * skipped. The implementation guarantees that the function object will never - * be called with the end iterator. + * indicate success. The @c next parameter is the next endpoint to be tried. + * The function object should return true if the next endpoint should be tried, + * and false if it should be skipped. * - * @returns On success, an iterator denoting the successfully connected - * endpoint. Otherwise, the end iterator. + * @returns The successfully connected endpoint. * * @throws boost::system::system_error Thrown on failure. If the sequence is * empty, the associated @c error_code is boost::asio::error::not_found. * Otherwise, contains the error from the last connection attempt. * - * @note This overload assumes that a default constructed object of type @c - * Iterator represents the end of the sequence. This is a valid assumption for - * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. - * * @par Example * The following connect condition function object can be used to output * information about the individual connection attempts: * @code struct my_connect_condition * { - * template <typename Iterator> - * Iterator operator()( + * bool operator()( * const boost::system::error_code& ec, - * Iterator next) + * const::tcp::endpoint& next) * { * if (ec) std::cout << "Error: " << ec.message() << std::endl; - * std::cout << "Trying: " << next->endpoint() << std::endl; - * return next; + * std::cout << "Trying: " << next << std::endl; + * return true; * } * }; @endcode * It would be used with the boost::asio::connect function as follows: - * @code tcp::resolver r(io_service); + * @code tcp::resolver r(io_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_service); - * tcp::resolver::iterator i = boost::asio::connect( - * s, r.resolve(q), my_connect_condition()); - * std::cout << "Connected to: " << i->endpoint() << std::endl; @endcode + * tcp::socket s(io_context); + * tcp::endpoint e = boost::asio::connect(s, + * r.resolve(q), my_connect_condition()); + * std::cout << "Connected to: " << e << std::endl; @endcode */ -template <typename Protocol, typename SocketService, - typename Iterator, typename ConnectCondition> -Iterator connect(basic_socket<Protocol, SocketService>& s, - Iterator begin, ConnectCondition connect_condition); +template <typename Protocol BOOST_ASIO_SVC_TPARAM, + typename EndpointSequence, typename ConnectCondition> +typename Protocol::endpoint connect( + basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, + const EndpointSequence& endpoints, ConnectCondition connect_condition, + typename enable_if<is_endpoint_sequence< + EndpointSequence>::value>::type* = 0); /// Establishes a socket connection by trying each endpoint in a sequence. /** @@ -245,67 +327,148 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, * @param s The socket to be connected. If the socket is already open, it will * be closed. * - * @param begin An iterator pointing to the start of a sequence of endpoints. + * @param endpoints A sequence of endpoints. * * @param connect_condition A function object that is called prior to each * connection attempt. The signature of the function object must be: - * @code Iterator connect_condition( + * @code bool connect_condition( * const boost::system::error_code& ec, - * Iterator next); @endcode + * const typename Protocol::endpoint& next); @endcode * The @c ec parameter contains the result from the most recent connect * operation. Before the first connection attempt, @c ec is always set to - * indicate success. The @c next parameter is an iterator pointing to the next - * endpoint to be tried. The function object should return the next iterator, - * but is permitted to return a different iterator so that endpoints may be - * skipped. The implementation guarantees that the function object will never - * be called with the end iterator. + * indicate success. The @c next parameter is the next endpoint to be tried. + * The function object should return true if the next endpoint should be tried, + * and false if it should be skipped. * * @param ec Set to indicate what error occurred, if any. If the sequence is * empty, set to boost::asio::error::not_found. Otherwise, contains the error * from the last connection attempt. * - * @returns On success, an iterator denoting the successfully connected - * endpoint. Otherwise, the end iterator. - * - * @note This overload assumes that a default constructed object of type @c - * Iterator represents the end of the sequence. This is a valid assumption for - * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. + * @returns On success, the successfully connected endpoint. Otherwise, a + * default-constructed endpoint. * * @par Example * The following connect condition function object can be used to output * information about the individual connection attempts: * @code struct my_connect_condition * { - * template <typename Iterator> - * Iterator operator()( + * bool operator()( * const boost::system::error_code& ec, - * Iterator next) + * const::tcp::endpoint& next) * { * if (ec) std::cout << "Error: " << ec.message() << std::endl; - * std::cout << "Trying: " << next->endpoint() << std::endl; - * return next; + * std::cout << "Trying: " << next << std::endl; + * return true; * } * }; @endcode * It would be used with the boost::asio::connect function as follows: - * @code tcp::resolver r(io_service); + * @code tcp::resolver r(io_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_service); + * tcp::socket s(io_context); * boost::system::error_code ec; - * tcp::resolver::iterator i = boost::asio::connect( - * s, r.resolve(q), my_connect_condition(), ec); + * tcp::endpoint e = boost::asio::connect(s, + * r.resolve(q), my_connect_condition(), ec); * if (ec) * { * // An error occurred. * } * else * { - * std::cout << "Connected to: " << i->endpoint() << std::endl; + * std::cout << "Connected to: " << e << std::endl; * } @endcode */ -template <typename Protocol, typename SocketService, +template <typename Protocol BOOST_ASIO_SVC_TPARAM, + typename EndpointSequence, typename ConnectCondition> +typename Protocol::endpoint connect( + basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, + const EndpointSequence& endpoints, ConnectCondition connect_condition, + boost::system::error_code& ec, + typename enable_if<is_endpoint_sequence< + EndpointSequence>::value>::type* = 0); + +#if !defined(BOOST_ASIO_NO_DEPRECATED) +/// (Deprecated.) Establishes a socket connection by trying each endpoint in a +/// sequence. +/** + * This function attempts to connect a socket to one of a sequence of + * endpoints. It does this by repeated calls to the socket's @c connect member + * function, once for each endpoint in the sequence, until a connection is + * successfully established. + * + * @param s The socket to be connected. If the socket is already open, it will + * be closed. + * + * @param begin An iterator pointing to the start of a sequence of endpoints. + * + * @param connect_condition A function object that is called prior to each + * connection attempt. The signature of the function object must be: + * @code bool connect_condition( + * const boost::system::error_code& ec, + * const typename Protocol::endpoint& next); @endcode + * The @c ec parameter contains the result from the most recent connect + * operation. Before the first connection attempt, @c ec is always set to + * indicate success. The @c next parameter is the next endpoint to be tried. + * The function object should return true if the next endpoint should be tried, + * and false if it should be skipped. + * + * @returns On success, an iterator denoting the successfully connected + * endpoint. Otherwise, the end iterator. + * + * @throws boost::system::system_error Thrown on failure. If the sequence is + * empty, the associated @c error_code is boost::asio::error::not_found. + * Otherwise, contains the error from the last connection attempt. + * + * @note This overload assumes that a default constructed object of type @c + * Iterator represents the end of the sequence. This is a valid assumption for + * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. + */ +template <typename Protocol BOOST_ASIO_SVC_TPARAM, typename Iterator, typename ConnectCondition> -Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin, - ConnectCondition connect_condition, boost::system::error_code& ec); +Iterator connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, + Iterator begin, ConnectCondition connect_condition, + typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0); + +/// (Deprecated.) Establishes a socket connection by trying each endpoint in a +/// sequence. +/** + * This function attempts to connect a socket to one of a sequence of + * endpoints. It does this by repeated calls to the socket's @c connect member + * function, once for each endpoint in the sequence, until a connection is + * successfully established. + * + * @param s The socket to be connected. If the socket is already open, it will + * be closed. + * + * @param begin An iterator pointing to the start of a sequence of endpoints. + * + * @param connect_condition A function object that is called prior to each + * connection attempt. The signature of the function object must be: + * @code bool connect_condition( + * const boost::system::error_code& ec, + * const typename Protocol::endpoint& next); @endcode + * The @c ec parameter contains the result from the most recent connect + * operation. Before the first connection attempt, @c ec is always set to + * indicate success. The @c next parameter is the next endpoint to be tried. + * The function object should return true if the next endpoint should be tried, + * and false if it should be skipped. + * + * @param ec Set to indicate what error occurred, if any. If the sequence is + * empty, set to boost::asio::error::not_found. Otherwise, contains the error + * from the last connection attempt. + * + * @returns On success, an iterator denoting the successfully connected + * endpoint. Otherwise, the end iterator. + * + * @note This overload assumes that a default constructed object of type @c + * Iterator represents the end of the sequence. This is a valid assumption for + * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. + */ +template <typename Protocol BOOST_ASIO_SVC_TPARAM, + typename Iterator, typename ConnectCondition> +Iterator connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, Iterator begin, + ConnectCondition connect_condition, boost::system::error_code& ec, + typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0); +#endif // !defined(BOOST_ASIO_NO_DEPRECATED) /// Establishes a socket connection by trying each endpoint in a sequence. /** @@ -323,19 +486,16 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin, * * @param connect_condition A function object that is called prior to each * connection attempt. The signature of the function object must be: - * @code Iterator connect_condition( + * @code bool connect_condition( * const boost::system::error_code& ec, - * Iterator next); @endcode + * const typename Protocol::endpoint& next); @endcode * The @c ec parameter contains the result from the most recent connect * operation. Before the first connection attempt, @c ec is always set to - * indicate success. The @c next parameter is an iterator pointing to the next - * endpoint to be tried. The function object should return the next iterator, - * but is permitted to return a different iterator so that endpoints may be - * skipped. The implementation guarantees that the function object will never - * be called with the end iterator. + * indicate success. The @c next parameter is the next endpoint to be tried. + * The function object should return true if the next endpoint should be tried, + * and false if it should be skipped. * - * @returns On success, an iterator denoting the successfully connected - * endpoint. Otherwise, the end iterator. + * @returns An iterator denoting the successfully connected endpoint. * * @throws boost::system::system_error Thrown on failure. If the sequence is * empty, the associated @c error_code is boost::asio::error::not_found. @@ -346,27 +506,27 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin, * information about the individual connection attempts: * @code struct my_connect_condition * { - * template <typename Iterator> - * Iterator operator()( + * bool operator()( * const boost::system::error_code& ec, - * Iterator next) + * const::tcp::endpoint& next) * { * if (ec) std::cout << "Error: " << ec.message() << std::endl; - * std::cout << "Trying: " << next->endpoint() << std::endl; - * return next; + * std::cout << "Trying: " << next << std::endl; + * return true; * } * }; @endcode * It would be used with the boost::asio::connect function as follows: - * @code tcp::resolver r(io_service); + * @code tcp::resolver r(io_context); * tcp::resolver::query q("host", "service"); - * tcp::resolver::iterator i = r.resolve(q), end; - * tcp::socket s(io_service); - * i = boost::asio::connect(s, i, end, my_connect_condition()); + * tcp::resolver::results_type e = r.resolve(q); + * tcp::socket s(io_context); + * tcp::resolver::results_type::iterator i = boost::asio::connect( + * s, e.begin(), e.end(), my_connect_condition()); * std::cout << "Connected to: " << i->endpoint() << std::endl; @endcode */ -template <typename Protocol, typename SocketService, +template <typename Protocol BOOST_ASIO_SVC_TPARAM, typename Iterator, typename ConnectCondition> -Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin, +Iterator connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, Iterator begin, Iterator end, ConnectCondition connect_condition); /// Establishes a socket connection by trying each endpoint in a sequence. @@ -385,16 +545,14 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin, * * @param connect_condition A function object that is called prior to each * connection attempt. The signature of the function object must be: - * @code Iterator connect_condition( + * @code bool connect_condition( * const boost::system::error_code& ec, - * Iterator next); @endcode + * const typename Protocol::endpoint& next); @endcode * The @c ec parameter contains the result from the most recent connect * operation. Before the first connection attempt, @c ec is always set to - * indicate success. The @c next parameter is an iterator pointing to the next - * endpoint to be tried. The function object should return the next iterator, - * but is permitted to return a different iterator so that endpoints may be - * skipped. The implementation guarantees that the function object will never - * be called with the end iterator. + * indicate success. The @c next parameter is the next endpoint to be tried. + * The function object should return true if the next endpoint should be tried, + * and false if it should be skipped. * * @param ec Set to indicate what error occurred, if any. If the sequence is * empty, set to boost::asio::error::not_found. Otherwise, contains the error @@ -408,23 +566,23 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin, * information about the individual connection attempts: * @code struct my_connect_condition * { - * template <typename Iterator> - * Iterator operator()( + * bool operator()( * const boost::system::error_code& ec, - * Iterator next) + * const::tcp::endpoint& next) * { * if (ec) std::cout << "Error: " << ec.message() << std::endl; - * std::cout << "Trying: " << next->endpoint() << std::endl; - * return next; + * std::cout << "Trying: " << next << std::endl; + * return true; * } * }; @endcode * It would be used with the boost::asio::connect function as follows: - * @code tcp::resolver r(io_service); + * @code tcp::resolver r(io_context); * tcp::resolver::query q("host", "service"); - * tcp::resolver::iterator i = r.resolve(q), end; - * tcp::socket s(io_service); + * tcp::resolver::results_type e = r.resolve(q); + * tcp::socket s(io_context); * boost::system::error_code ec; - * i = boost::asio::connect(s, i, end, my_connect_condition(), ec); + * tcp::resolver::results_type::iterator i = boost::asio::connect( + * s, e.begin(), e.end(), my_connect_condition()); * if (ec) * { * // An error occurred. @@ -434,9 +592,9 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin, * std::cout << "Connected to: " << i->endpoint() << std::endl; * } @endcode */ -template <typename Protocol, typename SocketService, +template <typename Protocol BOOST_ASIO_SVC_TPARAM, typename Iterator, typename ConnectCondition> -Iterator connect(basic_socket<Protocol, SocketService>& s, +Iterator connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, Iterator begin, Iterator end, ConnectCondition connect_condition, boost::system::error_code& ec); @@ -461,7 +619,7 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, * @param s The socket to be connected. If the socket is already open, it will * be closed. * - * @param begin An iterator pointing to the start of a sequence of endpoints. + * @param endpoints A sequence of endpoints. * * @param handler The handler to be called when the connect operation * completes. Copies will be made of the handler as required. The function @@ -472,23 +630,19 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, * // error from the last connection attempt. * const boost::system::error_code& error, * - * // On success, an iterator denoting the successfully - * // connected endpoint. Otherwise, the end iterator. - * Iterator iterator + * // On success, the successfully connected endpoint. + * // Otherwise, a default-constructed endpoint. + * const typename Protocol::endpoint& endpoint * ); @endcode * Regardless of whether the asynchronous operation completes immediately or * not, the handler will not be invoked from within this function. Invocation * of the handler will be performed in a manner equivalent to using - * boost::asio::io_service::post(). - * - * @note This overload assumes that a default constructed object of type @c - * Iterator represents the end of the sequence. This is a valid assumption for - * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. + * boost::asio::io_context::post(). * * @par Example - * @code tcp::resolver r(io_service); + * @code tcp::resolver r(io_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_service); + * tcp::socket s(io_context); * * // ... * @@ -498,11 +652,11 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, * * void resolve_handler( * const boost::system::error_code& ec, - * tcp::resolver::iterator i) + * tcp::resolver::results_type results) * { * if (!ec) * { - * boost::asio::async_connect(s, i, connect_handler); + * boost::asio::async_connect(s, results, connect_handler); * } * } * @@ -510,17 +664,65 @@ Iterator connect(basic_socket<Protocol, SocketService>& s, * * void connect_handler( * const boost::system::error_code& ec, - * tcp::resolver::iterator i) + * const tcp::endpoint& endpoint) * { * // ... * } @endcode */ -template <typename Protocol, typename SocketService, - typename Iterator, typename ComposedConnectHandler> -BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler, +template <typename Protocol BOOST_ASIO_SVC_TPARAM, + typename EndpointSequence, typename RangeConnectHandler> +BOOST_ASIO_INITFN_RESULT_TYPE(RangeConnectHandler, + void (boost::system::error_code, typename Protocol::endpoint)) +async_connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, + const EndpointSequence& endpoints, + BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler, + typename enable_if<is_endpoint_sequence< + EndpointSequence>::value>::type* = 0); + +#if !defined(BOOST_ASIO_NO_DEPRECATED) +/// (Deprecated.) Asynchronously establishes a socket connection by trying each +/// endpoint in a sequence. +/** + * This function attempts to connect a socket to one of a sequence of + * endpoints. It does this by repeated calls to the socket's @c async_connect + * member function, once for each endpoint in the sequence, until a connection + * is successfully established. + * + * @param s The socket to be connected. If the socket is already open, it will + * be closed. + * + * @param begin An iterator pointing to the start of a sequence of endpoints. + * + * @param handler The handler to be called when the connect operation + * completes. Copies will be made of the handler as required. The function + * signature of the handler must be: + * @code void handler( + * // Result of operation. if the sequence is empty, set to + * // boost::asio::error::not_found. Otherwise, contains the + * // error from the last connection attempt. + * const boost::system::error_code& error, + * + * // On success, an iterator denoting the successfully + * // connected endpoint. Otherwise, the end iterator. + * Iterator iterator + * ); @endcode + * Regardless of whether the asynchronous operation completes immediately or + * not, the handler will not be invoked from within this function. Invocation + * of the handler will be performed in a manner equivalent to using + * boost::asio::io_context::post(). + * + * @note This overload assumes that a default constructed object of type @c + * Iterator represents the end of the sequence. This is a valid assumption for + * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. + */ +template <typename Protocol BOOST_ASIO_SVC_TPARAM, + typename Iterator, typename IteratorConnectHandler> +BOOST_ASIO_INITFN_RESULT_TYPE(IteratorConnectHandler, void (boost::system::error_code, Iterator)) -async_connect(basic_socket<Protocol, SocketService>& s, - Iterator begin, BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler); +async_connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, + Iterator begin, BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler, + typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0); +#endif // !defined(BOOST_ASIO_NO_DEPRECATED) /// Asynchronously establishes a socket connection by trying each endpoint in a /// sequence. @@ -553,46 +755,31 @@ async_connect(basic_socket<Protocol, SocketService>& s, * Regardless of whether the asynchronous operation completes immediately or * not, the handler will not be invoked from within this function. Invocation * of the handler will be performed in a manner equivalent to using - * boost::asio::io_service::post(). + * boost::asio::io_context::post(). * * @par Example - * @code tcp::resolver r(io_service); - * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_service); - * - * // ... - * - * r.async_resolve(q, resolve_handler); - * - * // ... - * - * void resolve_handler( - * const boost::system::error_code& ec, - * tcp::resolver::iterator i) - * { - * if (!ec) - * { - * tcp::resolver::iterator end; - * boost::asio::async_connect(s, i, end, connect_handler); - * } - * } + * @code std::vector<tcp::endpoint> endpoints = ...; + * tcp::socket s(io_context); + * boost::asio::async_connect(s, + * endpoints.begin(), endpoints.end(), + * connect_handler); * * // ... * * void connect_handler( * const boost::system::error_code& ec, - * tcp::resolver::iterator i) + * std::vector<tcp::endpoint>::iterator i) * { * // ... * } @endcode */ -template <typename Protocol, typename SocketService, - typename Iterator, typename ComposedConnectHandler> -BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler, +template <typename Protocol BOOST_ASIO_SVC_TPARAM, + typename Iterator, typename IteratorConnectHandler> +BOOST_ASIO_INITFN_RESULT_TYPE(IteratorConnectHandler, void (boost::system::error_code, Iterator)) -async_connect(basic_socket<Protocol, SocketService>& s, +async_connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, Iterator begin, Iterator end, - BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler); + BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler); /// Asynchronously establishes a socket connection by trying each endpoint in a /// sequence. @@ -605,20 +792,18 @@ async_connect(basic_socket<Protocol, SocketService>& s, * @param s The socket to be connected. If the socket is already open, it will * be closed. * - * @param begin An iterator pointing to the start of a sequence of endpoints. + * @param endpoints A sequence of endpoints. * * @param connect_condition A function object that is called prior to each * connection attempt. The signature of the function object must be: - * @code Iterator connect_condition( + * @code bool connect_condition( * const boost::system::error_code& ec, - * Iterator next); @endcode + * const typename Protocol::endpoint& next); @endcode * The @c ec parameter contains the result from the most recent connect * operation. Before the first connection attempt, @c ec is always set to - * indicate success. The @c next parameter is an iterator pointing to the next - * endpoint to be tried. The function object should return the next iterator, - * but is permitted to return a different iterator so that endpoints may be - * skipped. The implementation guarantees that the function object will never - * be called with the end iterator. + * indicate success. The @c next parameter is the next endpoint to be tried. + * The function object should return true if the next endpoint should be tried, + * and false if it should be skipped. * * @param handler The handler to be called when the connect operation * completes. Copies will be made of the handler as required. The function @@ -636,31 +821,26 @@ async_connect(basic_socket<Protocol, SocketService>& s, * Regardless of whether the asynchronous operation completes immediately or * not, the handler will not be invoked from within this function. Invocation * of the handler will be performed in a manner equivalent to using - * boost::asio::io_service::post(). - * - * @note This overload assumes that a default constructed object of type @c - * Iterator represents the end of the sequence. This is a valid assumption for - * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. + * boost::asio::io_context::post(). * * @par Example * The following connect condition function object can be used to output * information about the individual connection attempts: * @code struct my_connect_condition * { - * template <typename Iterator> - * Iterator operator()( + * bool operator()( * const boost::system::error_code& ec, - * Iterator next) + * const::tcp::endpoint& next) * { * if (ec) std::cout << "Error: " << ec.message() << std::endl; - * std::cout << "Trying: " << next->endpoint() << std::endl; - * return next; + * std::cout << "Trying: " << next << std::endl; + * return true; * } * }; @endcode * It would be used with the boost::asio::connect function as follows: - * @code tcp::resolver r(io_service); + * @code tcp::resolver r(io_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_service); + * tcp::socket s(io_context); * * // ... * @@ -670,11 +850,11 @@ async_connect(basic_socket<Protocol, SocketService>& s, * * void resolve_handler( * const boost::system::error_code& ec, - * tcp::resolver::iterator i) + * tcp::resolver::results_type results) * { * if (!ec) * { - * boost::asio::async_connect(s, i, + * boost::asio::async_connect(s, results, * my_connect_condition(), * connect_handler); * } @@ -684,7 +864,7 @@ async_connect(basic_socket<Protocol, SocketService>& s, * * void connect_handler( * const boost::system::error_code& ec, - * tcp::resolver::iterator i) + * const tcp::endpoint& endpoint) * { * if (ec) * { @@ -692,17 +872,76 @@ async_connect(basic_socket<Protocol, SocketService>& s, * } * else * { - * std::cout << "Connected to: " << i->endpoint() << std::endl; + * std::cout << "Connected to: " << endpoint << std::endl; * } * } @endcode */ -template <typename Protocol, typename SocketService, typename Iterator, - typename ConnectCondition, typename ComposedConnectHandler> -BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler, +template <typename Protocol BOOST_ASIO_SVC_TPARAM, typename EndpointSequence, + typename ConnectCondition, typename RangeConnectHandler> +BOOST_ASIO_INITFN_RESULT_TYPE(RangeConnectHandler, + void (boost::system::error_code, typename Protocol::endpoint)) +async_connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, + const EndpointSequence& endpoints, ConnectCondition connect_condition, + BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler, + typename enable_if<is_endpoint_sequence< + EndpointSequence>::value>::type* = 0); + +#if !defined(BOOST_ASIO_NO_DEPRECATED) +/// (Deprecated.) Asynchronously establishes a socket connection by trying each +/// endpoint in a sequence. +/** + * This function attempts to connect a socket to one of a sequence of + * endpoints. It does this by repeated calls to the socket's @c async_connect + * member function, once for each endpoint in the sequence, until a connection + * is successfully established. + * + * @param s The socket to be connected. If the socket is already open, it will + * be closed. + * + * @param begin An iterator pointing to the start of a sequence of endpoints. + * + * @param connect_condition A function object that is called prior to each + * connection attempt. The signature of the function object must be: + * @code bool connect_condition( + * const boost::system::error_code& ec, + * const typename Protocol::endpoint& next); @endcode + * The @c ec parameter contains the result from the most recent connect + * operation. Before the first connection attempt, @c ec is always set to + * indicate success. The @c next parameter is the next endpoint to be tried. + * The function object should return true if the next endpoint should be tried, + * and false if it should be skipped. + * + * @param handler The handler to be called when the connect operation + * completes. Copies will be made of the handler as required. The function + * signature of the handler must be: + * @code void handler( + * // Result of operation. if the sequence is empty, set to + * // boost::asio::error::not_found. Otherwise, contains the + * // error from the last connection attempt. + * const boost::system::error_code& error, + * + * // On success, an iterator denoting the successfully + * // connected endpoint. Otherwise, the end iterator. + * Iterator iterator + * ); @endcode + * Regardless of whether the asynchronous operation completes immediately or + * not, the handler will not be invoked from within this function. Invocation + * of the handler will be performed in a manner equivalent to using + * boost::asio::io_context::post(). + * + * @note This overload assumes that a default constructed object of type @c + * Iterator represents the end of the sequence. This is a valid assumption for + * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. + */ +template <typename Protocol BOOST_ASIO_SVC_TPARAM, typename Iterator, + typename ConnectCondition, typename IteratorConnectHandler> +BOOST_ASIO_INITFN_RESULT_TYPE(IteratorConnectHandler, void (boost::system::error_code, Iterator)) -async_connect(basic_socket<Protocol, SocketService>& s, Iterator begin, +async_connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, Iterator begin, ConnectCondition connect_condition, - BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler); + BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler, + typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0); +#endif // !defined(BOOST_ASIO_NO_DEPRECATED) /// Asynchronously establishes a socket connection by trying each endpoint in a /// sequence. @@ -721,16 +960,14 @@ async_connect(basic_socket<Protocol, SocketService>& s, Iterator begin, * * @param connect_condition A function object that is called prior to each * connection attempt. The signature of the function object must be: - * @code Iterator connect_condition( + * @code bool connect_condition( * const boost::system::error_code& ec, - * Iterator next); @endcode + * const typename Protocol::endpoint& next); @endcode * The @c ec parameter contains the result from the most recent connect * operation. Before the first connection attempt, @c ec is always set to - * indicate success. The @c next parameter is an iterator pointing to the next - * endpoint to be tried. The function object should return the next iterator, - * but is permitted to return a different iterator so that endpoints may be - * skipped. The implementation guarantees that the function object will never - * be called with the end iterator. + * indicate success. The @c next parameter is the next endpoint to be tried. + * The function object should return true if the next endpoint should be tried, + * and false if it should be skipped. * * @param handler The handler to be called when the connect operation * completes. Copies will be made of the handler as required. The function @@ -748,27 +985,26 @@ async_connect(basic_socket<Protocol, SocketService>& s, Iterator begin, * Regardless of whether the asynchronous operation completes immediately or * not, the handler will not be invoked from within this function. Invocation * of the handler will be performed in a manner equivalent to using - * boost::asio::io_service::post(). + * boost::asio::io_context::post(). * * @par Example * The following connect condition function object can be used to output * information about the individual connection attempts: * @code struct my_connect_condition * { - * template <typename Iterator> - * Iterator operator()( + * bool operator()( * const boost::system::error_code& ec, - * Iterator next) + * const::tcp::endpoint& next) * { * if (ec) std::cout << "Error: " << ec.message() << std::endl; - * std::cout << "Trying: " << next->endpoint() << std::endl; - * return next; + * std::cout << "Trying: " << next << std::endl; + * return true; * } * }; @endcode * It would be used with the boost::asio::connect function as follows: - * @code tcp::resolver r(io_service); + * @code tcp::resolver r(io_context); * tcp::resolver::query q("host", "service"); - * tcp::socket s(io_service); + * tcp::socket s(io_context); * * // ... * @@ -805,13 +1041,13 @@ async_connect(basic_socket<Protocol, SocketService>& s, Iterator begin, * } * } @endcode */ -template <typename Protocol, typename SocketService, typename Iterator, - typename ConnectCondition, typename ComposedConnectHandler> -BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler, +template <typename Protocol BOOST_ASIO_SVC_TPARAM, typename Iterator, + typename ConnectCondition, typename IteratorConnectHandler> +BOOST_ASIO_INITFN_RESULT_TYPE(IteratorConnectHandler, void (boost::system::error_code, Iterator)) -async_connect(basic_socket<Protocol, SocketService>& s, +async_connect(basic_socket<Protocol BOOST_ASIO_SVC_TARG>& s, Iterator begin, Iterator end, ConnectCondition connect_condition, - BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler); + BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler); /*@}*/ |