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