1//
2// connect.hpp
3// ~~~~~~~~~~~
4//
5// Copyright (c) 2003-2024 Christopher M. Kohlhoff (chris at kohlhoff dot com)
6//
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)
9//
10
11#ifndef BOOST_ASIO_CONNECT_HPP
12#define BOOST_ASIO_CONNECT_HPP
13
14#if defined(_MSC_VER) && (_MSC_VER >= 1200)
15# pragma once
16#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
17
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>
23
24#include <boost/asio/detail/push_options.hpp>
25
26namespace boost {
27namespace asio {
28
29namespace detail
30{
31 struct default_connect_condition;
32 template <typename, typename> class initiate_async_range_connect;
33 template <typename, typename> class initiate_async_iterator_connect;
34
35 char (&has_iterator_helper(...))[2];
36
37 template <typename T>
38 char has_iterator_helper(T*, typename T::iterator* = 0);
39
40 template <typename T>
41 struct has_iterator_typedef
42 {
43 enum { value = (sizeof((has_iterator_helper)((T*)(0))) == 1) };
44 };
45} // namespace detail
46
47/// Type trait used to determine whether a type is an endpoint sequence that can
48/// be used with with @c connect and @c async_connect.
49template <typename T>
50struct is_endpoint_sequence
51{
52#if defined(GENERATING_DOCUMENTATION)
53 /// The value member is true if the type may be used as an endpoint sequence.
54 static const bool value;
55#else
56 enum
57 {
58 value = detail::has_iterator_typedef<T>::value
59 };
60#endif
61};
62
63/**
64 * @defgroup connect boost::asio::connect
65 *
66 * @brief The @c connect function is a composed operation that establishes a
67 * socket connection by trying each endpoint in a sequence.
68 */
69/*@{*/
70
71/// Establishes a socket connection by trying each endpoint in a sequence.
72/**
73 * This function attempts to connect a socket to one of a sequence of
74 * endpoints. It does this by repeated calls to the socket's @c connect member
75 * function, once for each endpoint in the sequence, until a connection is
76 * successfully established.
77 *
78 * @param s The socket to be connected. If the socket is already open, it will
79 * be closed.
80 *
81 * @param endpoints A sequence of endpoints.
82 *
83 * @returns The successfully connected endpoint.
84 *
85 * @throws boost::system::system_error Thrown on failure. If the sequence is
86 * empty, the associated @c error_code is boost::asio::error::not_found.
87 * Otherwise, contains the error from the last connection attempt.
88 *
89 * @par Example
90 * @code tcp::resolver r(my_context);
91 * tcp::resolver::query q("host", "service");
92 * tcp::socket s(my_context);
93 * boost::asio::connect(s, r.resolve(q)); @endcode
94 */
95template <typename Protocol, typename Executor, typename EndpointSequence>
96typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
97 const EndpointSequence& endpoints,
98 constraint_t<is_endpoint_sequence<EndpointSequence>::value> = 0);
99
100/// Establishes a socket connection by trying each endpoint in a sequence.
101/**
102 * This function attempts to connect a socket to one of a sequence of
103 * endpoints. It does this by repeated calls to the socket's @c connect member
104 * function, once for each endpoint in the sequence, until a connection is
105 * successfully established.
106 *
107 * @param s The socket to be connected. If the socket is already open, it will
108 * be closed.
109 *
110 * @param endpoints A sequence of endpoints.
111 *
112 * @param ec Set to indicate what error occurred, if any. If the sequence is
113 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
114 * from the last connection attempt.
115 *
116 * @returns On success, the successfully connected endpoint. Otherwise, a
117 * default-constructed endpoint.
118 *
119 * @par Example
120 * @code tcp::resolver r(my_context);
121 * tcp::resolver::query q("host", "service");
122 * tcp::socket s(my_context);
123 * boost::system::error_code ec;
124 * boost::asio::connect(s, r.resolve(q), ec);
125 * if (ec)
126 * {
127 * // An error occurred.
128 * } @endcode
129 */
130template <typename Protocol, typename Executor, typename EndpointSequence>
131typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
132 const EndpointSequence& endpoints, boost::system::error_code& ec,
133 constraint_t<is_endpoint_sequence<EndpointSequence>::value> = 0);
134
135#if !defined(BOOST_ASIO_NO_DEPRECATED)
136/// (Deprecated: Use range overload.) Establishes a socket connection by trying
137/// each endpoint in a sequence.
138/**
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.
143 *
144 * @param s The socket to be connected. If the socket is already open, it will
145 * be closed.
146 *
147 * @param begin An iterator pointing to the start of a sequence of endpoints.
148 *
149 * @returns On success, an iterator denoting the successfully connected
150 * endpoint. Otherwise, the end iterator.
151 *
152 * @throws boost::system::system_error Thrown on failure. If the sequence is
153 * empty, the associated @c error_code is boost::asio::error::not_found.
154 * Otherwise, contains the error from the last connection attempt.
155 *
156 * @note This overload assumes that a default constructed object of type @c
157 * Iterator represents the end of the sequence. This is a valid assumption for
158 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
159 */
160template <typename Protocol, typename Executor, typename Iterator>
161Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin,
162 constraint_t<!is_endpoint_sequence<Iterator>::value> = 0);
163
164/// (Deprecated: Use range overload.) Establishes a socket connection by trying
165/// each endpoint in a sequence.
166/**
167 * This function attempts to connect a socket to one of a sequence of
168 * endpoints. It does this by repeated calls to the socket's @c connect member
169 * function, once for each endpoint in the sequence, until a connection is
170 * successfully established.
171 *
172 * @param s The socket to be connected. If the socket is already open, it will
173 * be closed.
174 *
175 * @param begin An iterator pointing to the start of a sequence of endpoints.
176 *
177 * @param ec Set to indicate what error occurred, if any. If the sequence is
178 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
179 * from the last connection attempt.
180 *
181 * @returns On success, an iterator denoting the successfully connected
182 * endpoint. Otherwise, the end iterator.
183 *
184 * @note This overload assumes that a default constructed object of type @c
185 * Iterator represents the end of the sequence. This is a valid assumption for
186 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
187 */
188template <typename Protocol, typename Executor, typename Iterator>
189Iterator connect(basic_socket<Protocol, Executor>& s,
190 Iterator begin, boost::system::error_code& ec,
191 constraint_t<!is_endpoint_sequence<Iterator>::value> = 0);
192#endif // !defined(BOOST_ASIO_NO_DEPRECATED)
193
194/// Establishes a socket connection by trying each endpoint in a sequence.
195/**
196 * This function attempts to connect a socket to one of a sequence of
197 * endpoints. It does this by repeated calls to the socket's @c connect member
198 * function, once for each endpoint in the sequence, until a connection is
199 * successfully established.
200 *
201 * @param s The socket to be connected. If the socket is already open, it will
202 * be closed.
203 *
204 * @param begin An iterator pointing to the start of a sequence of endpoints.
205 *
206 * @param end An iterator pointing to the end of a sequence of endpoints.
207 *
208 * @returns An iterator denoting the successfully connected endpoint.
209 *
210 * @throws boost::system::system_error Thrown on failure. If the sequence is
211 * empty, the associated @c error_code is boost::asio::error::not_found.
212 * Otherwise, contains the error from the last connection attempt.
213 *
214 * @par Example
215 * @code tcp::resolver r(my_context);
216 * tcp::resolver::query q("host", "service");
217 * tcp::resolver::results_type e = r.resolve(q);
218 * tcp::socket s(my_context);
219 * boost::asio::connect(s, e.begin(), e.end()); @endcode
220 */
221template <typename Protocol, typename Executor, typename Iterator>
222Iterator connect(basic_socket<Protocol, Executor>& s,
223 Iterator begin, Iterator end);
224
225/// Establishes a socket connection by trying each endpoint in a sequence.
226/**
227 * This function attempts to connect a socket to one of a sequence of
228 * endpoints. It does this by repeated calls to the socket's @c connect member
229 * function, once for each endpoint in the sequence, until a connection is
230 * successfully established.
231 *
232 * @param s The socket to be connected. If the socket is already open, it will
233 * be closed.
234 *
235 * @param begin An iterator pointing to the start of a sequence of endpoints.
236 *
237 * @param end An iterator pointing to the end of a sequence of endpoints.
238 *
239 * @param ec Set to indicate what error occurred, if any. If the sequence is
240 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
241 * from the last connection attempt.
242 *
243 * @returns On success, an iterator denoting the successfully connected
244 * endpoint. Otherwise, the end iterator.
245 *
246 * @par Example
247 * @code tcp::resolver r(my_context);
248 * tcp::resolver::query q("host", "service");
249 * tcp::resolver::results_type e = r.resolve(q);
250 * tcp::socket s(my_context);
251 * boost::system::error_code ec;
252 * boost::asio::connect(s, e.begin(), e.end(), ec);
253 * if (ec)
254 * {
255 * // An error occurred.
256 * } @endcode
257 */
258template <typename Protocol, typename Executor, typename Iterator>
259Iterator connect(basic_socket<Protocol, Executor>& s,
260 Iterator begin, Iterator end, boost::system::error_code& ec);
261
262/// Establishes a socket connection by trying each endpoint in a sequence.
263/**
264 * This function attempts to connect a socket to one of a sequence of
265 * endpoints. It does this by repeated calls to the socket's @c connect member
266 * function, once for each endpoint in the sequence, until a connection is
267 * successfully established.
268 *
269 * @param s The socket to be connected. If the socket is already open, it will
270 * be closed.
271 *
272 * @param endpoints A sequence of endpoints.
273 *
274 * @param connect_condition A function object that is called prior to each
275 * connection attempt. The signature of the function object must be:
276 * @code bool connect_condition(
277 * const boost::system::error_code& ec,
278 * const typename Protocol::endpoint& next); @endcode
279 * The @c ec parameter contains the result from the most recent connect
280 * operation. Before the first connection attempt, @c ec is always set to
281 * indicate success. The @c next parameter is the next endpoint to be tried.
282 * The function object should return true if the next endpoint should be tried,
283 * and false if it should be skipped.
284 *
285 * @returns The successfully connected endpoint.
286 *
287 * @throws boost::system::system_error Thrown on failure. If the sequence is
288 * empty, the associated @c error_code is boost::asio::error::not_found.
289 * Otherwise, contains the error from the last connection attempt.
290 *
291 * @par Example
292 * The following connect condition function object can be used to output
293 * information about the individual connection attempts:
294 * @code struct my_connect_condition
295 * {
296 * bool operator()(
297 * const boost::system::error_code& ec,
298 * const::tcp::endpoint& next)
299 * {
300 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
301 * std::cout << "Trying: " << next << std::endl;
302 * return true;
303 * }
304 * }; @endcode
305 * It would be used with the boost::asio::connect function as follows:
306 * @code tcp::resolver r(my_context);
307 * tcp::resolver::query q("host", "service");
308 * tcp::socket s(my_context);
309 * tcp::endpoint e = boost::asio::connect(s,
310 * r.resolve(q), my_connect_condition());
311 * std::cout << "Connected to: " << e << std::endl; @endcode
312 */
313template <typename Protocol, typename Executor,
314 typename EndpointSequence, typename ConnectCondition>
315typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
316 const EndpointSequence& endpoints, ConnectCondition connect_condition,
317 constraint_t<is_endpoint_sequence<EndpointSequence>::value> = 0);
318
319/// Establishes a socket connection by trying each endpoint in a sequence.
320/**
321 * This function attempts to connect a socket to one of a sequence of
322 * endpoints. It does this by repeated calls to the socket's @c connect member
323 * function, once for each endpoint in the sequence, until a connection is
324 * successfully established.
325 *
326 * @param s The socket to be connected. If the socket is already open, it will
327 * be closed.
328 *
329 * @param endpoints A sequence of endpoints.
330 *
331 * @param connect_condition A function object that is called prior to each
332 * connection attempt. The signature of the function object must be:
333 * @code bool connect_condition(
334 * const boost::system::error_code& ec,
335 * const typename Protocol::endpoint& next); @endcode
336 * The @c ec parameter contains the result from the most recent connect
337 * operation. Before the first connection attempt, @c ec is always set to
338 * indicate success. The @c next parameter is the next endpoint to be tried.
339 * The function object should return true if the next endpoint should be tried,
340 * and false if it should be skipped.
341 *
342 * @param ec Set to indicate what error occurred, if any. If the sequence is
343 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
344 * from the last connection attempt.
345 *
346 * @returns On success, the successfully connected endpoint. Otherwise, a
347 * default-constructed endpoint.
348 *
349 * @par Example
350 * The following connect condition function object can be used to output
351 * information about the individual connection attempts:
352 * @code struct my_connect_condition
353 * {
354 * bool operator()(
355 * const boost::system::error_code& ec,
356 * const::tcp::endpoint& next)
357 * {
358 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
359 * std::cout << "Trying: " << next << std::endl;
360 * return true;
361 * }
362 * }; @endcode
363 * It would be used with the boost::asio::connect function as follows:
364 * @code tcp::resolver r(my_context);
365 * tcp::resolver::query q("host", "service");
366 * tcp::socket s(my_context);
367 * boost::system::error_code ec;
368 * tcp::endpoint e = boost::asio::connect(s,
369 * r.resolve(q), my_connect_condition(), ec);
370 * if (ec)
371 * {
372 * // An error occurred.
373 * }
374 * else
375 * {
376 * std::cout << "Connected to: " << e << std::endl;
377 * } @endcode
378 */
379template <typename Protocol, typename Executor,
380 typename EndpointSequence, typename ConnectCondition>
381typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
382 const EndpointSequence& endpoints, ConnectCondition connect_condition,
383 boost::system::error_code& ec,
384 constraint_t<is_endpoint_sequence<EndpointSequence>::value> = 0);
385
386#if !defined(BOOST_ASIO_NO_DEPRECATED)
387/// (Deprecated: Use range overload.) Establishes a socket connection by trying
388/// each endpoint in a sequence.
389/**
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.
394 *
395 * @param s The socket to be connected. If the socket is already open, it will
396 * be closed.
397 *
398 * @param begin An iterator pointing to the start of a sequence of endpoints.
399 *
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.
410 *
411 * @returns On success, an iterator denoting the successfully connected
412 * endpoint. Otherwise, the end iterator.
413 *
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.
417 *
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.
421 */
422template <typename Protocol, typename Executor,
423 typename Iterator, typename ConnectCondition>
424Iterator connect(basic_socket<Protocol, Executor>& s,
425 Iterator begin, ConnectCondition connect_condition,
426 constraint_t<!is_endpoint_sequence<Iterator>::value> = 0);
427
428/// (Deprecated: Use range overload.) Establishes a socket connection by trying
429/// each endpoint in a sequence.
430/**
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.
435 *
436 * @param s The socket to be connected. If the socket is already open, it will
437 * be closed.
438 *
439 * @param begin An iterator pointing to the start of a sequence of endpoints.
440 *
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.
451 *
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.
455 *
456 * @returns On success, an iterator denoting the successfully connected
457 * endpoint. Otherwise, the end iterator.
458 *
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.
462 */
463template <typename Protocol, typename Executor,
464 typename Iterator, typename ConnectCondition>
465Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin,
466 ConnectCondition connect_condition, boost::system::error_code& ec,
467 constraint_t<!is_endpoint_sequence<Iterator>::value> = 0);
468#endif // !defined(BOOST_ASIO_NO_DEPRECATED)
469
470/// Establishes a socket connection by trying each endpoint in a sequence.
471/**
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.
476 *
477 * @param s The socket to be connected. If the socket is already open, it will
478 * be closed.
479 *
480 * @param begin An iterator pointing to the start of a sequence of endpoints.
481 *
482 * @param end An iterator pointing to the end of a sequence of endpoints.
483 *
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.
494 *
495 * @returns An iterator denoting the successfully connected endpoint.
496 *
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.
500 *
501 * @par Example
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
505 * {
506 * bool operator()(
507 * const boost::system::error_code& ec,
508 * const::tcp::endpoint& next)
509 * {
510 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
511 * std::cout << "Trying: " << next << std::endl;
512 * return true;
513 * }
514 * }; @endcode
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
523 */
524template <typename Protocol, typename Executor,
525 typename Iterator, typename ConnectCondition>
526Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin,
527 Iterator end, ConnectCondition connect_condition);
528
529/// Establishes a socket connection by trying each endpoint in a sequence.
530/**
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.
535 *
536 * @param s The socket to be connected. If the socket is already open, it will
537 * be closed.
538 *
539 * @param begin An iterator pointing to the start of a sequence of endpoints.
540 *
541 * @param end An iterator pointing to the end of a sequence of endpoints.
542 *
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.
553 *
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.
557 *
558 * @returns On success, an iterator denoting the successfully connected
559 * endpoint. Otherwise, the end iterator.
560 *
561 * @par Example
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
565 * {
566 * bool operator()(
567 * const boost::system::error_code& ec,
568 * const::tcp::endpoint& next)
569 * {
570 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
571 * std::cout << "Trying: " << next << std::endl;
572 * return true;
573 * }
574 * }; @endcode
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());
583 * if (ec)
584 * {
585 * // An error occurred.
586 * }
587 * else
588 * {
589 * std::cout << "Connected to: " << i->endpoint() << std::endl;
590 * } @endcode
591 */
592template <typename Protocol, typename Executor,
593 typename Iterator, typename ConnectCondition>
594Iterator connect(basic_socket<Protocol, Executor>& s,
595 Iterator begin, Iterator end, ConnectCondition connect_condition,
596 boost::system::error_code& ec);
597
598/*@}*/
599
600/**
601 * @defgroup async_connect boost::asio::async_connect
602 *
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.
605 */
606/*@{*/
607
608/// Asynchronously establishes a socket connection by trying each endpoint in a
609/// sequence.
610/**
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. It is an initiating function for an @ref
615 * asynchronous_operation, and always returns immediately.
616 *
617 * @param s The socket to be connected. If the socket is already open, it will
618 * be closed.
619 *
620 * @param endpoints A sequence of endpoints.
621 *
622 * @param token The @ref completion_token that will be used to produce a
623 * completion handler, which will be called when the connect completes.
624 * Potential completion tokens include @ref use_future, @ref use_awaitable,
625 * @ref yield_context, or a function object with the correct completion
626 * signature. The function signature of the completion handler must be:
627 * @code void handler(
628 * // Result of operation. if the sequence is empty, set to
629 * // boost::asio::error::not_found. Otherwise, contains the
630 * // error from the last connection attempt.
631 * const boost::system::error_code& error,
632 *
633 * // On success, the successfully connected endpoint.
634 * // Otherwise, a default-constructed endpoint.
635 * const typename Protocol::endpoint& endpoint
636 * ); @endcode
637 * Regardless of whether the asynchronous operation completes immediately or
638 * not, the completion handler will not be invoked from within this function.
639 * On immediate completion, invocation of the handler will be performed in a
640 * manner equivalent to using boost::asio::post().
641 *
642 * @par Completion Signature
643 * @code void(boost::system::error_code, typename Protocol::endpoint) @endcode
644 *
645 * @par Example
646 * @code tcp::resolver r(my_context);
647 * tcp::resolver::query q("host", "service");
648 * tcp::socket s(my_context);
649 *
650 * // ...
651 *
652 * r.async_resolve(q, resolve_handler);
653 *
654 * // ...
655 *
656 * void resolve_handler(
657 * const boost::system::error_code& ec,
658 * tcp::resolver::results_type results)
659 * {
660 * if (!ec)
661 * {
662 * boost::asio::async_connect(s, results, connect_handler);
663 * }
664 * }
665 *
666 * // ...
667 *
668 * void connect_handler(
669 * const boost::system::error_code& ec,
670 * const tcp::endpoint& endpoint)
671 * {
672 * // ...
673 * } @endcode
674 *
675 * @par Per-Operation Cancellation
676 * This asynchronous operation supports cancellation for the following
677 * boost::asio::cancellation_type values:
678 *
679 * @li @c cancellation_type::terminal
680 *
681 * @li @c cancellation_type::partial
682 *
683 * if they are also supported by the socket's @c async_connect operation.
684 */
685template <typename Protocol, typename Executor, typename EndpointSequence,
686 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
687 typename Protocol::endpoint)) RangeConnectToken
688 = default_completion_token_t<Executor>>
689auto async_connect(basic_socket<Protocol, Executor>& s,
690 const EndpointSequence& endpoints,
691 RangeConnectToken&& token = default_completion_token_t<Executor>(),
692 constraint_t<is_endpoint_sequence<EndpointSequence>::value> = 0)
693 -> decltype(
694 async_initiate<RangeConnectToken,
695 void (boost::system::error_code, typename Protocol::endpoint)>(
696 declval<detail::initiate_async_range_connect<Protocol, Executor>>(),
697 token, endpoints, declval<detail::default_connect_condition>()));
698
699#if !defined(BOOST_ASIO_NO_DEPRECATED)
700/// (Deprecated: Use range overload.) Asynchronously establishes a socket
701/// connection by trying each endpoint in a sequence.
702/**
703 * This function attempts to connect a socket to one of a sequence of
704 * endpoints. It does this by repeated calls to the socket's @c async_connect
705 * member function, once for each endpoint in the sequence, until a connection
706 * is successfully established. It is an initiating function for an @ref
707 * asynchronous_operation, and always returns immediately.
708 *
709 * @param s The socket to be connected. If the socket is already open, it will
710 * be closed.
711 *
712 * @param begin An iterator pointing to the start of a sequence of endpoints.
713 *
714 * @param token The @ref completion_token that will be used to produce a
715 * completion handler, which will be called when the connect completes.
716 * Potential completion tokens include @ref use_future, @ref use_awaitable,
717 * @ref yield_context, or a function object with the correct completion
718 * signature. The function signature of the completion handler must be:
719 * @code void handler(
720 * // Result of operation. if the sequence is empty, set to
721 * // boost::asio::error::not_found. Otherwise, contains the
722 * // error from the last connection attempt.
723 * const boost::system::error_code& error,
724 *
725 * // On success, an iterator denoting the successfully
726 * // connected endpoint. Otherwise, the end iterator.
727 * Iterator iterator
728 * ); @endcode
729 * Regardless of whether the asynchronous operation completes immediately or
730 * not, the completion handler will not be invoked from within this function.
731 * On immediate completion, invocation of the handler will be performed in a
732 * manner equivalent to using boost::asio::post().
733 *
734 * @par Completion Signature
735 * @code void(boost::system::error_code, Iterator) @endcode
736 *
737 * @note This overload assumes that a default constructed object of type @c
738 * Iterator represents the end of the sequence. This is a valid assumption for
739 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
740 *
741 * @par Per-Operation Cancellation
742 * This asynchronous operation supports cancellation for the following
743 * boost::asio::cancellation_type values:
744 *
745 * @li @c cancellation_type::terminal
746 *
747 * @li @c cancellation_type::partial
748 *
749 * if they are also supported by the socket's @c async_connect operation.
750 */
751template <typename Protocol, typename Executor, typename Iterator,
752 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
753 Iterator)) IteratorConnectToken = default_completion_token_t<Executor>>
754auto async_connect(basic_socket<Protocol, Executor>& s, Iterator begin,
755 IteratorConnectToken&& token = default_completion_token_t<Executor>(),
756 constraint_t<!is_endpoint_sequence<Iterator>::value> = 0)
757 -> decltype(
758 async_initiate<IteratorConnectToken,
759 void (boost::system::error_code, Iterator)>(
760 declval<detail::initiate_async_iterator_connect<Protocol, Executor>>(),
761 token, begin, Iterator(),
762 declval<detail::default_connect_condition>()));
763#endif // !defined(BOOST_ASIO_NO_DEPRECATED)
764
765/// Asynchronously establishes a socket connection by trying each endpoint in a
766/// sequence.
767/**
768 * This function attempts to connect a socket to one of a sequence of
769 * endpoints. It does this by repeated calls to the socket's @c async_connect
770 * member function, once for each endpoint in the sequence, until a connection
771 * is successfully established. It is an initiating function for an @ref
772 * asynchronous_operation, and always returns immediately.
773 *
774 * @param s The socket to be connected. If the socket is already open, it will
775 * be closed.
776 *
777 * @param begin An iterator pointing to the start of a sequence of endpoints.
778 *
779 * @param end An iterator pointing to the end of a sequence of endpoints.
780 *
781 * @param token The @ref completion_token that will be used to produce a
782 * completion handler, which will be called when the connect completes.
783 * Potential completion tokens include @ref use_future, @ref use_awaitable,
784 * @ref yield_context, or a function object with the correct completion
785 * signature. The function signature of the completion handler must be:
786 * @code void handler(
787 * // Result of operation. if the sequence is empty, set to
788 * // boost::asio::error::not_found. Otherwise, contains the
789 * // error from the last connection attempt.
790 * const boost::system::error_code& error,
791 *
792 * // On success, an iterator denoting the successfully
793 * // connected endpoint. Otherwise, the end iterator.
794 * Iterator iterator
795 * ); @endcode
796 * Regardless of whether the asynchronous operation completes immediately or
797 * not, the completion handler will not be invoked from within this function.
798 * On immediate completion, invocation of the handler will be performed in a
799 * manner equivalent to using boost::asio::post().
800 *
801 * @par Completion Signature
802 * @code void(boost::system::error_code, Iterator) @endcode
803 *
804 * @par Example
805 * @code std::vector<tcp::endpoint> endpoints = ...;
806 * tcp::socket s(my_context);
807 * boost::asio::async_connect(s,
808 * endpoints.begin(), endpoints.end(),
809 * connect_handler);
810 *
811 * // ...
812 *
813 * void connect_handler(
814 * const boost::system::error_code& ec,
815 * std::vector<tcp::endpoint>::iterator i)
816 * {
817 * // ...
818 * } @endcode
819 *
820 * @par Per-Operation Cancellation
821 * This asynchronous operation supports cancellation for the following
822 * boost::asio::cancellation_type values:
823 *
824 * @li @c cancellation_type::terminal
825 *
826 * @li @c cancellation_type::partial
827 *
828 * if they are also supported by the socket's @c async_connect operation.
829 */
830template <typename Protocol, typename Executor, typename Iterator,
831 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
832 Iterator)) IteratorConnectToken = default_completion_token_t<Executor>>
833auto async_connect(
834 basic_socket<Protocol, Executor>& s, Iterator begin, Iterator end,
835 IteratorConnectToken&& token = default_completion_token_t<Executor>())
836 -> decltype(
837 async_initiate<IteratorConnectToken,
838 void (boost::system::error_code, Iterator)>(
839 declval<detail::initiate_async_iterator_connect<Protocol, Executor>>(),
840 token, begin, end, declval<detail::default_connect_condition>()));
841
842/// Asynchronously establishes a socket connection by trying each endpoint in a
843/// sequence.
844/**
845 * This function attempts to connect a socket to one of a sequence of
846 * endpoints. It does this by repeated calls to the socket's @c async_connect
847 * member function, once for each endpoint in the sequence, until a connection
848 * is successfully established. It is an initiating function for an @ref
849 * asynchronous_operation, and always returns immediately.
850 *
851 * @param s The socket to be connected. If the socket is already open, it will
852 * be closed.
853 *
854 * @param endpoints A sequence of endpoints.
855 *
856 * @param connect_condition A function object that is called prior to each
857 * connection attempt. The signature of the function object must be:
858 * @code bool connect_condition(
859 * const boost::system::error_code& ec,
860 * const typename Protocol::endpoint& next); @endcode
861 * The @c ec parameter contains the result from the most recent connect
862 * operation. Before the first connection attempt, @c ec is always set to
863 * indicate success. The @c next parameter is the next endpoint to be tried.
864 * The function object should return true if the next endpoint should be tried,
865 * and false if it should be skipped.
866 *
867 * @param token The @ref completion_token that will be used to produce a
868 * completion handler, which will be called when the connect completes.
869 * Potential completion tokens include @ref use_future, @ref use_awaitable,
870 * @ref yield_context, or a function object with the correct completion
871 * signature. The function signature of the completion handler must be:
872 * @code void handler(
873 * // Result of operation. if the sequence is empty, set to
874 * // boost::asio::error::not_found. Otherwise, contains the
875 * // error from the last connection attempt.
876 * const boost::system::error_code& error,
877 *
878 * // On success, an iterator denoting the successfully
879 * // connected endpoint. Otherwise, the end iterator.
880 * Iterator iterator
881 * ); @endcode
882 * Regardless of whether the asynchronous operation completes immediately or
883 * not, the completion handler will not be invoked from within this function.
884 * On immediate completion, invocation of the handler will be performed in a
885 * manner equivalent to using boost::asio::post().
886 *
887 * @par Completion Signature
888 * @code void(boost::system::error_code, typename Protocol::endpoint) @endcode
889 *
890 * @par Example
891 * The following connect condition function object can be used to output
892 * information about the individual connection attempts:
893 * @code struct my_connect_condition
894 * {
895 * bool operator()(
896 * const boost::system::error_code& ec,
897 * const::tcp::endpoint& next)
898 * {
899 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
900 * std::cout << "Trying: " << next << std::endl;
901 * return true;
902 * }
903 * }; @endcode
904 * It would be used with the boost::asio::connect function as follows:
905 * @code tcp::resolver r(my_context);
906 * tcp::resolver::query q("host", "service");
907 * tcp::socket s(my_context);
908 *
909 * // ...
910 *
911 * r.async_resolve(q, resolve_handler);
912 *
913 * // ...
914 *
915 * void resolve_handler(
916 * const boost::system::error_code& ec,
917 * tcp::resolver::results_type results)
918 * {
919 * if (!ec)
920 * {
921 * boost::asio::async_connect(s, results,
922 * my_connect_condition(),
923 * connect_handler);
924 * }
925 * }
926 *
927 * // ...
928 *
929 * void connect_handler(
930 * const boost::system::error_code& ec,
931 * const tcp::endpoint& endpoint)
932 * {
933 * if (ec)
934 * {
935 * // An error occurred.
936 * }
937 * else
938 * {
939 * std::cout << "Connected to: " << endpoint << std::endl;
940 * }
941 * } @endcode
942 *
943 * @par Per-Operation Cancellation
944 * This asynchronous operation supports cancellation for the following
945 * boost::asio::cancellation_type values:
946 *
947 * @li @c cancellation_type::terminal
948 *
949 * @li @c cancellation_type::partial
950 *
951 * if they are also supported by the socket's @c async_connect operation.
952 */
953template <typename Protocol, typename Executor,
954 typename EndpointSequence, typename ConnectCondition,
955 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
956 typename Protocol::endpoint)) RangeConnectToken
957 = default_completion_token_t<Executor>>
958auto async_connect(basic_socket<Protocol, Executor>& s,
959 const EndpointSequence& endpoints, ConnectCondition connect_condition,
960 RangeConnectToken&& token = default_completion_token_t<Executor>(),
961 constraint_t<is_endpoint_sequence<EndpointSequence>::value> = 0)
962 -> decltype(
963 async_initiate<RangeConnectToken,
964 void (boost::system::error_code, typename Protocol::endpoint)>(
965 declval<detail::initiate_async_range_connect<Protocol, Executor>>(),
966 token, endpoints, connect_condition));
967
968#if !defined(BOOST_ASIO_NO_DEPRECATED)
969/// (Deprecated: Use range overload.) Asynchronously establishes a socket
970/// connection by trying each endpoint in a sequence.
971/**
972 * This function attempts to connect a socket to one of a sequence of
973 * endpoints. It does this by repeated calls to the socket's @c async_connect
974 * member function, once for each endpoint in the sequence, until a connection
975 * is successfully established. It is an initiating function for an @ref
976 * asynchronous_operation, and always returns immediately.
977 *
978 * @param s The socket to be connected. If the socket is already open, it will
979 * be closed.
980 *
981 * @param begin An iterator pointing to the start of a sequence of endpoints.
982 *
983 * @param connect_condition A function object that is called prior to each
984 * connection attempt. The signature of the function object must be:
985 * @code bool connect_condition(
986 * const boost::system::error_code& ec,
987 * const typename Protocol::endpoint& next); @endcode
988 * The @c ec parameter contains the result from the most recent connect
989 * operation. Before the first connection attempt, @c ec is always set to
990 * indicate success. The @c next parameter is the next endpoint to be tried.
991 * The function object should return true if the next endpoint should be tried,
992 * and false if it should be skipped.
993 *
994 * @param token The @ref completion_token that will be used to produce a
995 * completion handler, which will be called when the connect completes.
996 * Potential completion tokens include @ref use_future, @ref use_awaitable,
997 * @ref yield_context, or a function object with the correct completion
998 * signature. The function signature of the completion handler must be:
999 * @code void handler(
1000 * // Result of operation. if the sequence is empty, set to
1001 * // boost::asio::error::not_found. Otherwise, contains the
1002 * // error from the last connection attempt.
1003 * const boost::system::error_code& error,
1004 *
1005 * // On success, an iterator denoting the successfully
1006 * // connected endpoint. Otherwise, the end iterator.
1007 * Iterator iterator
1008 * ); @endcode
1009 * Regardless of whether the asynchronous operation completes immediately or
1010 * not, the completion handler will not be invoked from within this function.
1011 * On immediate completion, invocation of the handler will be performed in a
1012 * manner equivalent to using boost::asio::post().
1013 *
1014 * @par Completion Signature
1015 * @code void(boost::system::error_code, Iterator) @endcode
1016 *
1017 * @note This overload assumes that a default constructed object of type @c
1018 * Iterator represents the end of the sequence. This is a valid assumption for
1019 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
1020 *
1021 * @par Per-Operation Cancellation
1022 * This asynchronous operation supports cancellation for the following
1023 * boost::asio::cancellation_type values:
1024 *
1025 * @li @c cancellation_type::terminal
1026 *
1027 * @li @c cancellation_type::partial
1028 *
1029 * if they are also supported by the socket's @c async_connect operation.
1030 */
1031template <typename Protocol, typename Executor,
1032 typename Iterator, typename ConnectCondition,
1033 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1034 Iterator)) IteratorConnectToken = default_completion_token_t<Executor>>
1035auto async_connect(basic_socket<Protocol, Executor>& s,
1036 Iterator begin, ConnectCondition connect_condition,
1037 IteratorConnectToken&& token = default_completion_token_t<Executor>(),
1038 constraint_t<!is_endpoint_sequence<Iterator>::value> = 0)
1039 -> decltype(
1040 async_initiate<IteratorConnectToken,
1041 void (boost::system::error_code, Iterator)>(
1042 declval<detail::initiate_async_iterator_connect<Protocol, Executor>>(),
1043 token, begin, Iterator(), connect_condition));
1044#endif // !defined(BOOST_ASIO_NO_DEPRECATED)
1045
1046/// Asynchronously establishes a socket connection by trying each endpoint in a
1047/// sequence.
1048/**
1049 * This function attempts to connect a socket to one of a sequence of
1050 * endpoints. It does this by repeated calls to the socket's @c async_connect
1051 * member function, once for each endpoint in the sequence, until a connection
1052 * is successfully established. It is an initiating function for an @ref
1053 * asynchronous_operation, and always returns immediately.
1054 *
1055 * @param s The socket to be connected. If the socket is already open, it will
1056 * be closed.
1057 *
1058 * @param begin An iterator pointing to the start of a sequence of endpoints.
1059 *
1060 * @param end An iterator pointing to the end of a sequence of endpoints.
1061 *
1062 * @param connect_condition A function object that is called prior to each
1063 * connection attempt. The signature of the function object must be:
1064 * @code bool connect_condition(
1065 * const boost::system::error_code& ec,
1066 * const typename Protocol::endpoint& next); @endcode
1067 * The @c ec parameter contains the result from the most recent connect
1068 * operation. Before the first connection attempt, @c ec is always set to
1069 * indicate success. The @c next parameter is the next endpoint to be tried.
1070 * The function object should return true if the next endpoint should be tried,
1071 * and false if it should be skipped.
1072 *
1073 * @param token The @ref completion_token that will be used to produce a
1074 * completion handler, which will be called when the connect completes.
1075 * Potential completion tokens include @ref use_future, @ref use_awaitable,
1076 * @ref yield_context, or a function object with the correct completion
1077 * signature. The function signature of the completion handler must be:
1078 * @code void handler(
1079 * // Result of operation. if the sequence is empty, set to
1080 * // boost::asio::error::not_found. Otherwise, contains the
1081 * // error from the last connection attempt.
1082 * const boost::system::error_code& error,
1083 *
1084 * // On success, an iterator denoting the successfully
1085 * // connected endpoint. Otherwise, the end iterator.
1086 * Iterator iterator
1087 * ); @endcode
1088 * Regardless of whether the asynchronous operation completes immediately or
1089 * not, the completion handler will not be invoked from within this function.
1090 * On immediate completion, invocation of the handler will be performed in a
1091 * manner equivalent to using boost::asio::post().
1092 *
1093 * @par Completion Signature
1094 * @code void(boost::system::error_code, Iterator) @endcode
1095 *
1096 * @par Example
1097 * The following connect condition function object can be used to output
1098 * information about the individual connection attempts:
1099 * @code struct my_connect_condition
1100 * {
1101 * bool operator()(
1102 * const boost::system::error_code& ec,
1103 * const::tcp::endpoint& next)
1104 * {
1105 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
1106 * std::cout << "Trying: " << next << std::endl;
1107 * return true;
1108 * }
1109 * }; @endcode
1110 * It would be used with the boost::asio::connect function as follows:
1111 * @code tcp::resolver r(my_context);
1112 * tcp::resolver::query q("host", "service");
1113 * tcp::socket s(my_context);
1114 *
1115 * // ...
1116 *
1117 * r.async_resolve(q, resolve_handler);
1118 *
1119 * // ...
1120 *
1121 * void resolve_handler(
1122 * const boost::system::error_code& ec,
1123 * tcp::resolver::iterator i)
1124 * {
1125 * if (!ec)
1126 * {
1127 * tcp::resolver::iterator end;
1128 * boost::asio::async_connect(s, i, end,
1129 * my_connect_condition(),
1130 * connect_handler);
1131 * }
1132 * }
1133 *
1134 * // ...
1135 *
1136 * void connect_handler(
1137 * const boost::system::error_code& ec,
1138 * tcp::resolver::iterator i)
1139 * {
1140 * if (ec)
1141 * {
1142 * // An error occurred.
1143 * }
1144 * else
1145 * {
1146 * std::cout << "Connected to: " << i->endpoint() << std::endl;
1147 * }
1148 * } @endcode
1149 *
1150 * @par Per-Operation Cancellation
1151 * This asynchronous operation supports cancellation for the following
1152 * boost::asio::cancellation_type values:
1153 *
1154 * @li @c cancellation_type::terminal
1155 *
1156 * @li @c cancellation_type::partial
1157 *
1158 * if they are also supported by the socket's @c async_connect operation.
1159 */
1160template <typename Protocol, typename Executor,
1161 typename Iterator, typename ConnectCondition,
1162 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1163 Iterator)) IteratorConnectToken = default_completion_token_t<Executor>>
1164auto async_connect(basic_socket<Protocol, Executor>& s,
1165 Iterator begin, Iterator end, ConnectCondition connect_condition,
1166 IteratorConnectToken&& token = default_completion_token_t<Executor>())
1167 -> decltype(
1168 async_initiate<IteratorConnectToken,
1169 void (boost::system::error_code, Iterator)>(
1170 declval<detail::initiate_async_iterator_connect<Protocol, Executor>>(),
1171 token, begin, end, connect_condition));
1172
1173/*@}*/
1174
1175} // namespace asio
1176} // namespace boost
1177
1178#include <boost/asio/detail/pop_options.hpp>
1179
1180#include <boost/asio/impl/connect.hpp>
1181
1182#endif
1183

source code of boost/libs/asio/include/boost/asio/connect.hpp