5 // Copyright (c) 2003-2020 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/detail/type_traits.hpp>
22 #include <boost/asio/error.hpp>
24 #include <boost/asio/detail/push_options.hpp>
31 char (&has_iterator_helper(...))[2];
34 char has_iterator_helper(T*, typename T::iterator* = 0);
37 struct has_iterator_typedef
39 enum { value = (sizeof((has_iterator_helper)((T*)(0))) == 1) };
43 /// Type trait used to determine whether a type is an endpoint sequence that can
44 /// be used with with @c connect and @c async_connect.
46 struct is_endpoint_sequence
48 #if defined(GENERATING_DOCUMENTATION)
49 /// The value member is true if the type may be used as an endpoint sequence.
50 static const bool value;
54 value = detail::has_iterator_typedef<T>::value
60 * @defgroup connect boost::asio::connect
62 * @brief The @c connect function is a composed operation that establishes a
63 * socket connection by trying each endpoint in a sequence.
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 endpoints A sequence of endpoints.
79 * @returns The successfully connected endpoint.
81 * @throws boost::system::system_error Thrown on failure. If the sequence is
82 * empty, the associated @c error_code is boost::asio::error::not_found.
83 * Otherwise, contains the error from the last connection attempt.
86 * @code tcp::resolver r(my_context);
87 * tcp::resolver::query q("host", "service");
88 * tcp::socket s(my_context);
89 * boost::asio::connect(s, r.resolve(q)); @endcode
91 template <typename Protocol, typename Executor, typename EndpointSequence>
92 typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
93 const EndpointSequence& endpoints,
94 typename enable_if<is_endpoint_sequence<
95 EndpointSequence>::value>::type* = 0);
97 /// Establishes a socket connection by trying each endpoint in a sequence.
99 * This function attempts to connect a socket to one of a sequence of
100 * endpoints. It does this by repeated calls to the socket's @c connect member
101 * function, once for each endpoint in the sequence, until a connection is
102 * successfully established.
104 * @param s The socket to be connected. If the socket is already open, it will
107 * @param endpoints A sequence of endpoints.
109 * @param ec Set to indicate what error occurred, if any. If the sequence is
110 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
111 * from the last connection attempt.
113 * @returns On success, the successfully connected endpoint. Otherwise, a
114 * default-constructed endpoint.
117 * @code tcp::resolver r(my_context);
118 * tcp::resolver::query q("host", "service");
119 * tcp::socket s(my_context);
120 * boost::system::error_code ec;
121 * boost::asio::connect(s, r.resolve(q), ec);
124 * // An error occurred.
127 template <typename Protocol, typename Executor, typename EndpointSequence>
128 typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
129 const EndpointSequence& endpoints, boost::system::error_code& ec,
130 typename enable_if<is_endpoint_sequence<
131 EndpointSequence>::value>::type* = 0);
133 #if !defined(BOOST_ASIO_NO_DEPRECATED)
134 /// (Deprecated: Use range overload.) Establishes a socket connection by trying
135 /// each endpoint in a sequence.
137 * This function attempts to connect a socket to one of a sequence of
138 * endpoints. It does this by repeated calls to the socket's @c connect member
139 * function, once for each endpoint in the sequence, until a connection is
140 * successfully established.
142 * @param s The socket to be connected. If the socket is already open, it will
145 * @param begin An iterator pointing to the start of a sequence of endpoints.
147 * @returns On success, an iterator denoting the successfully connected
148 * endpoint. Otherwise, the end iterator.
150 * @throws boost::system::system_error Thrown on failure. If the sequence is
151 * empty, the associated @c error_code is boost::asio::error::not_found.
152 * Otherwise, contains the error from the last connection attempt.
154 * @note This overload assumes that a default constructed object of type @c
155 * Iterator represents the end of the sequence. This is a valid assumption for
156 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
158 template <typename Protocol, typename Executor, typename Iterator>
159 Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin,
160 typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
162 /// (Deprecated: Use range overload.) Establishes a socket connection by trying
163 /// each endpoint in a sequence.
165 * This function attempts to connect a socket to one of a sequence of
166 * endpoints. It does this by repeated calls to the socket's @c connect member
167 * function, once for each endpoint in the sequence, until a connection is
168 * successfully established.
170 * @param s The socket to be connected. If the socket is already open, it will
173 * @param begin An iterator pointing to the start of a sequence of endpoints.
175 * @param ec Set to indicate what error occurred, if any. If the sequence is
176 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
177 * from the last connection attempt.
179 * @returns On success, an iterator denoting the successfully connected
180 * endpoint. Otherwise, the end iterator.
182 * @note This overload assumes that a default constructed object of type @c
183 * Iterator represents the end of the sequence. This is a valid assumption for
184 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
186 template <typename Protocol, typename Executor, typename Iterator>
187 Iterator connect(basic_socket<Protocol, Executor>& s,
188 Iterator begin, boost::system::error_code& ec,
189 typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
190 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
192 /// Establishes a socket connection by trying each endpoint in a sequence.
194 * This function attempts to connect a socket to one of a sequence of
195 * endpoints. It does this by repeated calls to the socket's @c connect member
196 * function, once for each endpoint in the sequence, until a connection is
197 * successfully established.
199 * @param s The socket to be connected. If the socket is already open, it will
202 * @param begin An iterator pointing to the start of a sequence of endpoints.
204 * @param end An iterator pointing to the end of a sequence of endpoints.
206 * @returns An iterator denoting the successfully connected endpoint.
208 * @throws boost::system::system_error Thrown on failure. If the sequence is
209 * empty, the associated @c error_code is boost::asio::error::not_found.
210 * Otherwise, contains the error from the last connection attempt.
213 * @code tcp::resolver r(my_context);
214 * tcp::resolver::query q("host", "service");
215 * tcp::resolver::results_type e = r.resolve(q);
216 * tcp::socket s(my_context);
217 * boost::asio::connect(s, e.begin(), e.end()); @endcode
219 template <typename Protocol, typename Executor, typename Iterator>
220 Iterator connect(basic_socket<Protocol, Executor>& s,
221 Iterator begin, Iterator end);
223 /// Establishes a socket connection by trying each endpoint in a sequence.
225 * This function attempts to connect a socket to one of a sequence of
226 * endpoints. It does this by repeated calls to the socket's @c connect member
227 * function, once for each endpoint in the sequence, until a connection is
228 * successfully established.
230 * @param s The socket to be connected. If the socket is already open, it will
233 * @param begin An iterator pointing to the start of a sequence of endpoints.
235 * @param end An iterator pointing to the end of a sequence of endpoints.
237 * @param ec Set to indicate what error occurred, if any. If the sequence is
238 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
239 * from the last connection attempt.
241 * @returns On success, an iterator denoting the successfully connected
242 * endpoint. Otherwise, the end iterator.
245 * @code tcp::resolver r(my_context);
246 * tcp::resolver::query q("host", "service");
247 * tcp::resolver::results_type e = r.resolve(q);
248 * tcp::socket s(my_context);
249 * boost::system::error_code ec;
250 * boost::asio::connect(s, e.begin(), e.end(), ec);
253 * // An error occurred.
256 template <typename Protocol, typename Executor, typename Iterator>
257 Iterator connect(basic_socket<Protocol, Executor>& s,
258 Iterator begin, Iterator end, boost::system::error_code& ec);
260 /// Establishes a socket connection by trying each endpoint in a sequence.
262 * This function attempts to connect a socket to one of a sequence of
263 * endpoints. It does this by repeated calls to the socket's @c connect member
264 * function, once for each endpoint in the sequence, until a connection is
265 * successfully established.
267 * @param s The socket to be connected. If the socket is already open, it will
270 * @param endpoints A sequence of endpoints.
272 * @param connect_condition A function object that is called prior to each
273 * connection attempt. The signature of the function object must be:
274 * @code bool connect_condition(
275 * const boost::system::error_code& ec,
276 * const typename Protocol::endpoint& next); @endcode
277 * The @c ec parameter contains the result from the most recent connect
278 * operation. Before the first connection attempt, @c ec is always set to
279 * indicate success. The @c next parameter is the next endpoint to be tried.
280 * The function object should return true if the next endpoint should be tried,
281 * and false if it should be skipped.
283 * @returns The successfully connected endpoint.
285 * @throws boost::system::system_error Thrown on failure. If the sequence is
286 * empty, the associated @c error_code is boost::asio::error::not_found.
287 * Otherwise, contains the error from the last connection attempt.
290 * The following connect condition function object can be used to output
291 * information about the individual connection attempts:
292 * @code struct my_connect_condition
295 * const boost::system::error_code& ec,
296 * const::tcp::endpoint& next)
298 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
299 * std::cout << "Trying: " << next << std::endl;
303 * It would be used with the boost::asio::connect function as follows:
304 * @code tcp::resolver r(my_context);
305 * tcp::resolver::query q("host", "service");
306 * tcp::socket s(my_context);
307 * tcp::endpoint e = boost::asio::connect(s,
308 * r.resolve(q), my_connect_condition());
309 * std::cout << "Connected to: " << e << std::endl; @endcode
311 template <typename Protocol, typename Executor,
312 typename EndpointSequence, typename ConnectCondition>
313 typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
314 const EndpointSequence& endpoints, ConnectCondition connect_condition,
315 typename enable_if<is_endpoint_sequence<
316 EndpointSequence>::value>::type* = 0);
318 /// Establishes a socket connection by trying each endpoint in a sequence.
320 * This function attempts to connect a socket to one of a sequence of
321 * endpoints. It does this by repeated calls to the socket's @c connect member
322 * function, once for each endpoint in the sequence, until a connection is
323 * successfully established.
325 * @param s The socket to be connected. If the socket is already open, it will
328 * @param endpoints A sequence of endpoints.
330 * @param connect_condition A function object that is called prior to each
331 * connection attempt. The signature of the function object must be:
332 * @code bool connect_condition(
333 * const boost::system::error_code& ec,
334 * const typename Protocol::endpoint& next); @endcode
335 * The @c ec parameter contains the result from the most recent connect
336 * operation. Before the first connection attempt, @c ec is always set to
337 * indicate success. The @c next parameter is the next endpoint to be tried.
338 * The function object should return true if the next endpoint should be tried,
339 * and false if it should be skipped.
341 * @param ec Set to indicate what error occurred, if any. If the sequence is
342 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
343 * from the last connection attempt.
345 * @returns On success, the successfully connected endpoint. Otherwise, a
346 * default-constructed endpoint.
349 * The following connect condition function object can be used to output
350 * information about the individual connection attempts:
351 * @code struct my_connect_condition
354 * const boost::system::error_code& ec,
355 * const::tcp::endpoint& next)
357 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
358 * std::cout << "Trying: " << next << std::endl;
362 * It would be used with the boost::asio::connect function as follows:
363 * @code tcp::resolver r(my_context);
364 * tcp::resolver::query q("host", "service");
365 * tcp::socket s(my_context);
366 * boost::system::error_code ec;
367 * tcp::endpoint e = boost::asio::connect(s,
368 * r.resolve(q), my_connect_condition(), ec);
371 * // An error occurred.
375 * std::cout << "Connected to: " << e << std::endl;
378 template <typename Protocol, typename Executor,
379 typename EndpointSequence, typename ConnectCondition>
380 typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
381 const EndpointSequence& endpoints, ConnectCondition connect_condition,
382 boost::system::error_code& ec,
383 typename enable_if<is_endpoint_sequence<
384 EndpointSequence>::value>::type* = 0);
386 #if !defined(BOOST_ASIO_NO_DEPRECATED)
387 /// (Deprecated: Use range overload.) Establishes a socket connection by trying
388 /// each endpoint in a sequence.
390 * This function attempts to connect a socket to one of a sequence of
391 * endpoints. It does this by repeated calls to the socket's @c connect member
392 * function, once for each endpoint in the sequence, until a connection is
393 * successfully established.
395 * @param s The socket to be connected. If the socket is already open, it will
398 * @param begin An iterator pointing to the start of a sequence of endpoints.
400 * @param connect_condition A function object that is called prior to each
401 * connection attempt. The signature of the function object must be:
402 * @code bool connect_condition(
403 * const boost::system::error_code& ec,
404 * const typename Protocol::endpoint& next); @endcode
405 * The @c ec parameter contains the result from the most recent connect
406 * operation. Before the first connection attempt, @c ec is always set to
407 * indicate success. The @c next parameter is the next endpoint to be tried.
408 * The function object should return true if the next endpoint should be tried,
409 * and false if it should be skipped.
411 * @returns On success, an iterator denoting the successfully connected
412 * endpoint. Otherwise, the end iterator.
414 * @throws boost::system::system_error Thrown on failure. If the sequence is
415 * empty, the associated @c error_code is boost::asio::error::not_found.
416 * Otherwise, contains the error from the last connection attempt.
418 * @note This overload assumes that a default constructed object of type @c
419 * Iterator represents the end of the sequence. This is a valid assumption for
420 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
422 template <typename Protocol, typename Executor,
423 typename Iterator, typename ConnectCondition>
424 Iterator connect(basic_socket<Protocol, Executor>& s,
425 Iterator begin, ConnectCondition connect_condition,
426 typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
428 /// (Deprecated: Use range overload.) Establishes a socket connection by trying
429 /// each endpoint in a sequence.
431 * This function attempts to connect a socket to one of a sequence of
432 * endpoints. It does this by repeated calls to the socket's @c connect member
433 * function, once for each endpoint in the sequence, until a connection is
434 * successfully established.
436 * @param s The socket to be connected. If the socket is already open, it will
439 * @param begin An iterator pointing to the start of a sequence of endpoints.
441 * @param connect_condition A function object that is called prior to each
442 * connection attempt. The signature of the function object must be:
443 * @code bool connect_condition(
444 * const boost::system::error_code& ec,
445 * const typename Protocol::endpoint& next); @endcode
446 * The @c ec parameter contains the result from the most recent connect
447 * operation. Before the first connection attempt, @c ec is always set to
448 * indicate success. The @c next parameter is the next endpoint to be tried.
449 * The function object should return true if the next endpoint should be tried,
450 * and false if it should be skipped.
452 * @param ec Set to indicate what error occurred, if any. If the sequence is
453 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
454 * from the last connection attempt.
456 * @returns On success, an iterator denoting the successfully connected
457 * endpoint. Otherwise, the end iterator.
459 * @note This overload assumes that a default constructed object of type @c
460 * Iterator represents the end of the sequence. This is a valid assumption for
461 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
463 template <typename Protocol, typename Executor,
464 typename Iterator, typename ConnectCondition>
465 Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin,
466 ConnectCondition connect_condition, boost::system::error_code& ec,
467 typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
468 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
470 /// Establishes a socket connection by trying each endpoint in a sequence.
472 * This function attempts to connect a socket to one of a sequence of
473 * endpoints. It does this by repeated calls to the socket's @c connect member
474 * function, once for each endpoint in the sequence, until a connection is
475 * successfully established.
477 * @param s The socket to be connected. If the socket is already open, it will
480 * @param begin An iterator pointing to the start of a sequence of endpoints.
482 * @param end An iterator pointing to the end of a sequence of endpoints.
484 * @param connect_condition A function object that is called prior to each
485 * connection attempt. The signature of the function object must be:
486 * @code bool connect_condition(
487 * const boost::system::error_code& ec,
488 * const typename Protocol::endpoint& next); @endcode
489 * The @c ec parameter contains the result from the most recent connect
490 * operation. Before the first connection attempt, @c ec is always set to
491 * indicate success. The @c next parameter is the next endpoint to be tried.
492 * The function object should return true if the next endpoint should be tried,
493 * and false if it should be skipped.
495 * @returns An iterator denoting the successfully connected endpoint.
497 * @throws boost::system::system_error Thrown on failure. If the sequence is
498 * empty, the associated @c error_code is boost::asio::error::not_found.
499 * Otherwise, contains the error from the last connection attempt.
502 * The following connect condition function object can be used to output
503 * information about the individual connection attempts:
504 * @code struct my_connect_condition
507 * const boost::system::error_code& ec,
508 * const::tcp::endpoint& next)
510 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
511 * std::cout << "Trying: " << next << std::endl;
515 * It would be used with the boost::asio::connect function as follows:
516 * @code tcp::resolver r(my_context);
517 * tcp::resolver::query q("host", "service");
518 * tcp::resolver::results_type e = r.resolve(q);
519 * tcp::socket s(my_context);
520 * tcp::resolver::results_type::iterator i = boost::asio::connect(
521 * s, e.begin(), e.end(), my_connect_condition());
522 * std::cout << "Connected to: " << i->endpoint() << std::endl; @endcode
524 template <typename Protocol, typename Executor,
525 typename Iterator, typename ConnectCondition>
526 Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin,
527 Iterator end, ConnectCondition connect_condition);
529 /// Establishes a socket connection by trying each endpoint in a sequence.
531 * This function attempts to connect a socket to one of a sequence of
532 * endpoints. It does this by repeated calls to the socket's @c connect member
533 * function, once for each endpoint in the sequence, until a connection is
534 * successfully established.
536 * @param s The socket to be connected. If the socket is already open, it will
539 * @param begin An iterator pointing to the start of a sequence of endpoints.
541 * @param end An iterator pointing to the end of a sequence of endpoints.
543 * @param connect_condition A function object that is called prior to each
544 * connection attempt. The signature of the function object must be:
545 * @code bool connect_condition(
546 * const boost::system::error_code& ec,
547 * const typename Protocol::endpoint& next); @endcode
548 * The @c ec parameter contains the result from the most recent connect
549 * operation. Before the first connection attempt, @c ec is always set to
550 * indicate success. The @c next parameter is the next endpoint to be tried.
551 * The function object should return true if the next endpoint should be tried,
552 * and false if it should be skipped.
554 * @param ec Set to indicate what error occurred, if any. If the sequence is
555 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
556 * from the last connection attempt.
558 * @returns On success, an iterator denoting the successfully connected
559 * endpoint. Otherwise, the end iterator.
562 * The following connect condition function object can be used to output
563 * information about the individual connection attempts:
564 * @code struct my_connect_condition
567 * const boost::system::error_code& ec,
568 * const::tcp::endpoint& next)
570 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
571 * std::cout << "Trying: " << next << std::endl;
575 * It would be used with the boost::asio::connect function as follows:
576 * @code tcp::resolver r(my_context);
577 * tcp::resolver::query q("host", "service");
578 * tcp::resolver::results_type e = r.resolve(q);
579 * tcp::socket s(my_context);
580 * boost::system::error_code ec;
581 * tcp::resolver::results_type::iterator i = boost::asio::connect(
582 * s, e.begin(), e.end(), my_connect_condition());
585 * // An error occurred.
589 * std::cout << "Connected to: " << i->endpoint() << std::endl;
592 template <typename Protocol, typename Executor,
593 typename Iterator, typename ConnectCondition>
594 Iterator connect(basic_socket<Protocol, Executor>& s,
595 Iterator begin, Iterator end, ConnectCondition connect_condition,
596 boost::system::error_code& ec);
601 * @defgroup async_connect boost::asio::async_connect
603 * @brief The @c async_connect function is a composed asynchronous operation
604 * that establishes a socket connection by trying each endpoint in a sequence.
608 /// Asynchronously establishes a socket connection by trying each endpoint in a
611 * This function attempts to connect a socket to one of a sequence of
612 * endpoints. It does this by repeated calls to the socket's @c async_connect
613 * member function, once for each endpoint in the sequence, until a connection
614 * is successfully established.
616 * @param s The socket to be connected. If the socket is already open, it will
619 * @param endpoints A sequence of endpoints.
621 * @param handler The handler to be called when the connect operation
622 * completes. Copies will be made of the handler as required. The function
623 * signature of the handler must be:
624 * @code void handler(
625 * // Result of operation. if the sequence is empty, set to
626 * // boost::asio::error::not_found. Otherwise, contains the
627 * // error from the last connection attempt.
628 * const boost::system::error_code& error,
630 * // On success, the successfully connected endpoint.
631 * // Otherwise, a default-constructed endpoint.
632 * const typename Protocol::endpoint& endpoint
634 * Regardless of whether the asynchronous operation completes immediately or
635 * not, the handler will not be invoked from within this function. On
636 * immediate completion, invocation of the handler will be performed in a
637 * manner equivalent to using boost::asio::post().
640 * @code tcp::resolver r(my_context);
641 * tcp::resolver::query q("host", "service");
642 * tcp::socket s(my_context);
646 * r.async_resolve(q, resolve_handler);
650 * void resolve_handler(
651 * const boost::system::error_code& ec,
652 * tcp::resolver::results_type results)
656 * boost::asio::async_connect(s, results, connect_handler);
662 * void connect_handler(
663 * const boost::system::error_code& ec,
664 * const tcp::endpoint& endpoint)
669 template <typename Protocol, typename Executor, typename EndpointSequence,
670 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
671 typename Protocol::endpoint)) RangeConnectHandler
672 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
673 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectHandler,
674 void (boost::system::error_code, typename Protocol::endpoint))
675 async_connect(basic_socket<Protocol, Executor>& s,
676 const EndpointSequence& endpoints,
677 BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler
678 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
679 typename enable_if<is_endpoint_sequence<
680 EndpointSequence>::value>::type* = 0);
682 #if !defined(BOOST_ASIO_NO_DEPRECATED)
683 /// (Deprecated: Use range overload.) Asynchronously establishes a socket
684 /// connection by trying each endpoint in a sequence.
686 * This function attempts to connect a socket to one of a sequence of
687 * endpoints. It does this by repeated calls to the socket's @c async_connect
688 * member function, once for each endpoint in the sequence, until a connection
689 * is successfully established.
691 * @param s The socket to be connected. If the socket is already open, it will
694 * @param begin An iterator pointing to the start of a sequence of endpoints.
696 * @param handler The handler to be called when the connect operation
697 * completes. Copies will be made of the handler as required. The function
698 * signature of the handler must be:
699 * @code void handler(
700 * // Result of operation. if the sequence is empty, set to
701 * // boost::asio::error::not_found. Otherwise, contains the
702 * // error from the last connection attempt.
703 * const boost::system::error_code& error,
705 * // On success, an iterator denoting the successfully
706 * // connected endpoint. Otherwise, the end iterator.
709 * Regardless of whether the asynchronous operation completes immediately or
710 * not, the handler will not be invoked from within this function. On
711 * immediate completion, invocation of the handler will be performed in a
712 * manner equivalent to using boost::asio::post().
714 * @note This overload assumes that a default constructed object of type @c
715 * Iterator represents the end of the sequence. This is a valid assumption for
716 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
718 template <typename Protocol, typename Executor, typename Iterator,
719 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
720 Iterator)) IteratorConnectHandler
721 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
722 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler,
723 void (boost::system::error_code, Iterator))
724 async_connect(basic_socket<Protocol, Executor>& s, Iterator begin,
725 BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler
726 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
727 typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
728 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
730 /// Asynchronously establishes a socket connection by trying each endpoint in a
733 * This function attempts to connect a socket to one of a sequence of
734 * endpoints. It does this by repeated calls to the socket's @c async_connect
735 * member function, once for each endpoint in the sequence, until a connection
736 * is successfully established.
738 * @param s The socket to be connected. If the socket is already open, it will
741 * @param begin An iterator pointing to the start of a sequence of endpoints.
743 * @param end An iterator pointing to the end of a sequence of endpoints.
745 * @param handler The handler to be called when the connect operation
746 * completes. Copies will be made of the handler as required. The function
747 * signature of the handler must be:
748 * @code void handler(
749 * // Result of operation. if the sequence is empty, set to
750 * // boost::asio::error::not_found. Otherwise, contains the
751 * // error from the last connection attempt.
752 * const boost::system::error_code& error,
754 * // On success, an iterator denoting the successfully
755 * // connected endpoint. Otherwise, the end iterator.
758 * Regardless of whether the asynchronous operation completes immediately or
759 * not, the handler will not be invoked from within this function. On
760 * immediate completion, invocation of the handler will be performed in a
761 * manner equivalent to using boost::asio::post().
764 * @code std::vector<tcp::endpoint> endpoints = ...;
765 * tcp::socket s(my_context);
766 * boost::asio::async_connect(s,
767 * endpoints.begin(), endpoints.end(),
772 * void connect_handler(
773 * const boost::system::error_code& ec,
774 * std::vector<tcp::endpoint>::iterator i)
779 template <typename Protocol, typename Executor, typename Iterator,
780 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
781 Iterator)) IteratorConnectHandler
782 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
783 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler,
784 void (boost::system::error_code, Iterator))
785 async_connect(basic_socket<Protocol, Executor>& s, Iterator begin, Iterator end,
786 BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler
787 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor));
789 /// Asynchronously establishes a socket connection by trying each endpoint in a
792 * This function attempts to connect a socket to one of a sequence of
793 * endpoints. It does this by repeated calls to the socket's @c async_connect
794 * member function, once for each endpoint in the sequence, until a connection
795 * is successfully established.
797 * @param s The socket to be connected. If the socket is already open, it will
800 * @param endpoints A sequence of endpoints.
802 * @param connect_condition A function object that is called prior to each
803 * connection attempt. The signature of the function object must be:
804 * @code bool connect_condition(
805 * const boost::system::error_code& ec,
806 * const typename Protocol::endpoint& next); @endcode
807 * The @c ec parameter contains the result from the most recent connect
808 * operation. Before the first connection attempt, @c ec is always set to
809 * indicate success. The @c next parameter is the next endpoint to be tried.
810 * The function object should return true if the next endpoint should be tried,
811 * and false if it should be skipped.
813 * @param handler The handler to be called when the connect operation
814 * completes. Copies will be made of the handler as required. The function
815 * signature of the handler must be:
816 * @code void handler(
817 * // Result of operation. if the sequence is empty, set to
818 * // boost::asio::error::not_found. Otherwise, contains the
819 * // error from the last connection attempt.
820 * const boost::system::error_code& error,
822 * // On success, an iterator denoting the successfully
823 * // connected endpoint. Otherwise, the end iterator.
826 * Regardless of whether the asynchronous operation completes immediately or
827 * not, the handler will not be invoked from within this function. On
828 * immediate completion, invocation of the handler will be performed in a
829 * manner equivalent to using boost::asio::post().
832 * The following connect condition function object can be used to output
833 * information about the individual connection attempts:
834 * @code struct my_connect_condition
837 * const boost::system::error_code& ec,
838 * const::tcp::endpoint& next)
840 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
841 * std::cout << "Trying: " << next << std::endl;
845 * It would be used with the boost::asio::connect function as follows:
846 * @code tcp::resolver r(my_context);
847 * tcp::resolver::query q("host", "service");
848 * tcp::socket s(my_context);
852 * r.async_resolve(q, resolve_handler);
856 * void resolve_handler(
857 * const boost::system::error_code& ec,
858 * tcp::resolver::results_type results)
862 * boost::asio::async_connect(s, results,
863 * my_connect_condition(),
870 * void connect_handler(
871 * const boost::system::error_code& ec,
872 * const tcp::endpoint& endpoint)
876 * // An error occurred.
880 * std::cout << "Connected to: " << endpoint << std::endl;
884 template <typename Protocol, typename Executor,
885 typename EndpointSequence, typename ConnectCondition,
886 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
887 typename Protocol::endpoint)) RangeConnectHandler
888 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
889 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectHandler,
890 void (boost::system::error_code, typename Protocol::endpoint))
891 async_connect(basic_socket<Protocol, Executor>& s,
892 const EndpointSequence& endpoints, ConnectCondition connect_condition,
893 BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler
894 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
895 typename enable_if<is_endpoint_sequence<
896 EndpointSequence>::value>::type* = 0);
898 #if !defined(BOOST_ASIO_NO_DEPRECATED)
899 /// (Deprecated: Use range overload.) Asynchronously establishes a socket
900 /// connection by trying each endpoint in a sequence.
902 * This function attempts to connect a socket to one of a sequence of
903 * endpoints. It does this by repeated calls to the socket's @c async_connect
904 * member function, once for each endpoint in the sequence, until a connection
905 * is successfully established.
907 * @param s The socket to be connected. If the socket is already open, it will
910 * @param begin An iterator pointing to the start of a sequence of endpoints.
912 * @param connect_condition A function object that is called prior to each
913 * connection attempt. The signature of the function object must be:
914 * @code bool connect_condition(
915 * const boost::system::error_code& ec,
916 * const typename Protocol::endpoint& next); @endcode
917 * The @c ec parameter contains the result from the most recent connect
918 * operation. Before the first connection attempt, @c ec is always set to
919 * indicate success. The @c next parameter is the next endpoint to be tried.
920 * The function object should return true if the next endpoint should be tried,
921 * and false if it should be skipped.
923 * @param handler The handler to be called when the connect operation
924 * completes. Copies will be made of the handler as required. The function
925 * signature of the handler must be:
926 * @code void handler(
927 * // Result of operation. if the sequence is empty, set to
928 * // boost::asio::error::not_found. Otherwise, contains the
929 * // error from the last connection attempt.
930 * const boost::system::error_code& error,
932 * // On success, an iterator denoting the successfully
933 * // connected endpoint. Otherwise, the end iterator.
936 * Regardless of whether the asynchronous operation completes immediately or
937 * not, the handler will not be invoked from within this function. On
938 * immediate completion, invocation of the handler will be performed in a
939 * manner equivalent to using boost::asio::post().
941 * @note This overload assumes that a default constructed object of type @c
942 * Iterator represents the end of the sequence. This is a valid assumption for
943 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
945 template <typename Protocol, typename Executor,
946 typename Iterator, typename ConnectCondition,
947 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
948 Iterator)) IteratorConnectHandler
949 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
950 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler,
951 void (boost::system::error_code, Iterator))
952 async_connect(basic_socket<Protocol, Executor>& s, Iterator begin,
953 ConnectCondition connect_condition,
954 BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler
955 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
956 typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
957 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
959 /// Asynchronously establishes a socket connection by trying each endpoint in a
962 * This function attempts to connect a socket to one of a sequence of
963 * endpoints. It does this by repeated calls to the socket's @c async_connect
964 * member function, once for each endpoint in the sequence, until a connection
965 * is successfully established.
967 * @param s The socket to be connected. If the socket is already open, it will
970 * @param begin An iterator pointing to the start of a sequence of endpoints.
972 * @param end An iterator pointing to the end of a sequence of endpoints.
974 * @param connect_condition A function object that is called prior to each
975 * connection attempt. The signature of the function object must be:
976 * @code bool connect_condition(
977 * const boost::system::error_code& ec,
978 * const typename Protocol::endpoint& next); @endcode
979 * The @c ec parameter contains the result from the most recent connect
980 * operation. Before the first connection attempt, @c ec is always set to
981 * indicate success. The @c next parameter is the next endpoint to be tried.
982 * The function object should return true if the next endpoint should be tried,
983 * and false if it should be skipped.
985 * @param handler The handler to be called when the connect operation
986 * completes. Copies will be made of the handler as required. The function
987 * signature of the handler must be:
988 * @code void handler(
989 * // Result of operation. if the sequence is empty, set to
990 * // boost::asio::error::not_found. Otherwise, contains the
991 * // error from the last connection attempt.
992 * const boost::system::error_code& error,
994 * // On success, an iterator denoting the successfully
995 * // connected endpoint. Otherwise, the end iterator.
998 * Regardless of whether the asynchronous operation completes immediately or
999 * not, the handler will not be invoked from within this function. On
1000 * immediate completion, invocation of the handler will be performed in a
1001 * manner equivalent to using boost::asio::post().
1004 * The following connect condition function object can be used to output
1005 * information about the individual connection attempts:
1006 * @code struct my_connect_condition
1009 * const boost::system::error_code& ec,
1010 * const::tcp::endpoint& next)
1012 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
1013 * std::cout << "Trying: " << next << std::endl;
1017 * It would be used with the boost::asio::connect function as follows:
1018 * @code tcp::resolver r(my_context);
1019 * tcp::resolver::query q("host", "service");
1020 * tcp::socket s(my_context);
1024 * r.async_resolve(q, resolve_handler);
1028 * void resolve_handler(
1029 * const boost::system::error_code& ec,
1030 * tcp::resolver::iterator i)
1034 * tcp::resolver::iterator end;
1035 * boost::asio::async_connect(s, i, end,
1036 * my_connect_condition(),
1043 * void connect_handler(
1044 * const boost::system::error_code& ec,
1045 * tcp::resolver::iterator i)
1049 * // An error occurred.
1053 * std::cout << "Connected to: " << i->endpoint() << std::endl;
1057 template <typename Protocol, typename Executor,
1058 typename Iterator, typename ConnectCondition,
1059 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1060 Iterator)) IteratorConnectHandler
1061 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
1062 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler,
1063 void (boost::system::error_code, Iterator))
1064 async_connect(basic_socket<Protocol, Executor>& s, Iterator begin,
1065 Iterator end, ConnectCondition connect_condition,
1066 BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler
1067 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor));
1072 } // namespace boost
1074 #include <boost/asio/detail/pop_options.hpp>
1076 #include <boost/asio/impl/connect.hpp>