async_connect (4 of 4 overloads)

+async_connect + (4 of 4 overloads) +

+ Asynchronously establishes a socket connection by trying each endpoint + in a sequence. +

template<
+    typename Protocol,
+    typename SocketService,
+    typename Iterator,
+    typename ConnectCondition,
+    typename ComposedConnectHandler>
+void async_connect(
+    basic_socket< Protocol, SocketService > & s,
+    Iterator begin,
+    Iterator end,
+    ConnectCondition connect_condition,
+    ComposedConnectHandler handler);
+

+ This function attempts to connect a socket to one of a sequence of endpoints. + It does this by repeated calls to the socket's async_connect + member function, once for each endpoint in the sequence, until a connection + is successfully established. +

+ + Parameters +

s

+ The socket to be connected. If the socket is already open, it will + be closed. +

begin

+ An iterator pointing to the start of a sequence of endpoints. +

end

+ An iterator pointing to the end of a sequence of endpoints. +

connect_condition

+ A function object that is called prior to each connection attempt. + The signature of the function object must be: +

Iterator connect_condition(
+    const boost::system::error_code& ec,
+    Iterator next);
+

+ The ec parameter + contains the result from the most recent connect operation. Before + the first connection attempt, ec + is always set to indicate success. The 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. +

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: +

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
+);
+

+ 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(). +

+ + Example +

+ The following connect condition function object can be used to output information + about the individual connection attempts: +

struct my_connect_condition
+{
+  template <typename Iterator>
+  Iterator operator()(
+      const boost::system::error_code& ec,
+      Iterator next)
+  {
+    if (ec) std::cout << "Error: " << ec.message() << std::endl;
+    std::cout << "Trying: " << next->endpoint() << std::endl;
+    return next;
+  }
+};
+

+ It would be used with the boost::asio::connect + function as follows: +

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,
+        my_connect_condition(),
+        connect_handler);
+  }
+}
+
+// ...
+
+void connect_handler(
+    const boost::system::error_code& ec,
+    tcp::resolver::iterator i)
+{
+  if (ec)
+  {
+    // An error occurred.
+  }
+  else
+  {
+    std::cout << "Connected to: " << i->endpoint() << std::endl;
+  }
+}
+