boost/asio/connect.hpp

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