1//
2// connect.hpp
3// ~~~~~~~~~~~
4//
5// Copyright (c) 2003-2015 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/error.hpp>
22
23#include <boost/asio/detail/push_options.hpp>
24
25namespace boost {
26namespace asio {
27
28/**
29 * @defgroup connect boost::asio::connect
30 *
31 * @brief Establishes a socket connection by trying each endpoint in a sequence.
32 */
33/*@{*/
34
35/// Establishes a socket connection by trying each endpoint in a sequence.
36/**
37 * This function attempts to connect a socket to one of a sequence of
38 * endpoints. It does this by repeated calls to the socket's @c connect member
39 * function, once for each endpoint in the sequence, until a connection is
40 * successfully established.
41 *
42 * @param s The socket to be connected. If the socket is already open, it will
43 * be closed.
44 *
45 * @param begin An iterator pointing to the start of a sequence of endpoints.
46 *
47 * @returns On success, an iterator denoting the successfully connected
48 * endpoint. Otherwise, the end iterator.
49 *
50 * @throws boost::system::system_error Thrown on failure. If the sequence is
51 * empty, the associated @c error_code is boost::asio::error::not_found.
52 * Otherwise, contains the error from the last connection attempt.
53 *
54 * @note This overload assumes that a default constructed object of type @c
55 * Iterator represents the end of the sequence. This is a valid assumption for
56 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
57 *
58 * @par Example
59 * @code tcp::resolver r(io_service);
60 * tcp::resolver::query q("host", "service");
61 * tcp::socket s(io_service);
62 * boost::asio::connect(s, r.resolve(q)); @endcode
63 */
64template <typename Protocol, typename SocketService, typename Iterator>
65Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin);
66
67/// Establishes a socket connection by trying each endpoint in a sequence.
68/**
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.
73 *
74 * @param s The socket to be connected. If the socket is already open, it will
75 * be closed.
76 *
77 * @param begin An iterator pointing to the start of a sequence of endpoints.
78 *
79 * @param ec Set to indicate what error occurred, if any. If the sequence is
80 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
81 * from the last connection attempt.
82 *
83 * @returns On success, an iterator denoting the successfully connected
84 * endpoint. Otherwise, the end iterator.
85 *
86 * @note This overload assumes that a default constructed object of type @c
87 * Iterator represents the end of the sequence. This is a valid assumption for
88 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
89 *
90 * @par Example
91 * @code tcp::resolver r(io_service);
92 * tcp::resolver::query q("host", "service");
93 * tcp::socket s(io_service);
94 * boost::system::error_code ec;
95 * boost::asio::connect(s, r.resolve(q), ec);
96 * if (ec)
97 * {
98 * // An error occurred.
99 * } @endcode
100 */
101template <typename Protocol, typename SocketService, typename Iterator>
102Iterator connect(basic_socket<Protocol, SocketService>& s,
103 Iterator begin, boost::system::error_code& ec);
104
105/// Establishes a socket connection by trying each endpoint in a sequence.
106/**
107 * This function attempts to connect a socket to one of a sequence of
108 * endpoints. It does this by repeated calls to the socket's @c connect member
109 * function, once for each endpoint in the sequence, until a connection is
110 * successfully established.
111 *
112 * @param s The socket to be connected. If the socket is already open, it will
113 * be closed.
114 *
115 * @param begin An iterator pointing to the start of a sequence of endpoints.
116 *
117 * @param end An iterator pointing to the end of a sequence of endpoints.
118 *
119 * @returns On success, an iterator denoting the successfully connected
120 * endpoint. Otherwise, the end iterator.
121 *
122 * @throws boost::system::system_error Thrown on failure. If the sequence is
123 * empty, the associated @c error_code is boost::asio::error::not_found.
124 * Otherwise, contains the error from the last connection attempt.
125 *
126 * @par Example
127 * @code tcp::resolver r(io_service);
128 * tcp::resolver::query q("host", "service");
129 * tcp::resolver::iterator i = r.resolve(q), end;
130 * tcp::socket s(io_service);
131 * boost::asio::connect(s, i, end); @endcode
132 */
133template <typename Protocol, typename SocketService, typename Iterator>
134Iterator connect(basic_socket<Protocol, SocketService>& s,
135 Iterator begin, Iterator end);
136
137/// Establishes a socket connection by trying 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 * @param end An iterator pointing to the end of a sequence of endpoints.
150 *
151 * @param ec Set to indicate what error occurred, if any. If the sequence is
152 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
153 * from the last connection attempt.
154 *
155 * @returns On success, an iterator denoting the successfully connected
156 * endpoint. Otherwise, the end iterator.
157 *
158 * @par Example
159 * @code tcp::resolver r(io_service);
160 * tcp::resolver::query q("host", "service");
161 * tcp::resolver::iterator i = r.resolve(q), end;
162 * tcp::socket s(io_service);
163 * boost::system::error_code ec;
164 * boost::asio::connect(s, i, end, ec);
165 * if (ec)
166 * {
167 * // An error occurred.
168 * } @endcode
169 */
170template <typename Protocol, typename SocketService, typename Iterator>
171Iterator connect(basic_socket<Protocol, SocketService>& s,
172 Iterator begin, Iterator end, boost::system::error_code& ec);
173
174/// Establishes a socket connection by trying each endpoint in a sequence.
175/**
176 * This function attempts to connect a socket to one of a sequence of
177 * endpoints. It does this by repeated calls to the socket's @c connect member
178 * function, once for each endpoint in the sequence, until a connection is
179 * successfully established.
180 *
181 * @param s The socket to be connected. If the socket is already open, it will
182 * be closed.
183 *
184 * @param begin An iterator pointing to the start of a sequence of endpoints.
185 *
186 * @param connect_condition A function object that is called prior to each
187 * connection attempt. The signature of the function object must be:
188 * @code Iterator connect_condition(
189 * const boost::system::error_code& ec,
190 * Iterator next); @endcode
191 * The @c ec parameter contains the result from the most recent connect
192 * operation. Before the first connection attempt, @c ec is always set to
193 * indicate success. The @c next parameter is an iterator pointing to the next
194 * endpoint to be tried. The function object should return the next iterator,
195 * but is permitted to return a different iterator so that endpoints may be
196 * skipped. The implementation guarantees that the function object will never
197 * be called with the end iterator.
198 *
199 * @returns On success, an iterator denoting the successfully connected
200 * endpoint. Otherwise, the end iterator.
201 *
202 * @throws boost::system::system_error Thrown on failure. If the sequence is
203 * empty, the associated @c error_code is boost::asio::error::not_found.
204 * Otherwise, contains the error from the last connection attempt.
205 *
206 * @note This overload assumes that a default constructed object of type @c
207 * Iterator represents the end of the sequence. This is a valid assumption for
208 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
209 *
210 * @par Example
211 * The following connect condition function object can be used to output
212 * information about the individual connection attempts:
213 * @code struct my_connect_condition
214 * {
215 * template <typename Iterator>
216 * Iterator operator()(
217 * const boost::system::error_code& ec,
218 * Iterator next)
219 * {
220 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
221 * std::cout << "Trying: " << next->endpoint() << std::endl;
222 * return next;
223 * }
224 * }; @endcode
225 * It would be used with the boost::asio::connect function as follows:
226 * @code tcp::resolver r(io_service);
227 * tcp::resolver::query q("host", "service");
228 * tcp::socket s(io_service);
229 * tcp::resolver::iterator i = boost::asio::connect(
230 * s, r.resolve(q), my_connect_condition());
231 * std::cout << "Connected to: " << i->endpoint() << std::endl; @endcode
232 */
233template <typename Protocol, typename SocketService,
234 typename Iterator, typename ConnectCondition>
235Iterator connect(basic_socket<Protocol, SocketService>& s,
236 Iterator begin, ConnectCondition connect_condition);
237
238/// Establishes a socket connection by trying each endpoint in a sequence.
239/**
240 * This function attempts to connect a socket to one of a sequence of
241 * endpoints. It does this by repeated calls to the socket's @c connect member
242 * function, once for each endpoint in the sequence, until a connection is
243 * successfully established.
244 *
245 * @param s The socket to be connected. If the socket is already open, it will
246 * be closed.
247 *
248 * @param begin An iterator pointing to the start of a sequence of endpoints.
249 *
250 * @param connect_condition A function object that is called prior to each
251 * connection attempt. The signature of the function object must be:
252 * @code Iterator connect_condition(
253 * const boost::system::error_code& ec,
254 * Iterator next); @endcode
255 * The @c ec parameter contains the result from the most recent connect
256 * operation. Before the first connection attempt, @c ec is always set to
257 * indicate success. The @c next parameter is an iterator pointing to the next
258 * endpoint to be tried. The function object should return the next iterator,
259 * but is permitted to return a different iterator so that endpoints may be
260 * skipped. The implementation guarantees that the function object will never
261 * be called with the end iterator.
262 *
263 * @param ec Set to indicate what error occurred, if any. If the sequence is
264 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
265 * from the last connection attempt.
266 *
267 * @returns On success, an iterator denoting the successfully connected
268 * endpoint. Otherwise, the end iterator.
269 *
270 * @note This overload assumes that a default constructed object of type @c
271 * Iterator represents the end of the sequence. This is a valid assumption for
272 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
273 *
274 * @par Example
275 * The following connect condition function object can be used to output
276 * information about the individual connection attempts:
277 * @code struct my_connect_condition
278 * {
279 * template <typename Iterator>
280 * Iterator operator()(
281 * const boost::system::error_code& ec,
282 * Iterator next)
283 * {
284 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
285 * std::cout << "Trying: " << next->endpoint() << std::endl;
286 * return next;
287 * }
288 * }; @endcode
289 * It would be used with the boost::asio::connect function as follows:
290 * @code tcp::resolver r(io_service);
291 * tcp::resolver::query q("host", "service");
292 * tcp::socket s(io_service);
293 * boost::system::error_code ec;
294 * tcp::resolver::iterator i = boost::asio::connect(
295 * s, r.resolve(q), my_connect_condition(), ec);
296 * if (ec)
297 * {
298 * // An error occurred.
299 * }
300 * else
301 * {
302 * std::cout << "Connected to: " << i->endpoint() << std::endl;
303 * } @endcode
304 */
305template <typename Protocol, typename SocketService,
306 typename Iterator, typename ConnectCondition>
307Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin,
308 ConnectCondition connect_condition, boost::system::error_code& ec);
309
310/// Establishes a socket connection by trying each endpoint in a sequence.
311/**
312 * This function attempts to connect a socket to one of a sequence of
313 * endpoints. It does this by repeated calls to the socket's @c connect member
314 * function, once for each endpoint in the sequence, until a connection is
315 * successfully established.
316 *
317 * @param s The socket to be connected. If the socket is already open, it will
318 * be closed.
319 *
320 * @param begin An iterator pointing to the start of a sequence of endpoints.
321 *
322 * @param end An iterator pointing to the end of a sequence of endpoints.
323 *
324 * @param connect_condition A function object that is called prior to each
325 * connection attempt. The signature of the function object must be:
326 * @code Iterator connect_condition(
327 * const boost::system::error_code& ec,
328 * Iterator next); @endcode
329 * The @c ec parameter contains the result from the most recent connect
330 * operation. Before the first connection attempt, @c ec is always set to
331 * indicate success. The @c next parameter is an iterator pointing to the next
332 * endpoint to be tried. The function object should return the next iterator,
333 * but is permitted to return a different iterator so that endpoints may be
334 * skipped. The implementation guarantees that the function object will never
335 * be called with the end iterator.
336 *
337 * @returns On success, an iterator denoting the successfully connected
338 * endpoint. Otherwise, the end iterator.
339 *
340 * @throws boost::system::system_error Thrown on failure. If the sequence is
341 * empty, the associated @c error_code is boost::asio::error::not_found.
342 * Otherwise, contains the error from the last connection attempt.
343 *
344 * @par Example
345 * The following connect condition function object can be used to output
346 * information about the individual connection attempts:
347 * @code struct my_connect_condition
348 * {
349 * template <typename Iterator>
350 * Iterator operator()(
351 * const boost::system::error_code& ec,
352 * Iterator next)
353 * {
354 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
355 * std::cout << "Trying: " << next->endpoint() << std::endl;
356 * return next;
357 * }
358 * }; @endcode
359 * It would be used with the boost::asio::connect function as follows:
360 * @code tcp::resolver r(io_service);
361 * tcp::resolver::query q("host", "service");
362 * tcp::resolver::iterator i = r.resolve(q), end;
363 * tcp::socket s(io_service);
364 * i = boost::asio::connect(s, i, end, my_connect_condition());
365 * std::cout << "Connected to: " << i->endpoint() << std::endl; @endcode
366 */
367template <typename Protocol, typename SocketService,
368 typename Iterator, typename ConnectCondition>
369Iterator connect(basic_socket<Protocol, SocketService>& s, Iterator begin,
370 Iterator end, ConnectCondition connect_condition);
371
372/// Establishes a socket connection by trying each endpoint in a sequence.
373/**
374 * This function attempts to connect a socket to one of a sequence of
375 * endpoints. It does this by repeated calls to the socket's @c connect member
376 * function, once for each endpoint in the sequence, until a connection is
377 * successfully established.
378 *
379 * @param s The socket to be connected. If the socket is already open, it will
380 * be closed.
381 *
382 * @param begin An iterator pointing to the start of a sequence of endpoints.
383 *
384 * @param end An iterator pointing to the end of a sequence of endpoints.
385 *
386 * @param connect_condition A function object that is called prior to each
387 * connection attempt. The signature of the function object must be:
388 * @code Iterator connect_condition(
389 * const boost::system::error_code& ec,
390 * Iterator next); @endcode
391 * The @c ec parameter contains the result from the most recent connect
392 * operation. Before the first connection attempt, @c ec is always set to
393 * indicate success. The @c next parameter is an iterator pointing to the next
394 * endpoint to be tried. The function object should return the next iterator,
395 * but is permitted to return a different iterator so that endpoints may be
396 * skipped. The implementation guarantees that the function object will never
397 * be called with the end iterator.
398 *
399 * @param ec Set to indicate what error occurred, if any. If the sequence is
400 * empty, set to boost::asio::error::not_found. Otherwise, contains the error
401 * from the last connection attempt.
402 *
403 * @returns On success, an iterator denoting the successfully connected
404 * endpoint. Otherwise, the end iterator.
405 *
406 * @par Example
407 * The following connect condition function object can be used to output
408 * information about the individual connection attempts:
409 * @code struct my_connect_condition
410 * {
411 * template <typename Iterator>
412 * Iterator operator()(
413 * const boost::system::error_code& ec,
414 * Iterator next)
415 * {
416 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
417 * std::cout << "Trying: " << next->endpoint() << std::endl;
418 * return next;
419 * }
420 * }; @endcode
421 * It would be used with the boost::asio::connect function as follows:
422 * @code tcp::resolver r(io_service);
423 * tcp::resolver::query q("host", "service");
424 * tcp::resolver::iterator i = r.resolve(q), end;
425 * tcp::socket s(io_service);
426 * boost::system::error_code ec;
427 * i = boost::asio::connect(s, i, end, my_connect_condition(), ec);
428 * if (ec)
429 * {
430 * // An error occurred.
431 * }
432 * else
433 * {
434 * std::cout << "Connected to: " << i->endpoint() << std::endl;
435 * } @endcode
436 */
437template <typename Protocol, typename SocketService,
438 typename Iterator, typename ConnectCondition>
439Iterator connect(basic_socket<Protocol, SocketService>& s,
440 Iterator begin, Iterator end, ConnectCondition connect_condition,
441 boost::system::error_code& ec);
442
443/*@}*/
444
445/**
446 * @defgroup async_connect boost::asio::async_connect
447 *
448 * @brief Asynchronously establishes a socket connection by trying each
449 * endpoint in a sequence.
450 */
451/*@{*/
452
453/// Asynchronously establishes a socket connection by trying each endpoint in a
454/// sequence.
455/**
456 * This function attempts to connect a socket to one of a sequence of
457 * endpoints. It does this by repeated calls to the socket's @c async_connect
458 * member function, once for each endpoint in the sequence, until a connection
459 * is successfully established.
460 *
461 * @param s The socket to be connected. If the socket is already open, it will
462 * be closed.
463 *
464 * @param begin An iterator pointing to the start of a sequence of endpoints.
465 *
466 * @param handler The handler to be called when the connect operation
467 * completes. Copies will be made of the handler as required. The function
468 * signature of the handler must be:
469 * @code void handler(
470 * // Result of operation. if the sequence is empty, set to
471 * // boost::asio::error::not_found. Otherwise, contains the
472 * // error from the last connection attempt.
473 * const boost::system::error_code& error,
474 *
475 * // On success, an iterator denoting the successfully
476 * // connected endpoint. Otherwise, the end iterator.
477 * Iterator iterator
478 * ); @endcode
479 * Regardless of whether the asynchronous operation completes immediately or
480 * not, the handler will not be invoked from within this function. Invocation
481 * of the handler will be performed in a manner equivalent to using
482 * boost::asio::io_service::post().
483 *
484 * @note This overload assumes that a default constructed object of type @c
485 * Iterator represents the end of the sequence. This is a valid assumption for
486 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
487 *
488 * @par Example
489 * @code tcp::resolver r(io_service);
490 * tcp::resolver::query q("host", "service");
491 * tcp::socket s(io_service);
492 *
493 * // ...
494 *
495 * r.async_resolve(q, resolve_handler);
496 *
497 * // ...
498 *
499 * void resolve_handler(
500 * const boost::system::error_code& ec,
501 * tcp::resolver::iterator i)
502 * {
503 * if (!ec)
504 * {
505 * boost::asio::async_connect(s, i, connect_handler);
506 * }
507 * }
508 *
509 * // ...
510 *
511 * void connect_handler(
512 * const boost::system::error_code& ec,
513 * tcp::resolver::iterator i)
514 * {
515 * // ...
516 * } @endcode
517 */
518template <typename Protocol, typename SocketService,
519 typename Iterator, typename ComposedConnectHandler>
520BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler,
521 void (boost::system::error_code, Iterator))
522async_connect(basic_socket<Protocol, SocketService>& s,
523 Iterator begin, BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler);
524
525/// Asynchronously establishes a socket connection by trying each endpoint in a
526/// sequence.
527/**
528 * This function attempts to connect a socket to one of a sequence of
529 * endpoints. It does this by repeated calls to the socket's @c async_connect
530 * member function, once for each endpoint in the sequence, until a connection
531 * is successfully established.
532 *
533 * @param s The socket to be connected. If the socket is already open, it will
534 * be closed.
535 *
536 * @param begin An iterator pointing to the start of a sequence of endpoints.
537 *
538 * @param end An iterator pointing to the end of a sequence of endpoints.
539 *
540 * @param handler The handler to be called when the connect operation
541 * completes. Copies will be made of the handler as required. The function
542 * signature of the handler must be:
543 * @code void handler(
544 * // Result of operation. if the sequence is empty, set to
545 * // boost::asio::error::not_found. Otherwise, contains the
546 * // error from the last connection attempt.
547 * const boost::system::error_code& error,
548 *
549 * // On success, an iterator denoting the successfully
550 * // connected endpoint. Otherwise, the end iterator.
551 * Iterator iterator
552 * ); @endcode
553 * Regardless of whether the asynchronous operation completes immediately or
554 * not, the handler will not be invoked from within this function. Invocation
555 * of the handler will be performed in a manner equivalent to using
556 * boost::asio::io_service::post().
557 *
558 * @par Example
559 * @code tcp::resolver r(io_service);
560 * tcp::resolver::query q("host", "service");
561 * tcp::socket s(io_service);
562 *
563 * // ...
564 *
565 * r.async_resolve(q, resolve_handler);
566 *
567 * // ...
568 *
569 * void resolve_handler(
570 * const boost::system::error_code& ec,
571 * tcp::resolver::iterator i)
572 * {
573 * if (!ec)
574 * {
575 * tcp::resolver::iterator end;
576 * boost::asio::async_connect(s, i, end, connect_handler);
577 * }
578 * }
579 *
580 * // ...
581 *
582 * void connect_handler(
583 * const boost::system::error_code& ec,
584 * tcp::resolver::iterator i)
585 * {
586 * // ...
587 * } @endcode
588 */
589template <typename Protocol, typename SocketService,
590 typename Iterator, typename ComposedConnectHandler>
591BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler,
592 void (boost::system::error_code, Iterator))
593async_connect(basic_socket<Protocol, SocketService>& s,
594 Iterator begin, Iterator end,
595 BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler);
596
597/// Asynchronously establishes a socket connection by trying each endpoint in a
598/// sequence.
599/**
600 * This function attempts to connect a socket to one of a sequence of
601 * endpoints. It does this by repeated calls to the socket's @c async_connect
602 * member function, once for each endpoint in the sequence, until a connection
603 * is successfully established.
604 *
605 * @param s The socket to be connected. If the socket is already open, it will
606 * be closed.
607 *
608 * @param begin An iterator pointing to the start of a sequence of endpoints.
609 *
610 * @param connect_condition A function object that is called prior to each
611 * connection attempt. The signature of the function object must be:
612 * @code Iterator connect_condition(
613 * const boost::system::error_code& ec,
614 * Iterator next); @endcode
615 * The @c ec parameter contains the result from the most recent connect
616 * operation. Before the first connection attempt, @c ec is always set to
617 * indicate success. The @c next parameter is an iterator pointing to the next
618 * endpoint to be tried. The function object should return the next iterator,
619 * but is permitted to return a different iterator so that endpoints may be
620 * skipped. The implementation guarantees that the function object will never
621 * be called with the end iterator.
622 *
623 * @param handler The handler to be called when the connect operation
624 * completes. Copies will be made of the handler as required. The function
625 * signature of the handler must be:
626 * @code void handler(
627 * // Result of operation. if the sequence is empty, set to
628 * // boost::asio::error::not_found. Otherwise, contains the
629 * // error from the last connection attempt.
630 * const boost::system::error_code& error,
631 *
632 * // On success, an iterator denoting the successfully
633 * // connected endpoint. Otherwise, the end iterator.
634 * Iterator iterator
635 * ); @endcode
636 * Regardless of whether the asynchronous operation completes immediately or
637 * not, the handler will not be invoked from within this function. Invocation
638 * of the handler will be performed in a manner equivalent to using
639 * boost::asio::io_service::post().
640 *
641 * @note This overload assumes that a default constructed object of type @c
642 * Iterator represents the end of the sequence. This is a valid assumption for
643 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
644 *
645 * @par Example
646 * The following connect condition function object can be used to output
647 * information about the individual connection attempts:
648 * @code struct my_connect_condition
649 * {
650 * template <typename Iterator>
651 * Iterator operator()(
652 * const boost::system::error_code& ec,
653 * Iterator next)
654 * {
655 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
656 * std::cout << "Trying: " << next->endpoint() << std::endl;
657 * return next;
658 * }
659 * }; @endcode
660 * It would be used with the boost::asio::connect function as follows:
661 * @code tcp::resolver r(io_service);
662 * tcp::resolver::query q("host", "service");
663 * tcp::socket s(io_service);
664 *
665 * // ...
666 *
667 * r.async_resolve(q, resolve_handler);
668 *
669 * // ...
670 *
671 * void resolve_handler(
672 * const boost::system::error_code& ec,
673 * tcp::resolver::iterator i)
674 * {
675 * if (!ec)
676 * {
677 * boost::asio::async_connect(s, i,
678 * my_connect_condition(),
679 * connect_handler);
680 * }
681 * }
682 *
683 * // ...
684 *
685 * void connect_handler(
686 * const boost::system::error_code& ec,
687 * tcp::resolver::iterator i)
688 * {
689 * if (ec)
690 * {
691 * // An error occurred.
692 * }
693 * else
694 * {
695 * std::cout << "Connected to: " << i->endpoint() << std::endl;
696 * }
697 * } @endcode
698 */
699template <typename Protocol, typename SocketService, typename Iterator,
700 typename ConnectCondition, typename ComposedConnectHandler>
701BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler,
702 void (boost::system::error_code, Iterator))
703async_connect(basic_socket<Protocol, SocketService>& s, Iterator begin,
704 ConnectCondition connect_condition,
705 BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler);
706
707/// Asynchronously establishes a socket connection by trying each endpoint in a
708/// sequence.
709/**
710 * This function attempts to connect a socket to one of a sequence of
711 * endpoints. It does this by repeated calls to the socket's @c async_connect
712 * member function, once for each endpoint in the sequence, until a connection
713 * is successfully established.
714 *
715 * @param s The socket to be connected. If the socket is already open, it will
716 * be closed.
717 *
718 * @param begin An iterator pointing to the start of a sequence of endpoints.
719 *
720 * @param end An iterator pointing to the end of a sequence of endpoints.
721 *
722 * @param connect_condition A function object that is called prior to each
723 * connection attempt. The signature of the function object must be:
724 * @code Iterator connect_condition(
725 * const boost::system::error_code& ec,
726 * Iterator next); @endcode
727 * The @c ec parameter contains the result from the most recent connect
728 * operation. Before the first connection attempt, @c ec is always set to
729 * indicate success. The @c next parameter is an iterator pointing to the next
730 * endpoint to be tried. The function object should return the next iterator,
731 * but is permitted to return a different iterator so that endpoints may be
732 * skipped. The implementation guarantees that the function object will never
733 * be called with the end iterator.
734 *
735 * @param handler The handler to be called when the connect operation
736 * completes. Copies will be made of the handler as required. The function
737 * signature of the handler must be:
738 * @code void handler(
739 * // Result of operation. if the sequence is empty, set to
740 * // boost::asio::error::not_found. Otherwise, contains the
741 * // error from the last connection attempt.
742 * const boost::system::error_code& error,
743 *
744 * // On success, an iterator denoting the successfully
745 * // connected endpoint. Otherwise, the end iterator.
746 * Iterator iterator
747 * ); @endcode
748 * Regardless of whether the asynchronous operation completes immediately or
749 * not, the handler will not be invoked from within this function. Invocation
750 * of the handler will be performed in a manner equivalent to using
751 * boost::asio::io_service::post().
752 *
753 * @par Example
754 * The following connect condition function object can be used to output
755 * information about the individual connection attempts:
756 * @code struct my_connect_condition
757 * {
758 * template <typename Iterator>
759 * Iterator operator()(
760 * const boost::system::error_code& ec,
761 * Iterator next)
762 * {
763 * if (ec) std::cout << "Error: " << ec.message() << std::endl;
764 * std::cout << "Trying: " << next->endpoint() << std::endl;
765 * return next;
766 * }
767 * }; @endcode
768 * It would be used with the boost::asio::connect function as follows:
769 * @code tcp::resolver r(io_service);
770 * tcp::resolver::query q("host", "service");
771 * tcp::socket s(io_service);
772 *
773 * // ...
774 *
775 * r.async_resolve(q, resolve_handler);
776 *
777 * // ...
778 *
779 * void resolve_handler(
780 * const boost::system::error_code& ec,
781 * tcp::resolver::iterator i)
782 * {
783 * if (!ec)
784 * {
785 * tcp::resolver::iterator end;
786 * boost::asio::async_connect(s, i, end,
787 * my_connect_condition(),
788 * connect_handler);
789 * }
790 * }
791 *
792 * // ...
793 *
794 * void connect_handler(
795 * const boost::system::error_code& ec,
796 * tcp::resolver::iterator i)
797 * {
798 * if (ec)
799 * {
800 * // An error occurred.
801 * }
802 * else
803 * {
804 * std::cout << "Connected to: " << i->endpoint() << std::endl;
805 * }
806 * } @endcode
807 */
808template <typename Protocol, typename SocketService, typename Iterator,
809 typename ConnectCondition, typename ComposedConnectHandler>
810BOOST_ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler,
811 void (boost::system::error_code, Iterator))
812async_connect(basic_socket<Protocol, SocketService>& s,
813 Iterator begin, Iterator end, ConnectCondition connect_condition,
814 BOOST_ASIO_MOVE_ARG(ComposedConnectHandler) handler);
815
816/*@}*/
817
818} // namespace asio
819} // namespace boost
820
821#include <boost/asio/detail/pop_options.hpp>
822
823#include <boost/asio/impl/connect.hpp>
824
825#endif
826