5 // Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com)
7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
11 #ifndef BOOST_ASIO_CONNECT_HPP
12 #define BOOST_ASIO_CONNECT_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
19 #include <boost/asio/async_result.hpp>
20 #include <boost/asio/basic_socket.hpp>
21 #include <boost/asio/error.hpp>
23 #include <boost/asio/detail/push_options.hpp>
29 * @defgroup connect boost::asio::connect
31 * @brief Establishes a socket connection by trying each endpoint in a sequence.
35 /// Establishes a socket connection by trying each endpoint in a sequence.
37 * This function attempts to connect a socket to one of a sequence of
38 * endpoints. It does this by repeated calls to the socket's @c connect member
39 * function, once for each endpoint in the sequence, until a connection is
40 * successfully established.
42 * @param s The socket to be connected. If the socket is already open, it will
45 * @param begin An iterator pointing to the start of a sequence of endpoints.
47 * @returns On success, an iterator denoting the successfully connected
48 * endpoint. Otherwise, the end iterator.
50 * @throws boost::system::system_error Thrown on failure. If the sequence is
51 * empty, the associated @c error_code is boost::asio::error::not_found.
52 * Otherwise, contains the error from the last connection attempt.
54 * @note This overload assumes that a default constructed object of type @c
55 * Iterator represents the end of the sequence. This is a valid assumption for
56 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
59 * @code tcp::resolver r(io_service);
60 * tcp::resolver::query q("host", "service");
61 * tcp::socket s(io_service);
62 * boost::asio::connect(s, r.resolve(q)); @endcode
64 template <typename Protocol, typename SocketService, typename Iterator>
65 Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin);
67 /// Establishes a socket connection by trying each endpoint in a sequence.
69 * This function attempts to connect a socket to one of a sequence of
70 * endpoints. It does this by repeated calls to the socket's @c connect member
71 * function, once for each endpoint in the sequence, until a connection is
72 * successfully established.
74 * @param s The socket to be connected. If the socket is already open, it will
77 * @param begin An iterator pointing to the start of a sequence of endpoints.
79 * @param ec Set to indicate what error occurred, if any. If the sequence is
80 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
81 * from the last connection attempt.
83 * @returns On success, an iterator denoting the successfully connected
84 * endpoint. Otherwise, the end iterator.
86 * @note This overload assumes that a default constructed object of type @c
87 * Iterator represents the end of the sequence. This is a valid assumption for
88 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
91 * @code tcp::resolver r(io_service);
92 * tcp::resolver::query q("host", "service");
93 * tcp::socket s(io_service);
94 * boost::system::error_code ec;
95 * boost::asio::connect(s, r.resolve(q), ec);
98 * // An error occurred.
101 template <typename Protocol, typename SocketService, typename Iterator>
102 Iterator connect(basic_socket<Protocol, SocketService>& s,
103 Iterator begin, boost::system::error_code& ec);
105 /// Establishes a socket connection by trying each endpoint in a sequence.
107 * This function attempts to connect a socket to one of a sequence of
108 * endpoints. It does this by repeated calls to the socket's @c connect member
109 * function, once for each endpoint in the sequence, until a connection is
110 * successfully established.
112 * @param s The socket to be connected. If the socket is already open, it will
115 * @param begin An iterator pointing to the start of a sequence of endpoints.
117 * @param end An iterator pointing to the end of a sequence of endpoints.
119 * @returns On success, an iterator denoting the successfully connected
120 * endpoint. Otherwise, the end iterator.
122 * @throws boost::system::system_error Thrown on failure. If the sequence is
123 * empty, the associated @c error_code is boost::asio::error::not_found.
124 * Otherwise, contains the error from the last connection attempt.
127 * @code tcp::resolver r(io_service);
128 * tcp::resolver::query q("host", "service");
129 * tcp::resolver::iterator i = r.resolve(q), end;
130 * tcp::socket s(io_service);
131 * boost::asio::connect(s, i, end); @endcode
133 template <typename Protocol, typename SocketService, typename Iterator>
134 Iterator connect(basic_socket<Protocol, SocketService>& s,
135 Iterator begin, Iterator end);
137 /// Establishes a socket connection by trying each endpoint in a sequence.
139 * This function attempts to connect a socket to one of a sequence of
140 * endpoints. It does this by repeated calls to the socket's @c connect member
141 * function, once for each endpoint in the sequence, until a connection is
142 * successfully established.
144 * @param s The socket to be connected. If the socket is already open, it will
147 * @param begin An iterator pointing to the start of a sequence of endpoints.
149 * @param end An iterator pointing to the end of a sequence of endpoints.
151 * @param ec Set to indicate what error occurred, if any. If the sequence is
152 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
153 * from the last connection attempt.
155 * @returns On success, an iterator denoting the successfully connected
156 * endpoint. Otherwise, the end iterator.
159 * @code tcp::resolver r(io_service);
160 * tcp::resolver::query q("host", "service");
161 * tcp::resolver::iterator i = r.resolve(q), end;
162 * tcp::socket s(io_service);
163 * boost::system::error_code ec;
164 * boost::asio::connect(s, i, end, ec);
167 * // An error occurred.
170 template <typename Protocol, typename SocketService, typename Iterator>
171 Iterator connect(basic_socket<Protocol, SocketService>& s,
172 Iterator begin, Iterator end, boost::system::error_code& ec);
174 /// Establishes a socket connection by trying each endpoint in a sequence.
176 * This function attempts to connect a socket to one of a sequence of
177 * endpoints. It does this by repeated calls to the socket's @c connect member
178 * function, once for each endpoint in the sequence, until a connection is
179 * successfully established.
181 * @param s The socket to be connected. If the socket is already open, it will
184 * @param begin An iterator pointing to the start of a sequence of endpoints.
186 * @param connect_condition A function object that is called prior to each
187 * connection attempt. The signature of the function object must be:
188 * @code Iterator connect_condition(
189 * const boost::system::error_code& ec,
190 * Iterator next); @endcode
191 * The @c ec parameter contains the result from the most recent connect
192 * operation. Before the first connection attempt, @c ec is always set to
193 * indicate success. The @c next parameter is an iterator pointing to the next
194 * endpoint to be tried. The function object should return the next iterator,
195 * but is permitted to return a different iterator so that endpoints may be
196 * skipped. The implementation guarantees that the function object will never
197 * be called with the end iterator.
199 * @returns On success, an iterator denoting the successfully connected
200 * endpoint. Otherwise, the end iterator.
202 * @throws boost::system::system_error Thrown on failure. If the sequence is
203 * empty, the associated @c error_code is boost::asio::error::not_found.
204 * Otherwise, contains the error from the last connection attempt.
206 * @note This overload assumes that a default constructed object of type @c
207 * Iterator represents the end of the sequence. This is a valid assumption for
208 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
211 * The following connect condition function object can be used to output
212 * information about the individual connection attempts:
213 * @code struct my_connect_condition
215 * template <typename Iterator>
216 * Iterator operator()(
217 * const boost::system::error_code& ec,
220 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
221 * std::cout << "Trying: " << next->endpoint() << std::endl;
225 * It would be used with the boost::asio::connect function as follows:
226 * @code tcp::resolver r(io_service);
227 * tcp::resolver::query q("host", "service");
228 * tcp::socket s(io_service);
229 * tcp::resolver::iterator i = boost::asio::connect(
230 * s, r.resolve(q), my_connect_condition());
231 * std::cout << "Connected to: " << i->endpoint() << std::endl; @endcode
233 template <typename Protocol, typename SocketService,
234 typename Iterator, typename ConnectCondition>
235 Iterator connect(basic_socket<Protocol, SocketService>& s,
236 Iterator begin, ConnectCondition connect_condition);
238 /// Establishes a socket connection by trying each endpoint in a sequence.
240 * This function attempts to connect a socket to one of a sequence of
241 * endpoints. It does this by repeated calls to the socket's @c connect member
242 * function, once for each endpoint in the sequence, until a connection is
243 * successfully established.
245 * @param s The socket to be connected. If the socket is already open, it will
248 * @param begin An iterator pointing to the start of a sequence of endpoints.
250 * @param connect_condition A function object that is called prior to each
251 * connection attempt. The signature of the function object must be:
252 * @code Iterator connect_condition(
253 * const boost::system::error_code& ec,
254 * Iterator next); @endcode
255 * The @c ec parameter contains the result from the most recent connect
256 * operation. Before the first connection attempt, @c ec is always set to
257 * indicate success. The @c next parameter is an iterator pointing to the next
258 * endpoint to be tried. The function object should return the next iterator,
259 * but is permitted to return a different iterator so that endpoints may be
260 * skipped. The implementation guarantees that the function object will never
261 * be called with the end iterator.
263 * @param ec Set to indicate what error occurred, if any. If the sequence is
264 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
265 * from the last connection attempt.
267 * @returns On success, an iterator denoting the successfully connected
268 * endpoint. Otherwise, the end iterator.
270 * @note This overload assumes that a default constructed object of type @c
271 * Iterator represents the end of the sequence. This is a valid assumption for
272 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
275 * The following connect condition function object can be used to output
276 * information about the individual connection attempts:
277 * @code struct my_connect_condition
279 * template <typename Iterator>
280 * Iterator operator()(
281 * const boost::system::error_code& ec,
284 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
285 * std::cout << "Trying: " << next->endpoint() << std::endl;
289 * It would be used with the boost::asio::connect function as follows:
290 * @code tcp::resolver r(io_service);
291 * tcp::resolver::query q("host", "service");
292 * tcp::socket s(io_service);
293 * boost::system::error_code ec;
294 * tcp::resolver::iterator i = boost::asio::connect(
295 * s, r.resolve(q), my_connect_condition(), ec);
298 * // An error occurred.
302 * std::cout << "Connected to: " << i->endpoint() << std::endl;
305 template <typename Protocol, typename SocketService,
306 typename Iterator, typename ConnectCondition>
307 Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin,
308 ConnectCondition connect_condition, boost::system::error_code& ec);
310 /// Establishes a socket connection by trying each endpoint in a sequence.
312 * This function attempts to connect a socket to one of a sequence of
313 * endpoints. It does this by repeated calls to the socket's @c connect member
314 * function, once for each endpoint in the sequence, until a connection is
315 * successfully established.
317 * @param s The socket to be connected. If the socket is already open, it will
320 * @param begin An iterator pointing to the start of a sequence of endpoints.
322 * @param end An iterator pointing to the end of a sequence of endpoints.
324 * @param connect_condition A function object that is called prior to each
325 * connection attempt. The signature of the function object must be:
326 * @code Iterator connect_condition(
327 * const boost::system::error_code& ec,
328 * Iterator next); @endcode
329 * The @c ec parameter contains the result from the most recent connect
330 * operation. Before the first connection attempt, @c ec is always set to
331 * indicate success. The @c next parameter is an iterator pointing to the next
332 * endpoint to be tried. The function object should return the next iterator,
333 * but is permitted to return a different iterator so that endpoints may be
334 * skipped. The implementation guarantees that the function object will never
335 * be called with the end iterator.
337 * @returns On success, an iterator denoting the successfully connected
338 * endpoint. Otherwise, the end iterator.
340 * @throws boost::system::system_error Thrown on failure. If the sequence is
341 * empty, the associated @c error_code is boost::asio::error::not_found.
342 * Otherwise, contains the error from the last connection attempt.
345 * The following connect condition function object can be used to output
346 * information about the individual connection attempts:
347 * @code struct my_connect_condition
349 * template <typename Iterator>
350 * Iterator operator()(
351 * const boost::system::error_code& ec,
354 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
355 * std::cout << "Trying: " << next->endpoint() << std::endl;
359 * It would be used with the boost::asio::connect function as follows:
360 * @code tcp::resolver r(io_service);
361 * tcp::resolver::query q("host", "service");
362 * tcp::resolver::iterator i = r.resolve(q), end;
363 * tcp::socket s(io_service);
364 * i = boost::asio::connect(s, i, end, my_connect_condition());
365 * std::cout << "Connected to: " << i->endpoint() << std::endl; @endcode
367 template <typename Protocol, typename SocketService,
368 typename Iterator, typename ConnectCondition>
369 Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin,
370 Iterator end, ConnectCondition connect_condition);
372 /// Establishes a socket connection by trying each endpoint in a sequence.
374 * This function attempts to connect a socket to one of a sequence of
375 * endpoints. It does this by repeated calls to the socket's @c connect member
376 * function, once for each endpoint in the sequence, until a connection is
377 * successfully established.
379 * @param s The socket to be connected. If the socket is already open, it will
382 * @param begin An iterator pointing to the start of a sequence of endpoints.
384 * @param end An iterator pointing to the end of a sequence of endpoints.
386 * @param connect_condition A function object that is called prior to each
387 * connection attempt. The signature of the function object must be:
388 * @code Iterator connect_condition(
389 * const boost::system::error_code& ec,
390 * Iterator next); @endcode
391 * The @c ec parameter contains the result from the most recent connect
392 * operation. Before the first connection attempt, @c ec is always set to
393 * indicate success. The @c next parameter is an iterator pointing to the next
394 * endpoint to be tried. The function object should return the next iterator,
395 * but is permitted to return a different iterator so that endpoints may be
396 * skipped. The implementation guarantees that the function object will never
397 * be called with the end iterator.
399 * @param ec Set to indicate what error occurred, if any. If the sequence is
400 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
401 * from the last connection attempt.
403 * @returns On success, an iterator denoting the successfully connected
404 * endpoint. Otherwise, the end iterator.
407 * The following connect condition function object can be used to output
408 * information about the individual connection attempts:
409 * @code struct my_connect_condition
411 * template <typename Iterator>
412 * Iterator operator()(
413 * const boost::system::error_code& ec,
416 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
417 * std::cout << "Trying: " << next->endpoint() << std::endl;
421 * It would be used with the boost::asio::connect function as follows:
422 * @code tcp::resolver r(io_service);
423 * tcp::resolver::query q("host", "service");
424 * tcp::resolver::iterator i = r.resolve(q), end;
425 * tcp::socket s(io_service);
426 * boost::system::error_code ec;
427 * i = boost::asio::connect(s, i, end, my_connect_condition(), ec);
430 * // An error occurred.
434 * std::cout << "Connected to: " << i->endpoint() << std::endl;
437 template <typename Protocol, typename SocketService,
438 typename Iterator, typename ConnectCondition>
439 Iterator connect(basic_socket<Protocol, SocketService>& s,
440 Iterator begin, Iterator end, ConnectCondition connect_condition,
441 boost::system::error_code& ec);
446 * @defgroup async_connect boost::asio::async_connect
448 * @brief Asynchronously establishes a socket connection by trying each
449 * endpoint in a sequence.
453 /// Asynchronously establishes a socket connection by trying each endpoint in a
456 * This function attempts to connect a socket to one of a sequence of
457 * endpoints. It does this by repeated calls to the socket's @c async_connect
458 * member function, once for each endpoint in the sequence, until a connection
459 * is successfully established.
461 * @param s The socket to be connected. If the socket is already open, it will
464 * @param begin An iterator pointing to the start of a sequence of endpoints.
466 * @param handler The handler to be called when the connect operation
467 * completes. Copies will be made of the handler as required. The function
468 * signature of the handler must be:
469 * @code void handler(
470 * // Result of operation. if the sequence is empty, set to
471 * // boost::asio::error::not_found. Otherwise, contains the
472 * // error from the last connection attempt.
473 * const boost::system::error_code& error,
475 * // On success, an iterator denoting the successfully
476 * // connected endpoint. Otherwise, the end iterator.
479 * Regardless of whether the asynchronous operation completes immediately or
480 * not, the handler will not be invoked from within this function. Invocation
481 * of the handler will be performed in a manner equivalent to using
482 * boost::asio::io_service::post().
484 * @note This overload assumes that a default constructed object of type @c
485 * Iterator represents the end of the sequence. This is a valid assumption for
486 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
489 * @code tcp::resolver r(io_service);
490 * tcp::resolver::query q("host", "service");
491 * tcp::socket s(io_service);
495 * r.async_resolve(q, resolve_handler);
499 * void resolve_handler(
500 * const boost::system::error_code& ec,
501 * tcp::resolver::iterator i)
505 * boost::asio::async_connect(s, i, connect_handler);
511 * void connect_handler(
512 * const boost::system::error_code& ec,
513 * tcp::resolver::iterator i)
518 template <typename Protocol, typename SocketService,
519 typename Iterator, typename ComposedConnectHandler>
520 BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler,
521 void (boost::system::error_code, Iterator))
522 async_connect(basic_socket<Protocol, SocketService>& s,
523 Iterator begin, BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler);
525 /// Asynchronously establishes a socket connection by trying each endpoint in a
528 * This function attempts to connect a socket to one of a sequence of
529 * endpoints. It does this by repeated calls to the socket's @c async_connect
530 * member function, once for each endpoint in the sequence, until a connection
531 * is successfully established.
533 * @param s The socket to be connected. If the socket is already open, it will
536 * @param begin An iterator pointing to the start of a sequence of endpoints.
538 * @param end An iterator pointing to the end of a sequence of endpoints.
540 * @param handler The handler to be called when the connect operation
541 * completes. Copies will be made of the handler as required. The function
542 * signature of the handler must be:
543 * @code void handler(
544 * // Result of operation. if the sequence is empty, set to
545 * // boost::asio::error::not_found. Otherwise, contains the
546 * // error from the last connection attempt.
547 * const boost::system::error_code& error,
549 * // On success, an iterator denoting the successfully
550 * // connected endpoint. Otherwise, the end iterator.
553 * Regardless of whether the asynchronous operation completes immediately or
554 * not, the handler will not be invoked from within this function. Invocation
555 * of the handler will be performed in a manner equivalent to using
556 * boost::asio::io_service::post().
559 * @code tcp::resolver r(io_service);
560 * tcp::resolver::query q("host", "service");
561 * tcp::socket s(io_service);
565 * r.async_resolve(q, resolve_handler);
569 * void resolve_handler(
570 * const boost::system::error_code& ec,
571 * tcp::resolver::iterator i)
575 * tcp::resolver::iterator end;
576 * boost::asio::async_connect(s, i, end, connect_handler);
582 * void connect_handler(
583 * const boost::system::error_code& ec,
584 * tcp::resolver::iterator i)
589 template <typename Protocol, typename SocketService,
590 typename Iterator, typename ComposedConnectHandler>
591 BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler,
592 void (boost::system::error_code, Iterator))
593 async_connect(basic_socket<Protocol, SocketService>& s,
594 Iterator begin, Iterator end,
595 BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler);
597 /// Asynchronously establishes a socket connection by trying each endpoint in a
600 * This function attempts to connect a socket to one of a sequence of
601 * endpoints. It does this by repeated calls to the socket's @c async_connect
602 * member function, once for each endpoint in the sequence, until a connection
603 * is successfully established.
605 * @param s The socket to be connected. If the socket is already open, it will
608 * @param begin An iterator pointing to the start of a sequence of endpoints.
610 * @param connect_condition A function object that is called prior to each
611 * connection attempt. The signature of the function object must be:
612 * @code Iterator connect_condition(
613 * const boost::system::error_code& ec,
614 * Iterator next); @endcode
615 * The @c ec parameter contains the result from the most recent connect
616 * operation. Before the first connection attempt, @c ec is always set to
617 * indicate success. The @c next parameter is an iterator pointing to the next
618 * endpoint to be tried. The function object should return the next iterator,
619 * but is permitted to return a different iterator so that endpoints may be
620 * skipped. The implementation guarantees that the function object will never
621 * be called with the end iterator.
623 * @param handler The handler to be called when the connect operation
624 * completes. Copies will be made of the handler as required. The function
625 * signature of the handler must be:
626 * @code void handler(
627 * // Result of operation. if the sequence is empty, set to
628 * // boost::asio::error::not_found. Otherwise, contains the
629 * // error from the last connection attempt.
630 * const boost::system::error_code& error,
632 * // On success, an iterator denoting the successfully
633 * // connected endpoint. Otherwise, the end iterator.
636 * Regardless of whether the asynchronous operation completes immediately or
637 * not, the handler will not be invoked from within this function. Invocation
638 * of the handler will be performed in a manner equivalent to using
639 * boost::asio::io_service::post().
641 * @note This overload assumes that a default constructed object of type @c
642 * Iterator represents the end of the sequence. This is a valid assumption for
643 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
646 * The following connect condition function object can be used to output
647 * information about the individual connection attempts:
648 * @code struct my_connect_condition
650 * template <typename Iterator>
651 * Iterator operator()(
652 * const boost::system::error_code& ec,
655 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
656 * std::cout << "Trying: " << next->endpoint() << std::endl;
660 * It would be used with the boost::asio::connect function as follows:
661 * @code tcp::resolver r(io_service);
662 * tcp::resolver::query q("host", "service");
663 * tcp::socket s(io_service);
667 * r.async_resolve(q, resolve_handler);
671 * void resolve_handler(
672 * const boost::system::error_code& ec,
673 * tcp::resolver::iterator i)
677 * boost::asio::async_connect(s, i,
678 * my_connect_condition(),
685 * void connect_handler(
686 * const boost::system::error_code& ec,
687 * tcp::resolver::iterator i)
691 * // An error occurred.
695 * std::cout << "Connected to: " << i->endpoint() << std::endl;
699 template <typename Protocol, typename SocketService, typename Iterator,
700 typename ConnectCondition, typename ComposedConnectHandler>
701 BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler,
702 void (boost::system::error_code, Iterator))
703 async_connect(basic_socket<Protocol, SocketService>& s, Iterator begin,
704 ConnectCondition connect_condition,
705 BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler);
707 /// Asynchronously establishes a socket connection by trying each endpoint in a
710 * This function attempts to connect a socket to one of a sequence of
711 * endpoints. It does this by repeated calls to the socket's @c async_connect
712 * member function, once for each endpoint in the sequence, until a connection
713 * is successfully established.
715 * @param s The socket to be connected. If the socket is already open, it will
718 * @param begin An iterator pointing to the start of a sequence of endpoints.
720 * @param end An iterator pointing to the end of a sequence of endpoints.
722 * @param connect_condition A function object that is called prior to each
723 * connection attempt. The signature of the function object must be:
724 * @code Iterator connect_condition(
725 * const boost::system::error_code& ec,
726 * Iterator next); @endcode
727 * The @c ec parameter contains the result from the most recent connect
728 * operation. Before the first connection attempt, @c ec is always set to
729 * indicate success. The @c next parameter is an iterator pointing to the next
730 * endpoint to be tried. The function object should return the next iterator,
731 * but is permitted to return a different iterator so that endpoints may be
732 * skipped. The implementation guarantees that the function object will never
733 * be called with the end iterator.
735 * @param handler The handler to be called when the connect operation
736 * completes. Copies will be made of the handler as required. The function
737 * signature of the handler must be:
738 * @code void handler(
739 * // Result of operation. if the sequence is empty, set to
740 * // boost::asio::error::not_found. Otherwise, contains the
741 * // error from the last connection attempt.
742 * const boost::system::error_code& error,
744 * // On success, an iterator denoting the successfully
745 * // connected endpoint. Otherwise, the end iterator.
748 * Regardless of whether the asynchronous operation completes immediately or
749 * not, the handler will not be invoked from within this function. Invocation
750 * of the handler will be performed in a manner equivalent to using
751 * boost::asio::io_service::post().
754 * The following connect condition function object can be used to output
755 * information about the individual connection attempts:
756 * @code struct my_connect_condition
758 * template <typename Iterator>
759 * Iterator operator()(
760 * const boost::system::error_code& ec,
763 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
764 * std::cout << "Trying: " << next->endpoint() << std::endl;
768 * It would be used with the boost::asio::connect function as follows:
769 * @code tcp::resolver r(io_service);
770 * tcp::resolver::query q("host", "service");
771 * tcp::socket s(io_service);
775 * r.async_resolve(q, resolve_handler);
779 * void resolve_handler(
780 * const boost::system::error_code& ec,
781 * tcp::resolver::iterator i)
785 * tcp::resolver::iterator end;
786 * boost::asio::async_connect(s, i, end,
787 * my_connect_condition(),
794 * void connect_handler(
795 * const boost::system::error_code& ec,
796 * tcp::resolver::iterator i)
800 * // An error occurred.
804 * std::cout << "Connected to: " << i->endpoint() << std::endl;
808 template <typename Protocol, typename SocketService, typename Iterator,
809 typename ConnectCondition, typename ComposedConnectHandler>
810 BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler,
811 void (boost::system::error_code, Iterator))
812 async_connect(basic_socket<Protocol, SocketService>& s,
813 Iterator begin, Iterator end, ConnectCondition connect_condition,
814 BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler);
821 #include <boost/asio/detail/pop_options.hpp>
823 #include <boost/asio/impl/connect.hpp>