boost/asio/connect.hpp

   1 //
   2 // connect.hpp
   3 // ~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2019 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 enable_if<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 enable_if<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 enable_if<!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 enable_if<!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 enable_if<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 enable_if<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 enable_if<!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 enable_if<!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 enable_if<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 enable_if<!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 enable_if<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 enable_if<!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