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