1 // 2 // connect.hpp 3 // ~~~~~~~~~~~ 4 // 5 // Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com) 6 // 7 // Distributed under the Boost Software License, Version 1.0. (See accompanying 8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 9 // 10 11 #ifndef BOOST_ASIO_CONNECT_HPP 12 #define BOOST_ASIO_CONNECT_HPP 13 14 #if defined(_MSC_VER) && (_MSC_VER >= 1200) 15 # pragma once 16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200) 17 18 #include <boost/asio/detail/config.hpp> 19 #include <boost/asio/async_result.hpp> 20 #include <boost/asio/basic_socket.hpp> 21 #include <boost/asio/detail/type_traits.hpp> 22 #include <boost/asio/error.hpp> 23 24 #include <boost/asio/detail/push_options.hpp> 25 26 namespace boost { 27 namespace asio { 28 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 59 /** 60 * @defgroup connect boost::asio::connect 61 * 62 * @brief The @c connect function is a composed operation that establishes a 63 * socket connection by trying each endpoint in a sequence. 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 * 77 * @param endpoints A sequence of endpoints. 78 * 79 * @returns The successfully connected endpoint. 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 * 85 * @par Example 86 * @code tcp::resolver r(my_context); 87 * tcp::resolver::query q("host", "service"); 88 * tcp::socket s(my_context); 89 * boost::asio::connect(s, r.resolve(q)); @endcode 90 */ 91 template <typename Protocol, typename Executor, typename EndpointSequence> 92 typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s, 93 const EndpointSequence& endpoints, 94 typename constraint<is_endpoint_sequence< 95 EndpointSequence>::value>::type = 0); 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 * 107 * @param endpoints A sequence of endpoints. 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 * 113 * @returns On success, the successfully connected endpoint. Otherwise, a 114 * default-constructed endpoint. 115 * 116 * @par Example 117 * @code tcp::resolver r(my_context); 118 * tcp::resolver::query q("host", "service"); 119 * tcp::socket s(my_context); 120 * boost::system::error_code ec; 121 * boost::asio::connect(s, r.resolve(q), ec); 122 * if (ec) 123 * { 124 * // An error occurred. 125 * } @endcode 126 */ 127 template <typename Protocol, typename Executor, typename EndpointSequence> 128 typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s, 129 const EndpointSequence& endpoints, boost::system::error_code& ec, 130 typename constraint<is_endpoint_sequence< 131 EndpointSequence>::value>::type = 0); 132 133 #if !defined(BOOST_ASIO_NO_DEPRECATED) 134 /// (Deprecated: Use range overload.) Establishes a socket connection by trying 135 /// each endpoint in a sequence. 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 * 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 */ 158 template <typename Protocol, typename Executor, typename Iterator> 159 Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin, 160 typename constraint<!is_endpoint_sequence<Iterator>::value>::type = 0); 161 162 /// (Deprecated: Use range overload.) Establishes a socket connection by trying 163 /// each endpoint in a sequence. 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. 178 * 179 * @returns On success, an iterator denoting the successfully connected 180 * endpoint. Otherwise, the end iterator. 181 * 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 */ 186 template <typename Protocol, typename Executor, typename Iterator> 187 Iterator connect(basic_socket<Protocol, Executor>& s, 188 Iterator begin, boost::system::error_code& ec, 189 typename constraint<!is_endpoint_sequence<Iterator>::value>::type = 0); 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 * 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 213 * @code tcp::resolver r(my_context); 214 * tcp::resolver::query q("host", "service"); 215 * tcp::resolver::results_type e = r.resolve(q); 216 * tcp::socket s(my_context); 217 * boost::asio::connect(s, e.begin(), e.end()); @endcode 218 */ 219 template <typename Protocol, typename Executor, typename Iterator> 220 Iterator connect(basic_socket<Protocol, Executor>& s, 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 245 * @code tcp::resolver r(my_context); 246 * tcp::resolver::query q("host", "service"); 247 * tcp::resolver::results_type e = r.resolve(q); 248 * tcp::socket s(my_context); 249 * boost::system::error_code ec; 250 * boost::asio::connect(s, e.begin(), e.end(), ec); 251 * if (ec) 252 * { 253 * // An error occurred. 254 * } @endcode 255 */ 256 template <typename Protocol, typename Executor, typename Iterator> 257 Iterator connect(basic_socket<Protocol, Executor>& s, 258 Iterator begin, Iterator end, boost::system::error_code& ec); 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 * 270 * @param endpoints A sequence of endpoints. 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: 274 * @code bool connect_condition( 275 * const boost::system::error_code& ec, 276 * const typename Protocol::endpoint& next); @endcode 277 * The @c ec parameter contains the result from the most recent connect 278 * operation. Before the first connection attempt, @c ec is always set to 279 * indicate success. The @c next parameter is the next endpoint to be tried. 280 * The function object should return true if the next endpoint should be tried, 281 * and false if it should be skipped. 282 * 283 * @returns The successfully connected endpoint. 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 * 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 * { 294 * bool operator()( 295 * const boost::system::error_code& ec, 296 * const::tcp::endpoint& next) 297 * { 298 * if (ec) std::cout << "Error: " << ec.message() << std::endl; 299 * std::cout << "Trying: " << next << std::endl; 300 * return true; 301 * } 302 * }; @endcode 303 * It would be used with the boost::asio::connect function as follows: 304 * @code tcp::resolver r(my_context); 305 * tcp::resolver::query q("host", "service"); 306 * tcp::socket s(my_context); 307 * tcp::endpoint e = boost::asio::connect(s, 308 * r.resolve(q), my_connect_condition()); 309 * std::cout << "Connected to: " << e << std::endl; @endcode 310 */ 311 template <typename Protocol, typename Executor, 312 typename EndpointSequence, typename ConnectCondition> 313 typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s, 314 const EndpointSequence& endpoints, ConnectCondition connect_condition, 315 typename constraint<is_endpoint_sequence< 316 EndpointSequence>::value>::type = 0); 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 * 328 * @param endpoints A sequence of endpoints. 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: 332 * @code bool connect_condition( 333 * const boost::system::error_code& ec, 334 * const typename Protocol::endpoint& next); @endcode 335 * The @c ec parameter contains the result from the most recent connect 336 * operation. Before the first connection attempt, @c ec is always set to 337 * indicate success. The @c next parameter is the next endpoint to be tried. 338 * The function object should return true if the next endpoint should be tried, 339 * and false if it should be skipped. 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 * 345 * @returns On success, the successfully connected endpoint. Otherwise, a 346 * default-constructed endpoint. 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 * { 353 * bool operator()( 354 * const boost::system::error_code& ec, 355 * const::tcp::endpoint& next) 356 * { 357 * if (ec) std::cout << "Error: " << ec.message() << std::endl; 358 * std::cout << "Trying: " << next << std::endl; 359 * return true; 360 * } 361 * }; @endcode 362 * It would be used with the boost::asio::connect function as follows: 363 * @code tcp::resolver r(my_context); 364 * tcp::resolver::query q("host", "service"); 365 * tcp::socket s(my_context); 366 * boost::system::error_code ec; 367 * tcp::endpoint e = boost::asio::connect(s, 368 * r.resolve(q), my_connect_condition(), ec); 369 * if (ec) 370 * { 371 * // An error occurred. 372 * } 373 * else 374 * { 375 * std::cout << "Connected to: " << e << std::endl; 376 * } @endcode 377 */ 378 template <typename Protocol, typename Executor, 379 typename EndpointSequence, typename ConnectCondition> 380 typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s, 381 const EndpointSequence& endpoints, ConnectCondition connect_condition, 382 boost::system::error_code& ec, 383 typename constraint<is_endpoint_sequence< 384 EndpointSequence>::value>::type = 0); 385 386 #if !defined(BOOST_ASIO_NO_DEPRECATED) 387 /// (Deprecated: Use range overload.) Establishes a socket connection by trying 388 /// each endpoint in a sequence. 389 /** 390 * This function attempts to connect a socket to one of a sequence of 391 * endpoints. It does this by repeated calls to the socket's @c connect member 392 * function, once for each endpoint in the sequence, until a connection is 393 * successfully established. 394 * 395 * @param s The socket to be connected. If the socket is already open, it will 396 * be closed. 397 * 398 * @param begin An iterator pointing to the start of a sequence of endpoints. 399 * 400 * @param connect_condition A function object that is called prior to each 401 * connection attempt. The signature of the function object must be: 402 * @code bool connect_condition( 403 * const boost::system::error_code& ec, 404 * const typename Protocol::endpoint& next); @endcode 405 * The @c ec parameter contains the result from the most recent connect 406 * operation. Before the first connection attempt, @c ec is always set to 407 * indicate success. The @c next parameter is the next endpoint to be tried. 408 * The function object should return true if the next endpoint should be tried, 409 * and false if it should be skipped. 410 * 411 * @returns On success, an iterator denoting the successfully connected 412 * endpoint. Otherwise, the end iterator. 413 * 414 * @throws boost::system::system_error Thrown on failure. If the sequence is 415 * empty, the associated @c error_code is boost::asio::error::not_found. 416 * Otherwise, contains the error from the last connection attempt. 417 * 418 * @note This overload assumes that a default constructed object of type @c 419 * Iterator represents the end of the sequence. This is a valid assumption for 420 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. 421 */ 422 template <typename Protocol, typename Executor, 423 typename Iterator, typename ConnectCondition> 424 Iterator connect(basic_socket<Protocol, Executor>& s, 425 Iterator begin, ConnectCondition connect_condition, 426 typename constraint<!is_endpoint_sequence<Iterator>::value>::type = 0); 427 428 /// (Deprecated: Use range overload.) Establishes a socket connection by trying 429 /// each endpoint in a sequence. 430 /** 431 * This function attempts to connect a socket to one of a sequence of 432 * endpoints. It does this by repeated calls to the socket's @c connect member 433 * function, once for each endpoint in the sequence, until a connection is 434 * successfully established. 435 * 436 * @param s The socket to be connected. If the socket is already open, it will 437 * be closed. 438 * 439 * @param begin An iterator pointing to the start of a sequence of endpoints. 440 * 441 * @param connect_condition A function object that is called prior to each 442 * connection attempt. The signature of the function object must be: 443 * @code bool connect_condition( 444 * const boost::system::error_code& ec, 445 * const typename Protocol::endpoint& next); @endcode 446 * The @c ec parameter contains the result from the most recent connect 447 * operation. Before the first connection attempt, @c ec is always set to 448 * indicate success. The @c next parameter is the next endpoint to be tried. 449 * The function object should return true if the next endpoint should be tried, 450 * and false if it should be skipped. 451 * 452 * @param ec Set to indicate what error occurred, if any. If the sequence is 453 * empty, set to boost::asio::error::not_found. Otherwise, contains the error 454 * from the last connection attempt. 455 * 456 * @returns On success, an iterator denoting the successfully connected 457 * endpoint. Otherwise, the end iterator. 458 * 459 * @note This overload assumes that a default constructed object of type @c 460 * Iterator represents the end of the sequence. This is a valid assumption for 461 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. 462 */ 463 template <typename Protocol, typename Executor, 464 typename Iterator, typename ConnectCondition> 465 Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin, 466 ConnectCondition connect_condition, boost::system::error_code& ec, 467 typename constraint<!is_endpoint_sequence<Iterator>::value>::type = 0); 468 #endif // !defined(BOOST_ASIO_NO_DEPRECATED) 469 470 /// Establishes a socket connection by trying each endpoint in a sequence. 471 /** 472 * This function attempts to connect a socket to one of a sequence of 473 * endpoints. It does this by repeated calls to the socket's @c connect member 474 * function, once for each endpoint in the sequence, until a connection is 475 * successfully established. 476 * 477 * @param s The socket to be connected. If the socket is already open, it will 478 * be closed. 479 * 480 * @param begin An iterator pointing to the start of a sequence of endpoints. 481 * 482 * @param end An iterator pointing to the end of a sequence of endpoints. 483 * 484 * @param connect_condition A function object that is called prior to each 485 * connection attempt. The signature of the function object must be: 486 * @code bool connect_condition( 487 * const boost::system::error_code& ec, 488 * const typename Protocol::endpoint& next); @endcode 489 * The @c ec parameter contains the result from the most recent connect 490 * operation. Before the first connection attempt, @c ec is always set to 491 * indicate success. The @c next parameter is the next endpoint to be tried. 492 * The function object should return true if the next endpoint should be tried, 493 * and false if it should be skipped. 494 * 495 * @returns An iterator denoting the successfully connected endpoint. 496 * 497 * @throws boost::system::system_error Thrown on failure. If the sequence is 498 * empty, the associated @c error_code is boost::asio::error::not_found. 499 * Otherwise, contains the error from the last connection attempt. 500 * 501 * @par Example 502 * The following connect condition function object can be used to output 503 * information about the individual connection attempts: 504 * @code struct my_connect_condition 505 * { 506 * bool operator()( 507 * const boost::system::error_code& ec, 508 * const::tcp::endpoint& next) 509 * { 510 * if (ec) std::cout << "Error: " << ec.message() << std::endl; 511 * std::cout << "Trying: " << next << std::endl; 512 * return true; 513 * } 514 * }; @endcode 515 * It would be used with the boost::asio::connect function as follows: 516 * @code tcp::resolver r(my_context); 517 * tcp::resolver::query q("host", "service"); 518 * tcp::resolver::results_type e = r.resolve(q); 519 * tcp::socket s(my_context); 520 * tcp::resolver::results_type::iterator i = boost::asio::connect( 521 * s, e.begin(), e.end(), my_connect_condition()); 522 * std::cout << "Connected to: " << i->endpoint() << std::endl; @endcode 523 */ 524 template <typename Protocol, typename Executor, 525 typename Iterator, typename ConnectCondition> 526 Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin, 527 Iterator end, ConnectCondition connect_condition); 528 529 /// Establishes a socket connection by trying each endpoint in a sequence. 530 /** 531 * This function attempts to connect a socket to one of a sequence of 532 * endpoints. It does this by repeated calls to the socket's @c connect member 533 * function, once for each endpoint in the sequence, until a connection is 534 * successfully established. 535 * 536 * @param s The socket to be connected. If the socket is already open, it will 537 * be closed. 538 * 539 * @param begin An iterator pointing to the start of a sequence of endpoints. 540 * 541 * @param end An iterator pointing to the end of a sequence of endpoints. 542 * 543 * @param connect_condition A function object that is called prior to each 544 * connection attempt. The signature of the function object must be: 545 * @code bool connect_condition( 546 * const boost::system::error_code& ec, 547 * const typename Protocol::endpoint& next); @endcode 548 * The @c ec parameter contains the result from the most recent connect 549 * operation. Before the first connection attempt, @c ec is always set to 550 * indicate success. The @c next parameter is the next endpoint to be tried. 551 * The function object should return true if the next endpoint should be tried, 552 * and false if it should be skipped. 553 * 554 * @param ec Set to indicate what error occurred, if any. If the sequence is 555 * empty, set to boost::asio::error::not_found. Otherwise, contains the error 556 * from the last connection attempt. 557 * 558 * @returns On success, an iterator denoting the successfully connected 559 * endpoint. Otherwise, the end iterator. 560 * 561 * @par Example 562 * The following connect condition function object can be used to output 563 * information about the individual connection attempts: 564 * @code struct my_connect_condition 565 * { 566 * bool operator()( 567 * const boost::system::error_code& ec, 568 * const::tcp::endpoint& next) 569 * { 570 * if (ec) std::cout << "Error: " << ec.message() << std::endl; 571 * std::cout << "Trying: " << next << std::endl; 572 * return true; 573 * } 574 * }; @endcode 575 * It would be used with the boost::asio::connect function as follows: 576 * @code tcp::resolver r(my_context); 577 * tcp::resolver::query q("host", "service"); 578 * tcp::resolver::results_type e = r.resolve(q); 579 * tcp::socket s(my_context); 580 * boost::system::error_code ec; 581 * tcp::resolver::results_type::iterator i = boost::asio::connect( 582 * s, e.begin(), e.end(), my_connect_condition()); 583 * if (ec) 584 * { 585 * // An error occurred. 586 * } 587 * else 588 * { 589 * std::cout << "Connected to: " << i->endpoint() << std::endl; 590 * } @endcode 591 */ 592 template <typename Protocol, typename Executor, 593 typename Iterator, typename ConnectCondition> 594 Iterator connect(basic_socket<Protocol, Executor>& s, 595 Iterator begin, Iterator end, ConnectCondition connect_condition, 596 boost::system::error_code& ec); 597 598 /*@}*/ 599 600 /** 601 * @defgroup async_connect boost::asio::async_connect 602 * 603 * @brief The @c async_connect function is a composed asynchronous operation 604 * that establishes a socket connection by trying each endpoint in a sequence. 605 */ 606 /*@{*/ 607 608 /// Asynchronously establishes a socket connection by trying each endpoint in a 609 /// sequence. 610 /** 611 * This function attempts to connect a socket to one of a sequence of 612 * endpoints. It does this by repeated calls to the socket's @c async_connect 613 * member function, once for each endpoint in the sequence, until a connection 614 * is successfully established. 615 * 616 * @param s The socket to be connected. If the socket is already open, it will 617 * be closed. 618 * 619 * @param endpoints A sequence of endpoints. 620 * 621 * @param handler The handler to be called when the connect operation 622 * completes. Copies will be made of the handler as required. The function 623 * signature of the handler must be: 624 * @code void handler( 625 * // Result of operation. if the sequence is empty, set to 626 * // boost::asio::error::not_found. Otherwise, contains the 627 * // error from the last connection attempt. 628 * const boost::system::error_code& error, 629 * 630 * // On success, the successfully connected endpoint. 631 * // Otherwise, a default-constructed endpoint. 632 * const typename Protocol::endpoint& endpoint 633 * ); @endcode 634 * Regardless of whether the asynchronous operation completes immediately or 635 * not, the handler will not be invoked from within this function. On 636 * immediate completion, invocation of the handler will be performed in a 637 * manner equivalent to using boost::asio::post(). 638 * 639 * @par Example 640 * @code tcp::resolver r(my_context); 641 * tcp::resolver::query q("host", "service"); 642 * tcp::socket s(my_context); 643 * 644 * // ... 645 * 646 * r.async_resolve(q, resolve_handler); 647 * 648 * // ... 649 * 650 * void resolve_handler( 651 * const boost::system::error_code& ec, 652 * tcp::resolver::results_type results) 653 * { 654 * if (!ec) 655 * { 656 * boost::asio::async_connect(s, results, connect_handler); 657 * } 658 * } 659 * 660 * // ... 661 * 662 * void connect_handler( 663 * const boost::system::error_code& ec, 664 * const tcp::endpoint& endpoint) 665 * { 666 * // ... 667 * } @endcode 668 */ 669 template <typename Protocol, typename Executor, typename EndpointSequence, 670 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 671 typename Protocol::endpoint)) RangeConnectHandler 672 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)> 673 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectHandler, 674 void (boost::system::error_code, typename Protocol::endpoint)) 675 async_connect(basic_socket<Protocol, Executor>& s, 676 const EndpointSequence& endpoints, 677 BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler 678 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor), 679 typename constraint<is_endpoint_sequence< 680 EndpointSequence>::value>::type = 0); 681 682 #if !defined(BOOST_ASIO_NO_DEPRECATED) 683 /// (Deprecated: Use range overload.) Asynchronously establishes a socket 684 /// connection by trying each endpoint in a sequence. 685 /** 686 * This function attempts to connect a socket to one of a sequence of 687 * endpoints. It does this by repeated calls to the socket's @c async_connect 688 * member function, once for each endpoint in the sequence, until a connection 689 * is successfully established. 690 * 691 * @param s The socket to be connected. If the socket is already open, it will 692 * be closed. 693 * 694 * @param begin An iterator pointing to the start of a sequence of endpoints. 695 * 696 * @param handler The handler to be called when the connect operation 697 * completes. Copies will be made of the handler as required. The function 698 * signature of the handler must be: 699 * @code void handler( 700 * // Result of operation. if the sequence is empty, set to 701 * // boost::asio::error::not_found. Otherwise, contains the 702 * // error from the last connection attempt. 703 * const boost::system::error_code& error, 704 * 705 * // On success, an iterator denoting the successfully 706 * // connected endpoint. Otherwise, the end iterator. 707 * Iterator iterator 708 * ); @endcode 709 * Regardless of whether the asynchronous operation completes immediately or 710 * not, the handler will not be invoked from within this function. On 711 * immediate completion, invocation of the handler will be performed in a 712 * manner equivalent to using boost::asio::post(). 713 * 714 * @note This overload assumes that a default constructed object of type @c 715 * Iterator represents the end of the sequence. This is a valid assumption for 716 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. 717 */ 718 template <typename Protocol, typename Executor, typename Iterator, 719 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 720 Iterator)) IteratorConnectHandler 721 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)> 722 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler, 723 void (boost::system::error_code, Iterator)) 724 async_connect(basic_socket<Protocol, Executor>& s, Iterator begin, 725 BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler 726 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor), 727 typename constraint<!is_endpoint_sequence<Iterator>::value>::type = 0); 728 #endif // !defined(BOOST_ASIO_NO_DEPRECATED) 729 730 /// Asynchronously establishes a socket connection by trying each endpoint in a 731 /// sequence. 732 /** 733 * This function attempts to connect a socket to one of a sequence of 734 * endpoints. It does this by repeated calls to the socket's @c async_connect 735 * member function, once for each endpoint in the sequence, until a connection 736 * is successfully established. 737 * 738 * @param s The socket to be connected. If the socket is already open, it will 739 * be closed. 740 * 741 * @param begin An iterator pointing to the start of a sequence of endpoints. 742 * 743 * @param end An iterator pointing to the end of a sequence of endpoints. 744 * 745 * @param handler The handler to be called when the connect operation 746 * completes. Copies will be made of the handler as required. The function 747 * signature of the handler must be: 748 * @code void handler( 749 * // Result of operation. if the sequence is empty, set to 750 * // boost::asio::error::not_found. Otherwise, contains the 751 * // error from the last connection attempt. 752 * const boost::system::error_code& error, 753 * 754 * // On success, an iterator denoting the successfully 755 * // connected endpoint. Otherwise, the end iterator. 756 * Iterator iterator 757 * ); @endcode 758 * Regardless of whether the asynchronous operation completes immediately or 759 * not, the handler will not be invoked from within this function. On 760 * immediate completion, invocation of the handler will be performed in a 761 * manner equivalent to using boost::asio::post(). 762 * 763 * @par Example 764 * @code std::vector<tcp::endpoint> endpoints = ...; 765 * tcp::socket s(my_context); 766 * boost::asio::async_connect(s, 767 * endpoints.begin(), endpoints.end(), 768 * connect_handler); 769 * 770 * // ... 771 * 772 * void connect_handler( 773 * const boost::system::error_code& ec, 774 * std::vector<tcp::endpoint>::iterator i) 775 * { 776 * // ... 777 * } @endcode 778 */ 779 template <typename Protocol, typename Executor, typename Iterator, 780 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 781 Iterator)) IteratorConnectHandler 782 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)> 783 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler, 784 void (boost::system::error_code, Iterator)) 785 async_connect(basic_socket<Protocol, Executor>& s, Iterator begin, Iterator end, 786 BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler 787 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor)); 788 789 /// Asynchronously establishes a socket connection by trying each endpoint in a 790 /// sequence. 791 /** 792 * This function attempts to connect a socket to one of a sequence of 793 * endpoints. It does this by repeated calls to the socket's @c async_connect 794 * member function, once for each endpoint in the sequence, until a connection 795 * is successfully established. 796 * 797 * @param s The socket to be connected. If the socket is already open, it will 798 * be closed. 799 * 800 * @param endpoints A sequence of endpoints. 801 * 802 * @param connect_condition A function object that is called prior to each 803 * connection attempt. The signature of the function object must be: 804 * @code bool connect_condition( 805 * const boost::system::error_code& ec, 806 * const typename Protocol::endpoint& next); @endcode 807 * The @c ec parameter contains the result from the most recent connect 808 * operation. Before the first connection attempt, @c ec is always set to 809 * indicate success. The @c next parameter is the next endpoint to be tried. 810 * The function object should return true if the next endpoint should be tried, 811 * and false if it should be skipped. 812 * 813 * @param handler The handler to be called when the connect operation 814 * completes. Copies will be made of the handler as required. The function 815 * signature of the handler must be: 816 * @code void handler( 817 * // Result of operation. if the sequence is empty, set to 818 * // boost::asio::error::not_found. Otherwise, contains the 819 * // error from the last connection attempt. 820 * const boost::system::error_code& error, 821 * 822 * // On success, an iterator denoting the successfully 823 * // connected endpoint. Otherwise, the end iterator. 824 * Iterator iterator 825 * ); @endcode 826 * Regardless of whether the asynchronous operation completes immediately or 827 * not, the handler will not be invoked from within this function. On 828 * immediate completion, invocation of the handler will be performed in a 829 * manner equivalent to using boost::asio::post(). 830 * 831 * @par Example 832 * The following connect condition function object can be used to output 833 * information about the individual connection attempts: 834 * @code struct my_connect_condition 835 * { 836 * bool operator()( 837 * const boost::system::error_code& ec, 838 * const::tcp::endpoint& next) 839 * { 840 * if (ec) std::cout << "Error: " << ec.message() << std::endl; 841 * std::cout << "Trying: " << next << std::endl; 842 * return true; 843 * } 844 * }; @endcode 845 * It would be used with the boost::asio::connect function as follows: 846 * @code tcp::resolver r(my_context); 847 * tcp::resolver::query q("host", "service"); 848 * tcp::socket s(my_context); 849 * 850 * // ... 851 * 852 * r.async_resolve(q, resolve_handler); 853 * 854 * // ... 855 * 856 * void resolve_handler( 857 * const boost::system::error_code& ec, 858 * tcp::resolver::results_type results) 859 * { 860 * if (!ec) 861 * { 862 * boost::asio::async_connect(s, results, 863 * my_connect_condition(), 864 * connect_handler); 865 * } 866 * } 867 * 868 * // ... 869 * 870 * void connect_handler( 871 * const boost::system::error_code& ec, 872 * const tcp::endpoint& endpoint) 873 * { 874 * if (ec) 875 * { 876 * // An error occurred. 877 * } 878 * else 879 * { 880 * std::cout << "Connected to: " << endpoint << std::endl; 881 * } 882 * } @endcode 883 */ 884 template <typename Protocol, typename Executor, 885 typename EndpointSequence, typename ConnectCondition, 886 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 887 typename Protocol::endpoint)) RangeConnectHandler 888 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)> 889 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectHandler, 890 void (boost::system::error_code, typename Protocol::endpoint)) 891 async_connect(basic_socket<Protocol, Executor>& s, 892 const EndpointSequence& endpoints, ConnectCondition connect_condition, 893 BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler 894 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor), 895 typename constraint<is_endpoint_sequence< 896 EndpointSequence>::value>::type = 0); 897 898 #if !defined(BOOST_ASIO_NO_DEPRECATED) 899 /// (Deprecated: Use range overload.) Asynchronously establishes a socket 900 /// connection by trying each endpoint in a sequence. 901 /** 902 * This function attempts to connect a socket to one of a sequence of 903 * endpoints. It does this by repeated calls to the socket's @c async_connect 904 * member function, once for each endpoint in the sequence, until a connection 905 * is successfully established. 906 * 907 * @param s The socket to be connected. If the socket is already open, it will 908 * be closed. 909 * 910 * @param begin An iterator pointing to the start of a sequence of endpoints. 911 * 912 * @param connect_condition A function object that is called prior to each 913 * connection attempt. The signature of the function object must be: 914 * @code bool connect_condition( 915 * const boost::system::error_code& ec, 916 * const typename Protocol::endpoint& next); @endcode 917 * The @c ec parameter contains the result from the most recent connect 918 * operation. Before the first connection attempt, @c ec is always set to 919 * indicate success. The @c next parameter is the next endpoint to be tried. 920 * The function object should return true if the next endpoint should be tried, 921 * and false if it should be skipped. 922 * 923 * @param handler The handler to be called when the connect operation 924 * completes. Copies will be made of the handler as required. The function 925 * signature of the handler must be: 926 * @code void handler( 927 * // Result of operation. if the sequence is empty, set to 928 * // boost::asio::error::not_found. Otherwise, contains the 929 * // error from the last connection attempt. 930 * const boost::system::error_code& error, 931 * 932 * // On success, an iterator denoting the successfully 933 * // connected endpoint. Otherwise, the end iterator. 934 * Iterator iterator 935 * ); @endcode 936 * Regardless of whether the asynchronous operation completes immediately or 937 * not, the handler will not be invoked from within this function. On 938 * immediate completion, invocation of the handler will be performed in a 939 * manner equivalent to using boost::asio::post(). 940 * 941 * @note This overload assumes that a default constructed object of type @c 942 * Iterator represents the end of the sequence. This is a valid assumption for 943 * iterator types such as @c boost::asio::ip::tcp::resolver::iterator. 944 */ 945 template <typename Protocol, typename Executor, 946 typename Iterator, typename ConnectCondition, 947 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 948 Iterator)) IteratorConnectHandler 949 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)> 950 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler, 951 void (boost::system::error_code, Iterator)) 952 async_connect(basic_socket<Protocol, Executor>& s, Iterator begin, 953 ConnectCondition connect_condition, 954 BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler 955 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor), 956 typename constraint<!is_endpoint_sequence<Iterator>::value>::type = 0); 957 #endif // !defined(BOOST_ASIO_NO_DEPRECATED) 958 959 /// Asynchronously establishes a socket connection by trying each endpoint in a 960 /// sequence. 961 /** 962 * This function attempts to connect a socket to one of a sequence of 963 * endpoints. It does this by repeated calls to the socket's @c async_connect 964 * member function, once for each endpoint in the sequence, until a connection 965 * is successfully established. 966 * 967 * @param s The socket to be connected. If the socket is already open, it will 968 * be closed. 969 * 970 * @param begin An iterator pointing to the start of a sequence of endpoints. 971 * 972 * @param end An iterator pointing to the end of a sequence of endpoints. 973 * 974 * @param connect_condition A function object that is called prior to each 975 * connection attempt. The signature of the function object must be: 976 * @code bool connect_condition( 977 * const boost::system::error_code& ec, 978 * const typename Protocol::endpoint& next); @endcode 979 * The @c ec parameter contains the result from the most recent connect 980 * operation. Before the first connection attempt, @c ec is always set to 981 * indicate success. The @c next parameter is the next endpoint to be tried. 982 * The function object should return true if the next endpoint should be tried, 983 * and false if it should be skipped. 984 * 985 * @param handler The handler to be called when the connect operation 986 * completes. Copies will be made of the handler as required. The function 987 * signature of the handler must be: 988 * @code void handler( 989 * // Result of operation. if the sequence is empty, set to 990 * // boost::asio::error::not_found. Otherwise, contains the 991 * // error from the last connection attempt. 992 * const boost::system::error_code& error, 993 * 994 * // On success, an iterator denoting the successfully 995 * // connected endpoint. Otherwise, the end iterator. 996 * Iterator iterator 997 * ); @endcode 998 * Regardless of whether the asynchronous operation completes immediately or 999 * not, the handler will not be invoked from within this function. On 1000 * immediate completion, invocation of the handler will be performed in a 1001 * manner equivalent to using boost::asio::post(). 1002 * 1003 * @par Example 1004 * The following connect condition function object can be used to output 1005 * information about the individual connection attempts: 1006 * @code struct my_connect_condition 1007 * { 1008 * bool operator()( 1009 * const boost::system::error_code& ec, 1010 * const::tcp::endpoint& next) 1011 * { 1012 * if (ec) std::cout << "Error: " << ec.message() << std::endl; 1013 * std::cout << "Trying: " << next << std::endl; 1014 * return true; 1015 * } 1016 * }; @endcode 1017 * It would be used with the boost::asio::connect function as follows: 1018 * @code tcp::resolver r(my_context); 1019 * tcp::resolver::query q("host", "service"); 1020 * tcp::socket s(my_context); 1021 * 1022 * // ... 1023 * 1024 * r.async_resolve(q, resolve_handler); 1025 * 1026 * // ... 1027 * 1028 * void resolve_handler( 1029 * const boost::system::error_code& ec, 1030 * tcp::resolver::iterator i) 1031 * { 1032 * if (!ec) 1033 * { 1034 * tcp::resolver::iterator end; 1035 * boost::asio::async_connect(s, i, end, 1036 * my_connect_condition(), 1037 * connect_handler); 1038 * } 1039 * } 1040 * 1041 * // ... 1042 * 1043 * void connect_handler( 1044 * const boost::system::error_code& ec, 1045 * tcp::resolver::iterator i) 1046 * { 1047 * if (ec) 1048 * { 1049 * // An error occurred. 1050 * } 1051 * else 1052 * { 1053 * std::cout << "Connected to: " << i->endpoint() << std::endl; 1054 * } 1055 * } @endcode 1056 */ 1057 template <typename Protocol, typename Executor, 1058 typename Iterator, typename ConnectCondition, 1059 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, 1060 Iterator)) IteratorConnectHandler 1061 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)> 1062 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler, 1063 void (boost::system::error_code, Iterator)) 1064 async_connect(basic_socket<Protocol, Executor>& s, Iterator begin, 1065 Iterator end, ConnectCondition connect_condition, 1066 BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler 1067 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor)); 1068 1069 /*@}*/ 1070 1071 } // namespace asio 1072 } // namespace boost 1073 1074 #include <boost/asio/detail/pop_options.hpp> 1075 1076 #include <boost/asio/impl/connect.hpp> 1077 1078 #endif 1079