Chris@16: //
Chris@16: // connect.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_CONNECT_HPP
Chris@16: #define BOOST_ASIO_CONNECT_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 <boost/asio/detail/config.hpp>
Chris@16: #include <boost/asio/async_result.hpp>
Chris@16: #include <boost/asio/basic_socket.hpp>
Chris@16: #include <boost/asio/error.hpp>
Chris@16: 
Chris@16: #include <boost/asio/detail/push_options.hpp>
Chris@16: 
Chris@16: namespace boost {
Chris@16: namespace asio {
Chris@16: 
Chris@16: /**
Chris@16:  * @defgroup connect boost::asio::connect
Chris@16:  *
Chris@16:  * @brief Establishes a socket connection by trying each endpoint in a sequence.
Chris@16:  */
Chris@16: /*@{*/
Chris@16: 
Chris@16: /// Establishes a socket connection by trying each endpoint in a sequence.
Chris@16: /**
Chris@16:  * This function attempts to connect a socket to one of a sequence of
Chris@16:  * endpoints. It does this by repeated calls to the socket's @c connect member
Chris@16:  * function, once for each endpoint in the sequence, until a connection is
Chris@16:  * successfully established.
Chris@16:  *
Chris@16:  * @param s The socket to be connected. If the socket is already open, it will
Chris@16:  * be closed.
Chris@16:  *
Chris@16:  * @param begin An iterator pointing to the start of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @returns On success, an iterator denoting the successfully connected
Chris@16:  * endpoint. Otherwise, the end iterator.
Chris@16:  *
Chris@16:  * @throws boost::system::system_error Thrown on failure. If the sequence is
Chris@16:  * empty, the associated @c error_code is boost::asio::error::not_found.
Chris@16:  * Otherwise, contains the error from the last connection attempt.
Chris@16:  *
Chris@16:  * @note This overload assumes that a default constructed object of type @c
Chris@16:  * Iterator represents the end of the sequence. This is a valid assumption for
Chris@16:  * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
Chris@16:  *
Chris@16:  * @par Example
Chris@16:  * @code tcp::resolver r(io_service);
Chris@16:  * tcp::resolver::query q("host", "service");
Chris@16:  * tcp::socket s(io_service);
Chris@16:  * boost::asio::connect(s, r.resolve(q)); @endcode
Chris@16:  */
Chris@16: template <typename Protocol, typename SocketService, typename Iterator>
Chris@16: Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin);
Chris@16: 
Chris@16: /// Establishes a socket connection by trying each endpoint in a sequence.
Chris@16: /**
Chris@16:  * This function attempts to connect a socket to one of a sequence of
Chris@16:  * endpoints. It does this by repeated calls to the socket's @c connect member
Chris@16:  * function, once for each endpoint in the sequence, until a connection is
Chris@16:  * successfully established.
Chris@16:  *
Chris@16:  * @param s The socket to be connected. If the socket is already open, it will
Chris@16:  * be closed.
Chris@16:  *
Chris@16:  * @param begin An iterator pointing to the start of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param ec Set to indicate what error occurred, if any. If the sequence is
Chris@16:  * empty, set to boost::asio::error::not_found. Otherwise, contains the error
Chris@16:  * from the last connection attempt.
Chris@16:  *
Chris@16:  * @returns On success, an iterator denoting the successfully connected
Chris@16:  * endpoint. Otherwise, the end iterator.
Chris@16:  *
Chris@16:  * @note This overload assumes that a default constructed object of type @c
Chris@16:  * Iterator represents the end of the sequence. This is a valid assumption for
Chris@16:  * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
Chris@16:  *
Chris@16:  * @par Example
Chris@16:  * @code tcp::resolver r(io_service);
Chris@16:  * tcp::resolver::query q("host", "service");
Chris@16:  * tcp::socket s(io_service);
Chris@16:  * boost::system::error_code ec;
Chris@16:  * boost::asio::connect(s, r.resolve(q), ec);
Chris@16:  * if (ec)
Chris@16:  * {
Chris@16:  *   // An error occurred.
Chris@16:  * } @endcode
Chris@16:  */
Chris@16: template <typename Protocol, typename SocketService, typename Iterator>
Chris@16: Iterator connect(basic_socket<Protocol, SocketService>& s,
Chris@16:     Iterator begin, boost::system::error_code& ec);
Chris@16: 
Chris@16: /// Establishes a socket connection by trying each endpoint in a sequence.
Chris@16: /**
Chris@16:  * This function attempts to connect a socket to one of a sequence of
Chris@16:  * endpoints. It does this by repeated calls to the socket's @c connect member
Chris@16:  * function, once for each endpoint in the sequence, until a connection is
Chris@16:  * successfully established.
Chris@16:  *
Chris@16:  * @param s The socket to be connected. If the socket is already open, it will
Chris@16:  * be closed.
Chris@16:  *
Chris@16:  * @param begin An iterator pointing to the start of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param end An iterator pointing to the end of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @returns On success, an iterator denoting the successfully connected
Chris@16:  * endpoint. Otherwise, the end iterator.
Chris@16:  *
Chris@16:  * @throws boost::system::system_error Thrown on failure. If the sequence is
Chris@16:  * empty, the associated @c error_code is boost::asio::error::not_found.
Chris@16:  * Otherwise, contains the error from the last connection attempt.
Chris@16:  *
Chris@16:  * @par Example
Chris@16:  * @code tcp::resolver r(io_service);
Chris@16:  * tcp::resolver::query q("host", "service");
Chris@16:  * tcp::resolver::iterator i = r.resolve(q), end;
Chris@16:  * tcp::socket s(io_service);
Chris@16:  * boost::asio::connect(s, i, end); @endcode
Chris@16:  */
Chris@16: template <typename Protocol, typename SocketService, typename Iterator>
Chris@16: Iterator connect(basic_socket<Protocol, SocketService>& s,
Chris@16:     Iterator begin, Iterator end);
Chris@16: 
Chris@16: /// Establishes a socket connection by trying each endpoint in a sequence.
Chris@16: /**
Chris@16:  * This function attempts to connect a socket to one of a sequence of
Chris@16:  * endpoints. It does this by repeated calls to the socket's @c connect member
Chris@16:  * function, once for each endpoint in the sequence, until a connection is
Chris@16:  * successfully established.
Chris@16:  *
Chris@16:  * @param s The socket to be connected. If the socket is already open, it will
Chris@16:  * be closed.
Chris@16:  *
Chris@16:  * @param begin An iterator pointing to the start of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param end An iterator pointing to the end of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param ec Set to indicate what error occurred, if any. If the sequence is
Chris@16:  * empty, set to boost::asio::error::not_found. Otherwise, contains the error
Chris@16:  * from the last connection attempt.
Chris@16:  *
Chris@16:  * @returns On success, an iterator denoting the successfully connected
Chris@16:  * endpoint. Otherwise, the end iterator.
Chris@16:  *
Chris@16:  * @par Example
Chris@16:  * @code tcp::resolver r(io_service);
Chris@16:  * tcp::resolver::query q("host", "service");
Chris@16:  * tcp::resolver::iterator i = r.resolve(q), end;
Chris@16:  * tcp::socket s(io_service);
Chris@16:  * boost::system::error_code ec;
Chris@16:  * boost::asio::connect(s, i, end, ec);
Chris@16:  * if (ec)
Chris@16:  * {
Chris@16:  *   // An error occurred.
Chris@16:  * } @endcode
Chris@16:  */
Chris@16: template <typename Protocol, typename SocketService, typename Iterator>
Chris@16: Iterator connect(basic_socket<Protocol, SocketService>& s,
Chris@16:     Iterator begin, Iterator end, boost::system::error_code& ec);
Chris@16: 
Chris@16: /// Establishes a socket connection by trying each endpoint in a sequence.
Chris@16: /**
Chris@16:  * This function attempts to connect a socket to one of a sequence of
Chris@16:  * endpoints. It does this by repeated calls to the socket's @c connect member
Chris@16:  * function, once for each endpoint in the sequence, until a connection is
Chris@16:  * successfully established.
Chris@16:  *
Chris@16:  * @param s The socket to be connected. If the socket is already open, it will
Chris@16:  * be closed.
Chris@16:  *
Chris@16:  * @param begin An iterator pointing to the start of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param connect_condition A function object that is called prior to each
Chris@16:  * connection attempt. The signature of the function object must be:
Chris@16:  * @code Iterator connect_condition(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     Iterator next); @endcode
Chris@16:  * The @c ec parameter contains the result from the most recent connect
Chris@16:  * operation. Before the first connection attempt, @c ec is always set to
Chris@16:  * indicate success. The @c next parameter is an iterator pointing to the next
Chris@16:  * endpoint to be tried. The function object should return the next iterator,
Chris@16:  * but is permitted to return a different iterator so that endpoints may be
Chris@16:  * skipped. The implementation guarantees that the function object will never
Chris@16:  * be called with the end iterator.
Chris@16:  *
Chris@16:  * @returns On success, an iterator denoting the successfully connected
Chris@16:  * endpoint. Otherwise, the end iterator.
Chris@16:  *
Chris@16:  * @throws boost::system::system_error Thrown on failure. If the sequence is
Chris@16:  * empty, the associated @c error_code is boost::asio::error::not_found.
Chris@16:  * Otherwise, contains the error from the last connection attempt.
Chris@16:  *
Chris@16:  * @note This overload assumes that a default constructed object of type @c
Chris@16:  * Iterator represents the end of the sequence. This is a valid assumption for
Chris@16:  * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
Chris@16:  *
Chris@16:  * @par Example
Chris@16:  * The following connect condition function object can be used to output
Chris@16:  * information about the individual connection attempts:
Chris@16:  * @code struct my_connect_condition
Chris@16:  * {
Chris@16:  *   template <typename Iterator>
Chris@16:  *   Iterator operator()(
Chris@16:  *       const boost::system::error_code& ec,
Chris@16:  *       Iterator next)
Chris@16:  *   {
Chris@16:  *     if (ec) std::cout << "Error: " << ec.message() << std::endl;
Chris@16:  *     std::cout << "Trying: " << next->endpoint() << std::endl;
Chris@16:  *     return next;
Chris@16:  *   }
Chris@16:  * }; @endcode
Chris@16:  * It would be used with the boost::asio::connect function as follows:
Chris@16:  * @code tcp::resolver r(io_service);
Chris@16:  * tcp::resolver::query q("host", "service");
Chris@16:  * tcp::socket s(io_service);
Chris@16:  * tcp::resolver::iterator i = boost::asio::connect(
Chris@16:  *     s, r.resolve(q), my_connect_condition());
Chris@16:  * std::cout << "Connected to: " << i->endpoint() << std::endl; @endcode
Chris@16:  */
Chris@16: template <typename Protocol, typename SocketService,
Chris@16:     typename Iterator, typename ConnectCondition>
Chris@16: Iterator connect(basic_socket<Protocol, SocketService>& s,
Chris@16:     Iterator begin, ConnectCondition connect_condition);
Chris@16: 
Chris@16: /// Establishes a socket connection by trying each endpoint in a sequence.
Chris@16: /**
Chris@16:  * This function attempts to connect a socket to one of a sequence of
Chris@16:  * endpoints. It does this by repeated calls to the socket's @c connect member
Chris@16:  * function, once for each endpoint in the sequence, until a connection is
Chris@16:  * successfully established.
Chris@16:  *
Chris@16:  * @param s The socket to be connected. If the socket is already open, it will
Chris@16:  * be closed.
Chris@16:  *
Chris@16:  * @param begin An iterator pointing to the start of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param connect_condition A function object that is called prior to each
Chris@16:  * connection attempt. The signature of the function object must be:
Chris@16:  * @code Iterator connect_condition(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     Iterator next); @endcode
Chris@16:  * The @c ec parameter contains the result from the most recent connect
Chris@16:  * operation. Before the first connection attempt, @c ec is always set to
Chris@16:  * indicate success. The @c next parameter is an iterator pointing to the next
Chris@16:  * endpoint to be tried. The function object should return the next iterator,
Chris@16:  * but is permitted to return a different iterator so that endpoints may be
Chris@16:  * skipped. The implementation guarantees that the function object will never
Chris@16:  * be called with the end iterator.
Chris@16:  *
Chris@16:  * @param ec Set to indicate what error occurred, if any. If the sequence is
Chris@16:  * empty, set to boost::asio::error::not_found. Otherwise, contains the error
Chris@16:  * from the last connection attempt.
Chris@16:  *
Chris@16:  * @returns On success, an iterator denoting the successfully connected
Chris@16:  * endpoint. Otherwise, the end iterator.
Chris@16:  *
Chris@16:  * @note This overload assumes that a default constructed object of type @c
Chris@16:  * Iterator represents the end of the sequence. This is a valid assumption for
Chris@16:  * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
Chris@16:  *
Chris@16:  * @par Example
Chris@16:  * The following connect condition function object can be used to output
Chris@16:  * information about the individual connection attempts:
Chris@16:  * @code struct my_connect_condition
Chris@16:  * {
Chris@16:  *   template <typename Iterator>
Chris@16:  *   Iterator operator()(
Chris@16:  *       const boost::system::error_code& ec,
Chris@16:  *       Iterator next)
Chris@16:  *   {
Chris@16:  *     if (ec) std::cout << "Error: " << ec.message() << std::endl;
Chris@16:  *     std::cout << "Trying: " << next->endpoint() << std::endl;
Chris@16:  *     return next;
Chris@16:  *   }
Chris@16:  * }; @endcode
Chris@16:  * It would be used with the boost::asio::connect function as follows:
Chris@16:  * @code tcp::resolver r(io_service);
Chris@16:  * tcp::resolver::query q("host", "service");
Chris@16:  * tcp::socket s(io_service);
Chris@16:  * boost::system::error_code ec;
Chris@16:  * tcp::resolver::iterator i = boost::asio::connect(
Chris@16:  *     s, r.resolve(q), my_connect_condition(), ec);
Chris@16:  * if (ec)
Chris@16:  * {
Chris@16:  *   // An error occurred.
Chris@16:  * }
Chris@16:  * else
Chris@16:  * {
Chris@16:  *   std::cout << "Connected to: " << i->endpoint() << std::endl;
Chris@16:  * } @endcode
Chris@16:  */
Chris@16: template <typename Protocol, typename SocketService,
Chris@16:     typename Iterator, typename ConnectCondition>
Chris@16: Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin,
Chris@16:     ConnectCondition connect_condition, boost::system::error_code& ec);
Chris@16: 
Chris@16: /// Establishes a socket connection by trying each endpoint in a sequence.
Chris@16: /**
Chris@16:  * This function attempts to connect a socket to one of a sequence of
Chris@16:  * endpoints. It does this by repeated calls to the socket's @c connect member
Chris@16:  * function, once for each endpoint in the sequence, until a connection is
Chris@16:  * successfully established.
Chris@16:  *
Chris@16:  * @param s The socket to be connected. If the socket is already open, it will
Chris@16:  * be closed.
Chris@16:  *
Chris@16:  * @param begin An iterator pointing to the start of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param end An iterator pointing to the end of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param connect_condition A function object that is called prior to each
Chris@16:  * connection attempt. The signature of the function object must be:
Chris@16:  * @code Iterator connect_condition(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     Iterator next); @endcode
Chris@16:  * The @c ec parameter contains the result from the most recent connect
Chris@16:  * operation. Before the first connection attempt, @c ec is always set to
Chris@16:  * indicate success. The @c next parameter is an iterator pointing to the next
Chris@16:  * endpoint to be tried. The function object should return the next iterator,
Chris@16:  * but is permitted to return a different iterator so that endpoints may be
Chris@16:  * skipped. The implementation guarantees that the function object will never
Chris@16:  * be called with the end iterator.
Chris@16:  *
Chris@16:  * @returns On success, an iterator denoting the successfully connected
Chris@16:  * endpoint. Otherwise, the end iterator.
Chris@16:  *
Chris@16:  * @throws boost::system::system_error Thrown on failure. If the sequence is
Chris@16:  * empty, the associated @c error_code is boost::asio::error::not_found.
Chris@16:  * Otherwise, contains the error from the last connection attempt.
Chris@16:  *
Chris@16:  * @par Example
Chris@16:  * The following connect condition function object can be used to output
Chris@16:  * information about the individual connection attempts:
Chris@16:  * @code struct my_connect_condition
Chris@16:  * {
Chris@16:  *   template <typename Iterator>
Chris@16:  *   Iterator operator()(
Chris@16:  *       const boost::system::error_code& ec,
Chris@16:  *       Iterator next)
Chris@16:  *   {
Chris@16:  *     if (ec) std::cout << "Error: " << ec.message() << std::endl;
Chris@16:  *     std::cout << "Trying: " << next->endpoint() << std::endl;
Chris@16:  *     return next;
Chris@16:  *   }
Chris@16:  * }; @endcode
Chris@16:  * It would be used with the boost::asio::connect function as follows:
Chris@16:  * @code tcp::resolver r(io_service);
Chris@16:  * tcp::resolver::query q("host", "service");
Chris@16:  * tcp::resolver::iterator i = r.resolve(q), end;
Chris@16:  * tcp::socket s(io_service);
Chris@16:  * i = boost::asio::connect(s, i, end, my_connect_condition());
Chris@16:  * std::cout << "Connected to: " << i->endpoint() << std::endl; @endcode
Chris@16:  */
Chris@16: template <typename Protocol, typename SocketService,
Chris@16:     typename Iterator, typename ConnectCondition>
Chris@16: Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin,
Chris@16:     Iterator end, ConnectCondition connect_condition);
Chris@16: 
Chris@16: /// Establishes a socket connection by trying each endpoint in a sequence.
Chris@16: /**
Chris@16:  * This function attempts to connect a socket to one of a sequence of
Chris@16:  * endpoints. It does this by repeated calls to the socket's @c connect member
Chris@16:  * function, once for each endpoint in the sequence, until a connection is
Chris@16:  * successfully established.
Chris@16:  *
Chris@16:  * @param s The socket to be connected. If the socket is already open, it will
Chris@16:  * be closed.
Chris@16:  *
Chris@16:  * @param begin An iterator pointing to the start of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param end An iterator pointing to the end of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param connect_condition A function object that is called prior to each
Chris@16:  * connection attempt. The signature of the function object must be:
Chris@16:  * @code Iterator connect_condition(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     Iterator next); @endcode
Chris@16:  * The @c ec parameter contains the result from the most recent connect
Chris@16:  * operation. Before the first connection attempt, @c ec is always set to
Chris@16:  * indicate success. The @c next parameter is an iterator pointing to the next
Chris@16:  * endpoint to be tried. The function object should return the next iterator,
Chris@16:  * but is permitted to return a different iterator so that endpoints may be
Chris@16:  * skipped. The implementation guarantees that the function object will never
Chris@16:  * be called with the end iterator.
Chris@16:  *
Chris@16:  * @param ec Set to indicate what error occurred, if any. If the sequence is
Chris@16:  * empty, set to boost::asio::error::not_found. Otherwise, contains the error
Chris@16:  * from the last connection attempt.
Chris@16:  *
Chris@16:  * @returns On success, an iterator denoting the successfully connected
Chris@16:  * endpoint. Otherwise, the end iterator.
Chris@16:  *
Chris@16:  * @par Example
Chris@16:  * The following connect condition function object can be used to output
Chris@16:  * information about the individual connection attempts:
Chris@16:  * @code struct my_connect_condition
Chris@16:  * {
Chris@16:  *   template <typename Iterator>
Chris@16:  *   Iterator operator()(
Chris@16:  *       const boost::system::error_code& ec,
Chris@16:  *       Iterator next)
Chris@16:  *   {
Chris@16:  *     if (ec) std::cout << "Error: " << ec.message() << std::endl;
Chris@16:  *     std::cout << "Trying: " << next->endpoint() << std::endl;
Chris@16:  *     return next;
Chris@16:  *   }
Chris@16:  * }; @endcode
Chris@16:  * It would be used with the boost::asio::connect function as follows:
Chris@16:  * @code tcp::resolver r(io_service);
Chris@16:  * tcp::resolver::query q("host", "service");
Chris@16:  * tcp::resolver::iterator i = r.resolve(q), end;
Chris@16:  * tcp::socket s(io_service);
Chris@16:  * boost::system::error_code ec;
Chris@16:  * i = boost::asio::connect(s, i, end, my_connect_condition(), ec);
Chris@16:  * if (ec)
Chris@16:  * {
Chris@16:  *   // An error occurred.
Chris@16:  * }
Chris@16:  * else
Chris@16:  * {
Chris@16:  *   std::cout << "Connected to: " << i->endpoint() << std::endl;
Chris@16:  * } @endcode
Chris@16:  */
Chris@16: template <typename Protocol, typename SocketService,
Chris@16:     typename Iterator, typename ConnectCondition>
Chris@16: Iterator connect(basic_socket<Protocol, SocketService>& s,
Chris@16:     Iterator begin, Iterator end, ConnectCondition connect_condition,
Chris@16:     boost::system::error_code& ec);
Chris@16: 
Chris@16: /*@}*/
Chris@16: 
Chris@16: /**
Chris@16:  * @defgroup async_connect boost::asio::async_connect
Chris@16:  *
Chris@16:  * @brief Asynchronously establishes a socket connection by trying each
Chris@16:  * endpoint in a sequence.
Chris@16:  */
Chris@16: /*@{*/
Chris@16: 
Chris@16: /// Asynchronously establishes a socket connection by trying each endpoint in a
Chris@16: /// sequence.
Chris@16: /**
Chris@16:  * This function attempts to connect a socket to one of a sequence of
Chris@16:  * endpoints. It does this by repeated calls to the socket's @c async_connect
Chris@16:  * member function, once for each endpoint in the sequence, until a connection
Chris@16:  * is successfully established.
Chris@16:  *
Chris@16:  * @param s The socket to be connected. If the socket is already open, it will
Chris@16:  * be closed.
Chris@16:  *
Chris@16:  * @param begin An iterator pointing to the start of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param handler The handler to be called when the connect 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:  *   // Result of operation. if the sequence is empty, set to
Chris@16:  *   // boost::asio::error::not_found. Otherwise, contains the
Chris@16:  *   // error from the last connection attempt.
Chris@16:  *   const boost::system::error_code& error,
Chris@16:  *
Chris@16:  *   // On success, an iterator denoting the successfully
Chris@16:  *   // connected endpoint. Otherwise, the end iterator.
Chris@16:  *   Iterator iterator
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:  * @note This overload assumes that a default constructed object of type @c
Chris@16:  * Iterator represents the end of the sequence. This is a valid assumption for
Chris@16:  * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
Chris@16:  *
Chris@16:  * @par Example
Chris@16:  * @code tcp::resolver r(io_service);
Chris@16:  * tcp::resolver::query q("host", "service");
Chris@16:  * tcp::socket s(io_service);
Chris@16:  *
Chris@16:  * // ...
Chris@16:  *
Chris@16:  * r.async_resolve(q, resolve_handler);
Chris@16:  *
Chris@16:  * // ...
Chris@16:  *
Chris@16:  * void resolve_handler(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     tcp::resolver::iterator i)
Chris@16:  * {
Chris@16:  *   if (!ec)
Chris@16:  *   {
Chris@16:  *     boost::asio::async_connect(s, i, connect_handler);
Chris@16:  *   }
Chris@16:  * }
Chris@16:  *
Chris@16:  * // ...
Chris@16:  *
Chris@16:  * void connect_handler(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     tcp::resolver::iterator i)
Chris@16:  * {
Chris@16:  *   // ...
Chris@16:  * } @endcode
Chris@16:  */
Chris@16: template <typename Protocol, typename SocketService,
Chris@16:     typename Iterator, typename ComposedConnectHandler>
Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler,
Chris@16:     void (boost::system::error_code, Iterator))
Chris@16: async_connect(basic_socket<Protocol, SocketService>& s,
Chris@16:     Iterator begin, BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler);
Chris@16: 
Chris@16: /// Asynchronously establishes a socket connection by trying each endpoint in a
Chris@16: /// sequence.
Chris@16: /**
Chris@16:  * This function attempts to connect a socket to one of a sequence of
Chris@16:  * endpoints. It does this by repeated calls to the socket's @c async_connect
Chris@16:  * member function, once for each endpoint in the sequence, until a connection
Chris@16:  * is successfully established.
Chris@16:  *
Chris@16:  * @param s The socket to be connected. If the socket is already open, it will
Chris@16:  * be closed.
Chris@16:  *
Chris@16:  * @param begin An iterator pointing to the start of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param end An iterator pointing to the end of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param handler The handler to be called when the connect 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:  *   // Result of operation. if the sequence is empty, set to
Chris@16:  *   // boost::asio::error::not_found. Otherwise, contains the
Chris@16:  *   // error from the last connection attempt.
Chris@16:  *   const boost::system::error_code& error,
Chris@16:  *
Chris@16:  *   // On success, an iterator denoting the successfully
Chris@16:  *   // connected endpoint. Otherwise, the end iterator.
Chris@16:  *   Iterator iterator
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 tcp::resolver r(io_service);
Chris@16:  * tcp::resolver::query q("host", "service");
Chris@16:  * tcp::socket s(io_service);
Chris@16:  *
Chris@16:  * // ...
Chris@16:  *
Chris@16:  * r.async_resolve(q, resolve_handler);
Chris@16:  *
Chris@16:  * // ...
Chris@16:  *
Chris@16:  * void resolve_handler(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     tcp::resolver::iterator i)
Chris@16:  * {
Chris@16:  *   if (!ec)
Chris@16:  *   {
Chris@16:  *     tcp::resolver::iterator end;
Chris@16:  *     boost::asio::async_connect(s, i, end, connect_handler);
Chris@16:  *   }
Chris@16:  * }
Chris@16:  *
Chris@16:  * // ...
Chris@16:  *
Chris@16:  * void connect_handler(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     tcp::resolver::iterator i)
Chris@16:  * {
Chris@16:  *   // ...
Chris@16:  * } @endcode
Chris@16:  */
Chris@16: template <typename Protocol, typename SocketService,
Chris@16:     typename Iterator, typename ComposedConnectHandler>
Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler,
Chris@16:     void (boost::system::error_code, Iterator))
Chris@16: async_connect(basic_socket<Protocol, SocketService>& s,
Chris@16:     Iterator begin, Iterator end,
Chris@16:     BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler);
Chris@16: 
Chris@16: /// Asynchronously establishes a socket connection by trying each endpoint in a
Chris@16: /// sequence.
Chris@16: /**
Chris@16:  * This function attempts to connect a socket to one of a sequence of
Chris@16:  * endpoints. It does this by repeated calls to the socket's @c async_connect
Chris@16:  * member function, once for each endpoint in the sequence, until a connection
Chris@16:  * is successfully established.
Chris@16:  *
Chris@16:  * @param s The socket to be connected. If the socket is already open, it will
Chris@16:  * be closed.
Chris@16:  *
Chris@16:  * @param begin An iterator pointing to the start of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param connect_condition A function object that is called prior to each
Chris@16:  * connection attempt. The signature of the function object must be:
Chris@16:  * @code Iterator connect_condition(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     Iterator next); @endcode
Chris@16:  * The @c ec parameter contains the result from the most recent connect
Chris@16:  * operation. Before the first connection attempt, @c ec is always set to
Chris@16:  * indicate success. The @c next parameter is an iterator pointing to the next
Chris@16:  * endpoint to be tried. The function object should return the next iterator,
Chris@16:  * but is permitted to return a different iterator so that endpoints may be
Chris@16:  * skipped. The implementation guarantees that the function object will never
Chris@16:  * be called with the end iterator.
Chris@16:  *
Chris@16:  * @param handler The handler to be called when the connect 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:  *   // Result of operation. if the sequence is empty, set to
Chris@16:  *   // boost::asio::error::not_found. Otherwise, contains the
Chris@16:  *   // error from the last connection attempt.
Chris@16:  *   const boost::system::error_code& error,
Chris@16:  *
Chris@16:  *   // On success, an iterator denoting the successfully
Chris@16:  *   // connected endpoint. Otherwise, the end iterator.
Chris@16:  *   Iterator iterator
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:  * @note This overload assumes that a default constructed object of type @c
Chris@16:  * Iterator represents the end of the sequence. This is a valid assumption for
Chris@16:  * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
Chris@16:  *
Chris@16:  * @par Example
Chris@16:  * The following connect condition function object can be used to output
Chris@16:  * information about the individual connection attempts:
Chris@16:  * @code struct my_connect_condition
Chris@16:  * {
Chris@16:  *   template <typename Iterator>
Chris@16:  *   Iterator operator()(
Chris@16:  *       const boost::system::error_code& ec,
Chris@16:  *       Iterator next)
Chris@16:  *   {
Chris@16:  *     if (ec) std::cout << "Error: " << ec.message() << std::endl;
Chris@16:  *     std::cout << "Trying: " << next->endpoint() << std::endl;
Chris@16:  *     return next;
Chris@16:  *   }
Chris@16:  * }; @endcode
Chris@16:  * It would be used with the boost::asio::connect function as follows:
Chris@16:  * @code tcp::resolver r(io_service);
Chris@16:  * tcp::resolver::query q("host", "service");
Chris@16:  * tcp::socket s(io_service);
Chris@16:  *
Chris@16:  * // ...
Chris@16:  *
Chris@16:  * r.async_resolve(q, resolve_handler);
Chris@16:  *
Chris@16:  * // ...
Chris@16:  *
Chris@16:  * void resolve_handler(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     tcp::resolver::iterator i)
Chris@16:  * {
Chris@16:  *   if (!ec)
Chris@16:  *   {
Chris@16:  *     boost::asio::async_connect(s, i,
Chris@16:  *         my_connect_condition(),
Chris@16:  *         connect_handler);
Chris@16:  *   }
Chris@16:  * }
Chris@16:  *
Chris@16:  * // ...
Chris@16:  *
Chris@16:  * void connect_handler(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     tcp::resolver::iterator i)
Chris@16:  * {
Chris@16:  *   if (ec)
Chris@16:  *   {
Chris@16:  *     // An error occurred.
Chris@16:  *   }
Chris@16:  *   else
Chris@16:  *   {
Chris@16:  *     std::cout << "Connected to: " << i->endpoint() << std::endl;
Chris@16:  *   }
Chris@16:  * } @endcode
Chris@16:  */
Chris@16: template <typename Protocol, typename SocketService, typename Iterator,
Chris@16:     typename ConnectCondition, typename ComposedConnectHandler>
Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler,
Chris@16:     void (boost::system::error_code, Iterator))
Chris@16: async_connect(basic_socket<Protocol, SocketService>& s, Iterator begin,
Chris@16:     ConnectCondition connect_condition,
Chris@16:     BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler);
Chris@16: 
Chris@16: /// Asynchronously establishes a socket connection by trying each endpoint in a
Chris@16: /// sequence.
Chris@16: /**
Chris@16:  * This function attempts to connect a socket to one of a sequence of
Chris@16:  * endpoints. It does this by repeated calls to the socket's @c async_connect
Chris@16:  * member function, once for each endpoint in the sequence, until a connection
Chris@16:  * is successfully established.
Chris@16:  *
Chris@16:  * @param s The socket to be connected. If the socket is already open, it will
Chris@16:  * be closed.
Chris@16:  *
Chris@16:  * @param begin An iterator pointing to the start of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param end An iterator pointing to the end of a sequence of endpoints.
Chris@16:  *
Chris@16:  * @param connect_condition A function object that is called prior to each
Chris@16:  * connection attempt. The signature of the function object must be:
Chris@16:  * @code Iterator connect_condition(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     Iterator next); @endcode
Chris@16:  * The @c ec parameter contains the result from the most recent connect
Chris@16:  * operation. Before the first connection attempt, @c ec is always set to
Chris@16:  * indicate success. The @c next parameter is an iterator pointing to the next
Chris@16:  * endpoint to be tried. The function object should return the next iterator,
Chris@16:  * but is permitted to return a different iterator so that endpoints may be
Chris@16:  * skipped. The implementation guarantees that the function object will never
Chris@16:  * be called with the end iterator.
Chris@16:  *
Chris@16:  * @param handler The handler to be called when the connect 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:  *   // Result of operation. if the sequence is empty, set to
Chris@16:  *   // boost::asio::error::not_found. Otherwise, contains the
Chris@16:  *   // error from the last connection attempt.
Chris@16:  *   const boost::system::error_code& error,
Chris@16:  *
Chris@16:  *   // On success, an iterator denoting the successfully
Chris@16:  *   // connected endpoint. Otherwise, the end iterator.
Chris@16:  *   Iterator iterator
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:  * The following connect condition function object can be used to output
Chris@16:  * information about the individual connection attempts:
Chris@16:  * @code struct my_connect_condition
Chris@16:  * {
Chris@16:  *   template <typename Iterator>
Chris@16:  *   Iterator operator()(
Chris@16:  *       const boost::system::error_code& ec,
Chris@16:  *       Iterator next)
Chris@16:  *   {
Chris@16:  *     if (ec) std::cout << "Error: " << ec.message() << std::endl;
Chris@16:  *     std::cout << "Trying: " << next->endpoint() << std::endl;
Chris@16:  *     return next;
Chris@16:  *   }
Chris@16:  * }; @endcode
Chris@16:  * It would be used with the boost::asio::connect function as follows:
Chris@16:  * @code tcp::resolver r(io_service);
Chris@16:  * tcp::resolver::query q("host", "service");
Chris@16:  * tcp::socket s(io_service);
Chris@16:  *
Chris@16:  * // ...
Chris@16:  *
Chris@16:  * r.async_resolve(q, resolve_handler);
Chris@16:  *
Chris@16:  * // ...
Chris@16:  *
Chris@16:  * void resolve_handler(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     tcp::resolver::iterator i)
Chris@16:  * {
Chris@16:  *   if (!ec)
Chris@16:  *   {
Chris@16:  *     tcp::resolver::iterator end;
Chris@16:  *     boost::asio::async_connect(s, i, end,
Chris@16:  *         my_connect_condition(),
Chris@16:  *         connect_handler);
Chris@16:  *   }
Chris@16:  * }
Chris@16:  *
Chris@16:  * // ...
Chris@16:  *
Chris@16:  * void connect_handler(
Chris@16:  *     const boost::system::error_code& ec,
Chris@16:  *     tcp::resolver::iterator i)
Chris@16:  * {
Chris@16:  *   if (ec)
Chris@16:  *   {
Chris@16:  *     // An error occurred.
Chris@16:  *   }
Chris@16:  *   else
Chris@16:  *   {
Chris@16:  *     std::cout << "Connected to: " << i->endpoint() << std::endl;
Chris@16:  *   }
Chris@16:  * } @endcode
Chris@16:  */
Chris@16: template <typename Protocol, typename SocketService, typename Iterator,
Chris@16:     typename ConnectCondition, typename ComposedConnectHandler>
Chris@16: BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler,
Chris@16:     void (boost::system::error_code, Iterator))
Chris@16: async_connect(basic_socket<Protocol, SocketService>& s,
Chris@16:     Iterator begin, Iterator end, ConnectCondition connect_condition,
Chris@16:     BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler);
Chris@16: 
Chris@16: /*@}*/
Chris@16: 
Chris@16: } // namespace asio
Chris@16: } // namespace boost
Chris@16: 
Chris@16: #include <boost/asio/detail/pop_options.hpp>
Chris@16: 
Chris@16: #include <boost/asio/impl/connect.hpp>
Chris@16: 
Chris@16: #endif