9
3

connect.hpp 42 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078
  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. #ifndef BOOST_ASIO_CONNECT_HPP
  11. #define BOOST_ASIO_CONNECT_HPP
  12. #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  13. # pragma once
  14. #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  15. #include <boost/asio/detail/config.hpp>
  16. #include <boost/asio/async_result.hpp>
  17. #include <boost/asio/basic_socket.hpp>
  18. #include <boost/asio/detail/type_traits.hpp>
  19. #include <boost/asio/error.hpp>
  20. #include <boost/asio/detail/push_options.hpp>
  21. namespace boost {
  22. namespace asio {
  23. namespace detail
  24. {
  25. char (&has_iterator_helper(...))[2];
  26. template <typename T>
  27. char has_iterator_helper(T*, typename T::iterator* = 0);
  28. template <typename T>
  29. struct has_iterator_typedef
  30. {
  31. enum { value = (sizeof((has_iterator_helper)((T*)(0))) == 1) };
  32. };
  33. } // namespace detail
  34. /// Type trait used to determine whether a type is an endpoint sequence that can
  35. /// be used with with @c connect and @c async_connect.
  36. template <typename T>
  37. struct is_endpoint_sequence
  38. {
  39. #if defined(GENERATING_DOCUMENTATION)
  40. /// The value member is true if the type may be used as an endpoint sequence.
  41. static const bool value;
  42. #else
  43. enum
  44. {
  45. value = detail::has_iterator_typedef<T>::value
  46. };
  47. #endif
  48. };
  49. /**
  50. * @defgroup connect boost::asio::connect
  51. *
  52. * @brief The @c connect function is a composed operation that establishes a
  53. * socket connection by trying each endpoint in a sequence.
  54. */
  55. /*@{*/
  56. /// Establishes a socket connection by trying each endpoint in a sequence.
  57. /**
  58. * This function attempts to connect a socket to one of a sequence of
  59. * endpoints. It does this by repeated calls to the socket's @c connect member
  60. * function, once for each endpoint in the sequence, until a connection is
  61. * successfully established.
  62. *
  63. * @param s The socket to be connected. If the socket is already open, it will
  64. * be closed.
  65. *
  66. * @param endpoints A sequence of endpoints.
  67. *
  68. * @returns The successfully connected endpoint.
  69. *
  70. * @throws boost::system::system_error Thrown on failure. If the sequence is
  71. * empty, the associated @c error_code is boost::asio::error::not_found.
  72. * Otherwise, contains the error from the last connection attempt.
  73. *
  74. * @par Example
  75. * @code tcp::resolver r(my_context);
  76. * tcp::resolver::query q("host", "service");
  77. * tcp::socket s(my_context);
  78. * boost::asio::connect(s, r.resolve(q)); @endcode
  79. */
  80. template <typename Protocol, typename Executor, typename EndpointSequence>
  81. typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
  82. const EndpointSequence& endpoints,
  83. typename enable_if<is_endpoint_sequence<
  84. EndpointSequence>::value>::type* = 0);
  85. /// Establishes a socket connection by trying each endpoint in a sequence.
  86. /**
  87. * This function attempts to connect a socket to one of a sequence of
  88. * endpoints. It does this by repeated calls to the socket's @c connect member
  89. * function, once for each endpoint in the sequence, until a connection is
  90. * successfully established.
  91. *
  92. * @param s The socket to be connected. If the socket is already open, it will
  93. * be closed.
  94. *
  95. * @param endpoints A sequence of endpoints.
  96. *
  97. * @param ec Set to indicate what error occurred, if any. If the sequence is
  98. * empty, set to boost::asio::error::not_found. Otherwise, contains the error
  99. * from the last connection attempt.
  100. *
  101. * @returns On success, the successfully connected endpoint. Otherwise, a
  102. * default-constructed endpoint.
  103. *
  104. * @par Example
  105. * @code tcp::resolver r(my_context);
  106. * tcp::resolver::query q("host", "service");
  107. * tcp::socket s(my_context);
  108. * boost::system::error_code ec;
  109. * boost::asio::connect(s, r.resolve(q), ec);
  110. * if (ec)
  111. * {
  112. * // An error occurred.
  113. * } @endcode
  114. */
  115. template <typename Protocol, typename Executor, typename EndpointSequence>
  116. typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
  117. const EndpointSequence& endpoints, boost::system::error_code& ec,
  118. typename enable_if<is_endpoint_sequence<
  119. EndpointSequence>::value>::type* = 0);
  120. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  121. /// (Deprecated: Use range overload.) Establishes a socket connection by trying
  122. /// each endpoint in a sequence.
  123. /**
  124. * This function attempts to connect a socket to one of a sequence of
  125. * endpoints. It does this by repeated calls to the socket's @c connect member
  126. * function, once for each endpoint in the sequence, until a connection is
  127. * successfully established.
  128. *
  129. * @param s The socket to be connected. If the socket is already open, it will
  130. * be closed.
  131. *
  132. * @param begin An iterator pointing to the start of a sequence of endpoints.
  133. *
  134. * @returns On success, an iterator denoting the successfully connected
  135. * endpoint. Otherwise, the end iterator.
  136. *
  137. * @throws boost::system::system_error Thrown on failure. If the sequence is
  138. * empty, the associated @c error_code is boost::asio::error::not_found.
  139. * Otherwise, contains the error from the last connection attempt.
  140. *
  141. * @note This overload assumes that a default constructed object of type @c
  142. * Iterator represents the end of the sequence. This is a valid assumption for
  143. * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
  144. */
  145. template <typename Protocol, typename Executor, typename Iterator>
  146. Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin,
  147. typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
  148. /// (Deprecated: Use range overload.) Establishes a socket connection by trying
  149. /// each endpoint in a sequence.
  150. /**
  151. * This function attempts to connect a socket to one of a sequence of
  152. * endpoints. It does this by repeated calls to the socket's @c connect member
  153. * function, once for each endpoint in the sequence, until a connection is
  154. * successfully established.
  155. *
  156. * @param s The socket to be connected. If the socket is already open, it will
  157. * be closed.
  158. *
  159. * @param begin An iterator pointing to the start of a sequence of endpoints.
  160. *
  161. * @param ec Set to indicate what error occurred, if any. If the sequence is
  162. * empty, set to boost::asio::error::not_found. Otherwise, contains the error
  163. * from the last connection attempt.
  164. *
  165. * @returns On success, an iterator denoting the successfully connected
  166. * endpoint. Otherwise, the end iterator.
  167. *
  168. * @note This overload assumes that a default constructed object of type @c
  169. * Iterator represents the end of the sequence. This is a valid assumption for
  170. * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
  171. */
  172. template <typename Protocol, typename Executor, typename Iterator>
  173. Iterator connect(basic_socket<Protocol, Executor>& s,
  174. Iterator begin, boost::system::error_code& ec,
  175. typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
  176. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  177. /// Establishes a socket connection by trying each endpoint in a sequence.
  178. /**
  179. * This function attempts to connect a socket to one of a sequence of
  180. * endpoints. It does this by repeated calls to the socket's @c connect member
  181. * function, once for each endpoint in the sequence, until a connection is
  182. * successfully established.
  183. *
  184. * @param s The socket to be connected. If the socket is already open, it will
  185. * be closed.
  186. *
  187. * @param begin An iterator pointing to the start of a sequence of endpoints.
  188. *
  189. * @param end An iterator pointing to the end of a sequence of endpoints.
  190. *
  191. * @returns An iterator denoting the successfully connected endpoint.
  192. *
  193. * @throws boost::system::system_error Thrown on failure. If the sequence is
  194. * empty, the associated @c error_code is boost::asio::error::not_found.
  195. * Otherwise, contains the error from the last connection attempt.
  196. *
  197. * @par Example
  198. * @code tcp::resolver r(my_context);
  199. * tcp::resolver::query q("host", "service");
  200. * tcp::resolver::results_type e = r.resolve(q);
  201. * tcp::socket s(my_context);
  202. * boost::asio::connect(s, e.begin(), e.end()); @endcode
  203. */
  204. template <typename Protocol, typename Executor, typename Iterator>
  205. Iterator connect(basic_socket<Protocol, Executor>& s,
  206. Iterator begin, Iterator end);
  207. /// Establishes a socket connection by trying each endpoint in a sequence.
  208. /**
  209. * This function attempts to connect a socket to one of a sequence of
  210. * endpoints. It does this by repeated calls to the socket's @c connect member
  211. * function, once for each endpoint in the sequence, until a connection is
  212. * successfully established.
  213. *
  214. * @param s The socket to be connected. If the socket is already open, it will
  215. * be closed.
  216. *
  217. * @param begin An iterator pointing to the start of a sequence of endpoints.
  218. *
  219. * @param end An iterator pointing to the end of a sequence of endpoints.
  220. *
  221. * @param ec Set to indicate what error occurred, if any. If the sequence is
  222. * empty, set to boost::asio::error::not_found. Otherwise, contains the error
  223. * from the last connection attempt.
  224. *
  225. * @returns On success, an iterator denoting the successfully connected
  226. * endpoint. Otherwise, the end iterator.
  227. *
  228. * @par Example
  229. * @code tcp::resolver r(my_context);
  230. * tcp::resolver::query q("host", "service");
  231. * tcp::resolver::results_type e = r.resolve(q);
  232. * tcp::socket s(my_context);
  233. * boost::system::error_code ec;
  234. * boost::asio::connect(s, e.begin(), e.end(), ec);
  235. * if (ec)
  236. * {
  237. * // An error occurred.
  238. * } @endcode
  239. */
  240. template <typename Protocol, typename Executor, typename Iterator>
  241. Iterator connect(basic_socket<Protocol, Executor>& s,
  242. Iterator begin, Iterator end, boost::system::error_code& ec);
  243. /// Establishes a socket connection by trying each endpoint in a sequence.
  244. /**
  245. * This function attempts to connect a socket to one of a sequence of
  246. * endpoints. It does this by repeated calls to the socket's @c connect member
  247. * function, once for each endpoint in the sequence, until a connection is
  248. * successfully established.
  249. *
  250. * @param s The socket to be connected. If the socket is already open, it will
  251. * be closed.
  252. *
  253. * @param endpoints A sequence of endpoints.
  254. *
  255. * @param connect_condition A function object that is called prior to each
  256. * connection attempt. The signature of the function object must be:
  257. * @code bool connect_condition(
  258. * const boost::system::error_code& ec,
  259. * const typename Protocol::endpoint& next); @endcode
  260. * The @c ec parameter contains the result from the most recent connect
  261. * operation. Before the first connection attempt, @c ec is always set to
  262. * indicate success. The @c next parameter is the next endpoint to be tried.
  263. * The function object should return true if the next endpoint should be tried,
  264. * and false if it should be skipped.
  265. *
  266. * @returns The successfully connected endpoint.
  267. *
  268. * @throws boost::system::system_error Thrown on failure. If the sequence is
  269. * empty, the associated @c error_code is boost::asio::error::not_found.
  270. * Otherwise, contains the error from the last connection attempt.
  271. *
  272. * @par Example
  273. * The following connect condition function object can be used to output
  274. * information about the individual connection attempts:
  275. * @code struct my_connect_condition
  276. * {
  277. * bool operator()(
  278. * const boost::system::error_code& ec,
  279. * const::tcp::endpoint& next)
  280. * {
  281. * if (ec) std::cout << "Error: " << ec.message() << std::endl;
  282. * std::cout << "Trying: " << next << std::endl;
  283. * return true;
  284. * }
  285. * }; @endcode
  286. * It would be used with the boost::asio::connect function as follows:
  287. * @code tcp::resolver r(my_context);
  288. * tcp::resolver::query q("host", "service");
  289. * tcp::socket s(my_context);
  290. * tcp::endpoint e = boost::asio::connect(s,
  291. * r.resolve(q), my_connect_condition());
  292. * std::cout << "Connected to: " << e << std::endl; @endcode
  293. */
  294. template <typename Protocol, typename Executor,
  295. typename EndpointSequence, typename ConnectCondition>
  296. typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
  297. const EndpointSequence& endpoints, ConnectCondition connect_condition,
  298. typename enable_if<is_endpoint_sequence<
  299. EndpointSequence>::value>::type* = 0);
  300. /// Establishes a socket connection by trying each endpoint in a sequence.
  301. /**
  302. * This function attempts to connect a socket to one of a sequence of
  303. * endpoints. It does this by repeated calls to the socket's @c connect member
  304. * function, once for each endpoint in the sequence, until a connection is
  305. * successfully established.
  306. *
  307. * @param s The socket to be connected. If the socket is already open, it will
  308. * be closed.
  309. *
  310. * @param endpoints A sequence of endpoints.
  311. *
  312. * @param connect_condition A function object that is called prior to each
  313. * connection attempt. The signature of the function object must be:
  314. * @code bool connect_condition(
  315. * const boost::system::error_code& ec,
  316. * const typename Protocol::endpoint& next); @endcode
  317. * The @c ec parameter contains the result from the most recent connect
  318. * operation. Before the first connection attempt, @c ec is always set to
  319. * indicate success. The @c next parameter is the next endpoint to be tried.
  320. * The function object should return true if the next endpoint should be tried,
  321. * and false if it should be skipped.
  322. *
  323. * @param ec Set to indicate what error occurred, if any. If the sequence is
  324. * empty, set to boost::asio::error::not_found. Otherwise, contains the error
  325. * from the last connection attempt.
  326. *
  327. * @returns On success, the successfully connected endpoint. Otherwise, a
  328. * default-constructed endpoint.
  329. *
  330. * @par Example
  331. * The following connect condition function object can be used to output
  332. * information about the individual connection attempts:
  333. * @code struct my_connect_condition
  334. * {
  335. * bool operator()(
  336. * const boost::system::error_code& ec,
  337. * const::tcp::endpoint& next)
  338. * {
  339. * if (ec) std::cout << "Error: " << ec.message() << std::endl;
  340. * std::cout << "Trying: " << next << std::endl;
  341. * return true;
  342. * }
  343. * }; @endcode
  344. * It would be used with the boost::asio::connect function as follows:
  345. * @code tcp::resolver r(my_context);
  346. * tcp::resolver::query q("host", "service");
  347. * tcp::socket s(my_context);
  348. * boost::system::error_code ec;
  349. * tcp::endpoint e = boost::asio::connect(s,
  350. * r.resolve(q), my_connect_condition(), ec);
  351. * if (ec)
  352. * {
  353. * // An error occurred.
  354. * }
  355. * else
  356. * {
  357. * std::cout << "Connected to: " << e << std::endl;
  358. * } @endcode
  359. */
  360. template <typename Protocol, typename Executor,
  361. typename EndpointSequence, typename ConnectCondition>
  362. typename Protocol::endpoint connect(basic_socket<Protocol, Executor>& s,
  363. const EndpointSequence& endpoints, ConnectCondition connect_condition,
  364. boost::system::error_code& ec,
  365. typename enable_if<is_endpoint_sequence<
  366. EndpointSequence>::value>::type* = 0);
  367. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  368. /// (Deprecated: Use range overload.) Establishes a socket connection by trying
  369. /// each endpoint in a sequence.
  370. /**
  371. * This function attempts to connect a socket to one of a sequence of
  372. * endpoints. It does this by repeated calls to the socket's @c connect member
  373. * function, once for each endpoint in the sequence, until a connection is
  374. * successfully established.
  375. *
  376. * @param s The socket to be connected. If the socket is already open, it will
  377. * be closed.
  378. *
  379. * @param begin An iterator pointing to the start of a sequence of endpoints.
  380. *
  381. * @param connect_condition A function object that is called prior to each
  382. * connection attempt. The signature of the function object must be:
  383. * @code bool connect_condition(
  384. * const boost::system::error_code& ec,
  385. * const typename Protocol::endpoint& next); @endcode
  386. * The @c ec parameter contains the result from the most recent connect
  387. * operation. Before the first connection attempt, @c ec is always set to
  388. * indicate success. The @c next parameter is the next endpoint to be tried.
  389. * The function object should return true if the next endpoint should be tried,
  390. * and false if it should be skipped.
  391. *
  392. * @returns On success, an iterator denoting the successfully connected
  393. * endpoint. Otherwise, the end iterator.
  394. *
  395. * @throws boost::system::system_error Thrown on failure. If the sequence is
  396. * empty, the associated @c error_code is boost::asio::error::not_found.
  397. * Otherwise, contains the error from the last connection attempt.
  398. *
  399. * @note This overload assumes that a default constructed object of type @c
  400. * Iterator represents the end of the sequence. This is a valid assumption for
  401. * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
  402. */
  403. template <typename Protocol, typename Executor,
  404. typename Iterator, typename ConnectCondition>
  405. Iterator connect(basic_socket<Protocol, Executor>& s,
  406. Iterator begin, ConnectCondition connect_condition,
  407. typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
  408. /// (Deprecated: Use range overload.) Establishes a socket connection by trying
  409. /// each endpoint in a sequence.
  410. /**
  411. * This function attempts to connect a socket to one of a sequence of
  412. * endpoints. It does this by repeated calls to the socket's @c connect member
  413. * function, once for each endpoint in the sequence, until a connection is
  414. * successfully established.
  415. *
  416. * @param s The socket to be connected. If the socket is already open, it will
  417. * be closed.
  418. *
  419. * @param begin An iterator pointing to the start of a sequence of endpoints.
  420. *
  421. * @param connect_condition A function object that is called prior to each
  422. * connection attempt. The signature of the function object must be:
  423. * @code bool connect_condition(
  424. * const boost::system::error_code& ec,
  425. * const typename Protocol::endpoint& next); @endcode
  426. * The @c ec parameter contains the result from the most recent connect
  427. * operation. Before the first connection attempt, @c ec is always set to
  428. * indicate success. The @c next parameter is the next endpoint to be tried.
  429. * The function object should return true if the next endpoint should be tried,
  430. * and false if it should be skipped.
  431. *
  432. * @param ec Set to indicate what error occurred, if any. If the sequence is
  433. * empty, set to boost::asio::error::not_found. Otherwise, contains the error
  434. * from the last connection attempt.
  435. *
  436. * @returns On success, an iterator denoting the successfully connected
  437. * endpoint. Otherwise, the end iterator.
  438. *
  439. * @note This overload assumes that a default constructed object of type @c
  440. * Iterator represents the end of the sequence. This is a valid assumption for
  441. * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
  442. */
  443. template <typename Protocol, typename Executor,
  444. typename Iterator, typename ConnectCondition>
  445. Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin,
  446. ConnectCondition connect_condition, boost::system::error_code& ec,
  447. typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
  448. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  449. /// Establishes a socket connection by trying each endpoint in a sequence.
  450. /**
  451. * This function attempts to connect a socket to one of a sequence of
  452. * endpoints. It does this by repeated calls to the socket's @c connect member
  453. * function, once for each endpoint in the sequence, until a connection is
  454. * successfully established.
  455. *
  456. * @param s The socket to be connected. If the socket is already open, it will
  457. * be closed.
  458. *
  459. * @param begin An iterator pointing to the start of a sequence of endpoints.
  460. *
  461. * @param end An iterator pointing to the end of a sequence of endpoints.
  462. *
  463. * @param connect_condition A function object that is called prior to each
  464. * connection attempt. The signature of the function object must be:
  465. * @code bool connect_condition(
  466. * const boost::system::error_code& ec,
  467. * const typename Protocol::endpoint& next); @endcode
  468. * The @c ec parameter contains the result from the most recent connect
  469. * operation. Before the first connection attempt, @c ec is always set to
  470. * indicate success. The @c next parameter is the next endpoint to be tried.
  471. * The function object should return true if the next endpoint should be tried,
  472. * and false if it should be skipped.
  473. *
  474. * @returns An iterator denoting the successfully connected endpoint.
  475. *
  476. * @throws boost::system::system_error Thrown on failure. If the sequence is
  477. * empty, the associated @c error_code is boost::asio::error::not_found.
  478. * Otherwise, contains the error from the last connection attempt.
  479. *
  480. * @par Example
  481. * The following connect condition function object can be used to output
  482. * information about the individual connection attempts:
  483. * @code struct my_connect_condition
  484. * {
  485. * bool operator()(
  486. * const boost::system::error_code& ec,
  487. * const::tcp::endpoint& next)
  488. * {
  489. * if (ec) std::cout << "Error: " << ec.message() << std::endl;
  490. * std::cout << "Trying: " << next << std::endl;
  491. * return true;
  492. * }
  493. * }; @endcode
  494. * It would be used with the boost::asio::connect function as follows:
  495. * @code tcp::resolver r(my_context);
  496. * tcp::resolver::query q("host", "service");
  497. * tcp::resolver::results_type e = r.resolve(q);
  498. * tcp::socket s(my_context);
  499. * tcp::resolver::results_type::iterator i = boost::asio::connect(
  500. * s, e.begin(), e.end(), my_connect_condition());
  501. * std::cout << "Connected to: " << i->endpoint() << std::endl; @endcode
  502. */
  503. template <typename Protocol, typename Executor,
  504. typename Iterator, typename ConnectCondition>
  505. Iterator connect(basic_socket<Protocol, Executor>& s, Iterator begin,
  506. Iterator end, ConnectCondition connect_condition);
  507. /// Establishes a socket connection by trying each endpoint in a sequence.
  508. /**
  509. * This function attempts to connect a socket to one of a sequence of
  510. * endpoints. It does this by repeated calls to the socket's @c connect member
  511. * function, once for each endpoint in the sequence, until a connection is
  512. * successfully established.
  513. *
  514. * @param s The socket to be connected. If the socket is already open, it will
  515. * be closed.
  516. *
  517. * @param begin An iterator pointing to the start of a sequence of endpoints.
  518. *
  519. * @param end An iterator pointing to the end of a sequence of endpoints.
  520. *
  521. * @param connect_condition A function object that is called prior to each
  522. * connection attempt. The signature of the function object must be:
  523. * @code bool connect_condition(
  524. * const boost::system::error_code& ec,
  525. * const typename Protocol::endpoint& next); @endcode
  526. * The @c ec parameter contains the result from the most recent connect
  527. * operation. Before the first connection attempt, @c ec is always set to
  528. * indicate success. The @c next parameter is the next endpoint to be tried.
  529. * The function object should return true if the next endpoint should be tried,
  530. * and false if it should be skipped.
  531. *
  532. * @param ec Set to indicate what error occurred, if any. If the sequence is
  533. * empty, set to boost::asio::error::not_found. Otherwise, contains the error
  534. * from the last connection attempt.
  535. *
  536. * @returns On success, an iterator denoting the successfully connected
  537. * endpoint. Otherwise, the end iterator.
  538. *
  539. * @par Example
  540. * The following connect condition function object can be used to output
  541. * information about the individual connection attempts:
  542. * @code struct my_connect_condition
  543. * {
  544. * bool operator()(
  545. * const boost::system::error_code& ec,
  546. * const::tcp::endpoint& next)
  547. * {
  548. * if (ec) std::cout << "Error: " << ec.message() << std::endl;
  549. * std::cout << "Trying: " << next << std::endl;
  550. * return true;
  551. * }
  552. * }; @endcode
  553. * It would be used with the boost::asio::connect function as follows:
  554. * @code tcp::resolver r(my_context);
  555. * tcp::resolver::query q("host", "service");
  556. * tcp::resolver::results_type e = r.resolve(q);
  557. * tcp::socket s(my_context);
  558. * boost::system::error_code ec;
  559. * tcp::resolver::results_type::iterator i = boost::asio::connect(
  560. * s, e.begin(), e.end(), my_connect_condition());
  561. * if (ec)
  562. * {
  563. * // An error occurred.
  564. * }
  565. * else
  566. * {
  567. * std::cout << "Connected to: " << i->endpoint() << std::endl;
  568. * } @endcode
  569. */
  570. template <typename Protocol, typename Executor,
  571. typename Iterator, typename ConnectCondition>
  572. Iterator connect(basic_socket<Protocol, Executor>& s,
  573. Iterator begin, Iterator end, ConnectCondition connect_condition,
  574. boost::system::error_code& ec);
  575. /*@}*/
  576. /**
  577. * @defgroup async_connect boost::asio::async_connect
  578. *
  579. * @brief The @c async_connect function is a composed asynchronous operation
  580. * that establishes a socket connection by trying each endpoint in a sequence.
  581. */
  582. /*@{*/
  583. /// Asynchronously establishes a socket connection by trying each endpoint in a
  584. /// sequence.
  585. /**
  586. * This function attempts to connect a socket to one of a sequence of
  587. * endpoints. It does this by repeated calls to the socket's @c async_connect
  588. * member function, once for each endpoint in the sequence, until a connection
  589. * is successfully established.
  590. *
  591. * @param s The socket to be connected. If the socket is already open, it will
  592. * be closed.
  593. *
  594. * @param endpoints A sequence of endpoints.
  595. *
  596. * @param handler The handler to be called when the connect operation
  597. * completes. Copies will be made of the handler as required. The function
  598. * signature of the handler must be:
  599. * @code void handler(
  600. * // Result of operation. if the sequence is empty, set to
  601. * // boost::asio::error::not_found. Otherwise, contains the
  602. * // error from the last connection attempt.
  603. * const boost::system::error_code& error,
  604. *
  605. * // On success, the successfully connected endpoint.
  606. * // Otherwise, a default-constructed endpoint.
  607. * const typename Protocol::endpoint& endpoint
  608. * ); @endcode
  609. * Regardless of whether the asynchronous operation completes immediately or
  610. * not, the handler will not be invoked from within this function. On
  611. * immediate completion, invocation of the handler will be performed in a
  612. * manner equivalent to using boost::asio::post().
  613. *
  614. * @par Example
  615. * @code tcp::resolver r(my_context);
  616. * tcp::resolver::query q("host", "service");
  617. * tcp::socket s(my_context);
  618. *
  619. * // ...
  620. *
  621. * r.async_resolve(q, resolve_handler);
  622. *
  623. * // ...
  624. *
  625. * void resolve_handler(
  626. * const boost::system::error_code& ec,
  627. * tcp::resolver::results_type results)
  628. * {
  629. * if (!ec)
  630. * {
  631. * boost::asio::async_connect(s, results, connect_handler);
  632. * }
  633. * }
  634. *
  635. * // ...
  636. *
  637. * void connect_handler(
  638. * const boost::system::error_code& ec,
  639. * const tcp::endpoint& endpoint)
  640. * {
  641. * // ...
  642. * } @endcode
  643. */
  644. template <typename Protocol, typename Executor, typename EndpointSequence,
  645. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  646. typename Protocol::endpoint)) RangeConnectHandler
  647. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
  648. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectHandler,
  649. void (boost::system::error_code, typename Protocol::endpoint))
  650. async_connect(basic_socket<Protocol, Executor>& s,
  651. const EndpointSequence& endpoints,
  652. BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler
  653. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
  654. typename enable_if<is_endpoint_sequence<
  655. EndpointSequence>::value>::type* = 0);
  656. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  657. /// (Deprecated: Use range overload.) Asynchronously establishes a socket
  658. /// connection by trying each endpoint in a sequence.
  659. /**
  660. * This function attempts to connect a socket to one of a sequence of
  661. * endpoints. It does this by repeated calls to the socket's @c async_connect
  662. * member function, once for each endpoint in the sequence, until a connection
  663. * is successfully established.
  664. *
  665. * @param s The socket to be connected. If the socket is already open, it will
  666. * be closed.
  667. *
  668. * @param begin An iterator pointing to the start of a sequence of endpoints.
  669. *
  670. * @param handler The handler to be called when the connect operation
  671. * completes. Copies will be made of the handler as required. The function
  672. * signature of the handler must be:
  673. * @code void handler(
  674. * // Result of operation. if the sequence is empty, set to
  675. * // boost::asio::error::not_found. Otherwise, contains the
  676. * // error from the last connection attempt.
  677. * const boost::system::error_code& error,
  678. *
  679. * // On success, an iterator denoting the successfully
  680. * // connected endpoint. Otherwise, the end iterator.
  681. * Iterator iterator
  682. * ); @endcode
  683. * Regardless of whether the asynchronous operation completes immediately or
  684. * not, the handler will not be invoked from within this function. On
  685. * immediate completion, invocation of the handler will be performed in a
  686. * manner equivalent to using boost::asio::post().
  687. *
  688. * @note This overload assumes that a default constructed object of type @c
  689. * Iterator represents the end of the sequence. This is a valid assumption for
  690. * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
  691. */
  692. template <typename Protocol, typename Executor, typename Iterator,
  693. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  694. Iterator)) IteratorConnectHandler
  695. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
  696. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler,
  697. void (boost::system::error_code, Iterator))
  698. async_connect(basic_socket<Protocol, Executor>& s, Iterator begin,
  699. BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler
  700. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
  701. typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
  702. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  703. /// Asynchronously establishes a socket connection by trying each endpoint in a
  704. /// sequence.
  705. /**
  706. * This function attempts to connect a socket to one of a sequence of
  707. * endpoints. It does this by repeated calls to the socket's @c async_connect
  708. * member function, once for each endpoint in the sequence, until a connection
  709. * is successfully established.
  710. *
  711. * @param s The socket to be connected. If the socket is already open, it will
  712. * be closed.
  713. *
  714. * @param begin An iterator pointing to the start of a sequence of endpoints.
  715. *
  716. * @param end An iterator pointing to the end of a sequence of endpoints.
  717. *
  718. * @param handler The handler to be called when the connect operation
  719. * completes. Copies will be made of the handler as required. The function
  720. * signature of the handler must be:
  721. * @code void handler(
  722. * // Result of operation. if the sequence is empty, set to
  723. * // boost::asio::error::not_found. Otherwise, contains the
  724. * // error from the last connection attempt.
  725. * const boost::system::error_code& error,
  726. *
  727. * // On success, an iterator denoting the successfully
  728. * // connected endpoint. Otherwise, the end iterator.
  729. * Iterator iterator
  730. * ); @endcode
  731. * Regardless of whether the asynchronous operation completes immediately or
  732. * not, the handler will not be invoked from within this function. On
  733. * immediate completion, invocation of the handler will be performed in a
  734. * manner equivalent to using boost::asio::post().
  735. *
  736. * @par Example
  737. * @code std::vector<tcp::endpoint> endpoints = ...;
  738. * tcp::socket s(my_context);
  739. * boost::asio::async_connect(s,
  740. * endpoints.begin(), endpoints.end(),
  741. * connect_handler);
  742. *
  743. * // ...
  744. *
  745. * void connect_handler(
  746. * const boost::system::error_code& ec,
  747. * std::vector<tcp::endpoint>::iterator i)
  748. * {
  749. * // ...
  750. * } @endcode
  751. */
  752. template <typename Protocol, typename Executor, typename Iterator,
  753. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  754. Iterator)) IteratorConnectHandler
  755. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
  756. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler,
  757. void (boost::system::error_code, Iterator))
  758. async_connect(basic_socket<Protocol, Executor>& s, Iterator begin, Iterator end,
  759. BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler
  760. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor));
  761. /// Asynchronously establishes a socket connection by trying each endpoint in a
  762. /// sequence.
  763. /**
  764. * This function attempts to connect a socket to one of a sequence of
  765. * endpoints. It does this by repeated calls to the socket's @c async_connect
  766. * member function, once for each endpoint in the sequence, until a connection
  767. * is successfully established.
  768. *
  769. * @param s The socket to be connected. If the socket is already open, it will
  770. * be closed.
  771. *
  772. * @param endpoints A sequence of endpoints.
  773. *
  774. * @param connect_condition A function object that is called prior to each
  775. * connection attempt. The signature of the function object must be:
  776. * @code bool connect_condition(
  777. * const boost::system::error_code& ec,
  778. * const typename Protocol::endpoint& next); @endcode
  779. * The @c ec parameter contains the result from the most recent connect
  780. * operation. Before the first connection attempt, @c ec is always set to
  781. * indicate success. The @c next parameter is the next endpoint to be tried.
  782. * The function object should return true if the next endpoint should be tried,
  783. * and false if it should be skipped.
  784. *
  785. * @param handler The handler to be called when the connect operation
  786. * completes. Copies will be made of the handler as required. The function
  787. * signature of the handler must be:
  788. * @code void handler(
  789. * // Result of operation. if the sequence is empty, set to
  790. * // boost::asio::error::not_found. Otherwise, contains the
  791. * // error from the last connection attempt.
  792. * const boost::system::error_code& error,
  793. *
  794. * // On success, an iterator denoting the successfully
  795. * // connected endpoint. Otherwise, the end iterator.
  796. * Iterator iterator
  797. * ); @endcode
  798. * Regardless of whether the asynchronous operation completes immediately or
  799. * not, the handler will not be invoked from within this function. On
  800. * immediate completion, invocation of the handler will be performed in a
  801. * manner equivalent to using boost::asio::post().
  802. *
  803. * @par Example
  804. * The following connect condition function object can be used to output
  805. * information about the individual connection attempts:
  806. * @code struct my_connect_condition
  807. * {
  808. * bool operator()(
  809. * const boost::system::error_code& ec,
  810. * const::tcp::endpoint& next)
  811. * {
  812. * if (ec) std::cout << "Error: " << ec.message() << std::endl;
  813. * std::cout << "Trying: " << next << std::endl;
  814. * return true;
  815. * }
  816. * }; @endcode
  817. * It would be used with the boost::asio::connect function as follows:
  818. * @code tcp::resolver r(my_context);
  819. * tcp::resolver::query q("host", "service");
  820. * tcp::socket s(my_context);
  821. *
  822. * // ...
  823. *
  824. * r.async_resolve(q, resolve_handler);
  825. *
  826. * // ...
  827. *
  828. * void resolve_handler(
  829. * const boost::system::error_code& ec,
  830. * tcp::resolver::results_type results)
  831. * {
  832. * if (!ec)
  833. * {
  834. * boost::asio::async_connect(s, results,
  835. * my_connect_condition(),
  836. * connect_handler);
  837. * }
  838. * }
  839. *
  840. * // ...
  841. *
  842. * void connect_handler(
  843. * const boost::system::error_code& ec,
  844. * const tcp::endpoint& endpoint)
  845. * {
  846. * if (ec)
  847. * {
  848. * // An error occurred.
  849. * }
  850. * else
  851. * {
  852. * std::cout << "Connected to: " << endpoint << std::endl;
  853. * }
  854. * } @endcode
  855. */
  856. template <typename Protocol, typename Executor,
  857. typename EndpointSequence, typename ConnectCondition,
  858. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  859. typename Protocol::endpoint)) RangeConnectHandler
  860. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
  861. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(RangeConnectHandler,
  862. void (boost::system::error_code, typename Protocol::endpoint))
  863. async_connect(basic_socket<Protocol, Executor>& s,
  864. const EndpointSequence& endpoints, ConnectCondition connect_condition,
  865. BOOST_ASIO_MOVE_ARG(RangeConnectHandler) handler
  866. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
  867. typename enable_if<is_endpoint_sequence<
  868. EndpointSequence>::value>::type* = 0);
  869. #if !defined(BOOST_ASIO_NO_DEPRECATED)
  870. /// (Deprecated: Use range overload.) Asynchronously establishes a socket
  871. /// connection by trying each endpoint in a sequence.
  872. /**
  873. * This function attempts to connect a socket to one of a sequence of
  874. * endpoints. It does this by repeated calls to the socket's @c async_connect
  875. * member function, once for each endpoint in the sequence, until a connection
  876. * is successfully established.
  877. *
  878. * @param s The socket to be connected. If the socket is already open, it will
  879. * be closed.
  880. *
  881. * @param begin An iterator pointing to the start of a sequence of endpoints.
  882. *
  883. * @param connect_condition A function object that is called prior to each
  884. * connection attempt. The signature of the function object must be:
  885. * @code bool connect_condition(
  886. * const boost::system::error_code& ec,
  887. * const typename Protocol::endpoint& next); @endcode
  888. * The @c ec parameter contains the result from the most recent connect
  889. * operation. Before the first connection attempt, @c ec is always set to
  890. * indicate success. The @c next parameter is the next endpoint to be tried.
  891. * The function object should return true if the next endpoint should be tried,
  892. * and false if it should be skipped.
  893. *
  894. * @param handler The handler to be called when the connect operation
  895. * completes. Copies will be made of the handler as required. The function
  896. * signature of the handler must be:
  897. * @code void handler(
  898. * // Result of operation. if the sequence is empty, set to
  899. * // boost::asio::error::not_found. Otherwise, contains the
  900. * // error from the last connection attempt.
  901. * const boost::system::error_code& error,
  902. *
  903. * // On success, an iterator denoting the successfully
  904. * // connected endpoint. Otherwise, the end iterator.
  905. * Iterator iterator
  906. * ); @endcode
  907. * Regardless of whether the asynchronous operation completes immediately or
  908. * not, the handler will not be invoked from within this function. On
  909. * immediate completion, invocation of the handler will be performed in a
  910. * manner equivalent to using boost::asio::post().
  911. *
  912. * @note This overload assumes that a default constructed object of type @c
  913. * Iterator represents the end of the sequence. This is a valid assumption for
  914. * iterator types such as @c boost::asio::ip::tcp::resolver::iterator.
  915. */
  916. template <typename Protocol, typename Executor,
  917. typename Iterator, typename ConnectCondition,
  918. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  919. Iterator)) IteratorConnectHandler
  920. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
  921. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler,
  922. void (boost::system::error_code, Iterator))
  923. async_connect(basic_socket<Protocol, Executor>& s, Iterator begin,
  924. ConnectCondition connect_condition,
  925. BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler
  926. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor),
  927. typename enable_if<!is_endpoint_sequence<Iterator>::value>::type* = 0);
  928. #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  929. /// Asynchronously establishes a socket connection by trying each endpoint in a
  930. /// sequence.
  931. /**
  932. * This function attempts to connect a socket to one of a sequence of
  933. * endpoints. It does this by repeated calls to the socket's @c async_connect
  934. * member function, once for each endpoint in the sequence, until a connection
  935. * is successfully established.
  936. *
  937. * @param s The socket to be connected. If the socket is already open, it will
  938. * be closed.
  939. *
  940. * @param begin An iterator pointing to the start of a sequence of endpoints.
  941. *
  942. * @param end An iterator pointing to the end of a sequence of endpoints.
  943. *
  944. * @param connect_condition A function object that is called prior to each
  945. * connection attempt. The signature of the function object must be:
  946. * @code bool connect_condition(
  947. * const boost::system::error_code& ec,
  948. * const typename Protocol::endpoint& next); @endcode
  949. * The @c ec parameter contains the result from the most recent connect
  950. * operation. Before the first connection attempt, @c ec is always set to
  951. * indicate success. The @c next parameter is the next endpoint to be tried.
  952. * The function object should return true if the next endpoint should be tried,
  953. * and false if it should be skipped.
  954. *
  955. * @param handler The handler to be called when the connect operation
  956. * completes. Copies will be made of the handler as required. The function
  957. * signature of the handler must be:
  958. * @code void handler(
  959. * // Result of operation. if the sequence is empty, set to
  960. * // boost::asio::error::not_found. Otherwise, contains the
  961. * // error from the last connection attempt.
  962. * const boost::system::error_code& error,
  963. *
  964. * // On success, an iterator denoting the successfully
  965. * // connected endpoint. Otherwise, the end iterator.
  966. * Iterator iterator
  967. * ); @endcode
  968. * Regardless of whether the asynchronous operation completes immediately or
  969. * not, the handler will not be invoked from within this function. On
  970. * immediate completion, invocation of the handler will be performed in a
  971. * manner equivalent to using boost::asio::post().
  972. *
  973. * @par Example
  974. * The following connect condition function object can be used to output
  975. * information about the individual connection attempts:
  976. * @code struct my_connect_condition
  977. * {
  978. * bool operator()(
  979. * const boost::system::error_code& ec,
  980. * const::tcp::endpoint& next)
  981. * {
  982. * if (ec) std::cout << "Error: " << ec.message() << std::endl;
  983. * std::cout << "Trying: " << next << std::endl;
  984. * return true;
  985. * }
  986. * }; @endcode
  987. * It would be used with the boost::asio::connect function as follows:
  988. * @code tcp::resolver r(my_context);
  989. * tcp::resolver::query q("host", "service");
  990. * tcp::socket s(my_context);
  991. *
  992. * // ...
  993. *
  994. * r.async_resolve(q, resolve_handler);
  995. *
  996. * // ...
  997. *
  998. * void resolve_handler(
  999. * const boost::system::error_code& ec,
  1000. * tcp::resolver::iterator i)
  1001. * {
  1002. * if (!ec)
  1003. * {
  1004. * tcp::resolver::iterator end;
  1005. * boost::asio::async_connect(s, i, end,
  1006. * my_connect_condition(),
  1007. * connect_handler);
  1008. * }
  1009. * }
  1010. *
  1011. * // ...
  1012. *
  1013. * void connect_handler(
  1014. * const boost::system::error_code& ec,
  1015. * tcp::resolver::iterator i)
  1016. * {
  1017. * if (ec)
  1018. * {
  1019. * // An error occurred.
  1020. * }
  1021. * else
  1022. * {
  1023. * std::cout << "Connected to: " << i->endpoint() << std::endl;
  1024. * }
  1025. * } @endcode
  1026. */
  1027. template <typename Protocol, typename Executor,
  1028. typename Iterator, typename ConnectCondition,
  1029. BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
  1030. Iterator)) IteratorConnectHandler
  1031. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(Executor)>
  1032. BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(IteratorConnectHandler,
  1033. void (boost::system::error_code, Iterator))
  1034. async_connect(basic_socket<Protocol, Executor>& s, Iterator begin,
  1035. Iterator end, ConnectCondition connect_condition,
  1036. BOOST_ASIO_MOVE_ARG(IteratorConnectHandler) handler
  1037. BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(Executor));
  1038. /*@}*/
  1039. } // namespace asio
  1040. } // namespace boost
  1041. #include <boost/asio/detail/pop_options.hpp>
  1042. #include <boost/asio/impl/connect.hpp>
  1043. #endif