Audio plugin host https://kx.studio/carla
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

850 lines
37KB

  1. //
  2. // ip/basic_resolver.hpp
  3. // ~~~~~~~~~~~~~~~~~~~~~
  4. //
  5. // Copyright (c) 2003-2015 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 ASIO_IP_BASIC_RESOLVER_HPP
  11. #define ASIO_IP_BASIC_RESOLVER_HPP
  12. #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  13. # pragma once
  14. #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  15. #include "asio/detail/config.hpp"
  16. #include <string>
  17. #include "asio/basic_io_object.hpp"
  18. #include "asio/detail/handler_type_requirements.hpp"
  19. #include "asio/detail/throw_error.hpp"
  20. #include "asio/error.hpp"
  21. #include "asio/ip/basic_resolver_iterator.hpp"
  22. #include "asio/ip/basic_resolver_query.hpp"
  23. #include "asio/ip/basic_resolver_results.hpp"
  24. #include "asio/ip/resolver_base.hpp"
  25. #include "asio/ip/resolver_service.hpp"
  26. #include "asio/detail/push_options.hpp"
  27. namespace asio {
  28. namespace ip {
  29. /// Provides endpoint resolution functionality.
  30. /**
  31. * The basic_resolver class template provides the ability to resolve a query
  32. * to a list of endpoints.
  33. *
  34. * @par Thread Safety
  35. * @e Distinct @e objects: Safe.@n
  36. * @e Shared @e objects: Unsafe.
  37. */
  38. template <typename InternetProtocol,
  39. typename ResolverService = resolver_service<InternetProtocol> >
  40. class basic_resolver
  41. : public basic_io_object<ResolverService>,
  42. public resolver_base
  43. {
  44. public:
  45. /// The protocol type.
  46. typedef InternetProtocol protocol_type;
  47. /// The endpoint type.
  48. typedef typename InternetProtocol::endpoint endpoint_type;
  49. #if !defined(ASIO_NO_DEPRECATED)
  50. /// (Deprecated.) The query type.
  51. typedef basic_resolver_query<InternetProtocol> query;
  52. /// (Deprecated.) The iterator type.
  53. typedef basic_resolver_iterator<InternetProtocol> iterator;
  54. #endif // !defined(ASIO_NO_DEPRECATED)
  55. /// The results type.
  56. typedef basic_resolver_results<InternetProtocol> results_type;
  57. /// Constructor.
  58. /**
  59. * This constructor creates a basic_resolver.
  60. *
  61. * @param io_context The io_context object that the resolver will use to
  62. * dispatch handlers for any asynchronous operations performed on the timer.
  63. */
  64. explicit basic_resolver(asio::io_context& io_context)
  65. : basic_io_object<ResolverService>(io_context)
  66. {
  67. }
  68. /// Cancel any asynchronous operations that are waiting on the resolver.
  69. /**
  70. * This function forces the completion of any pending asynchronous
  71. * operations on the host resolver. The handler for each cancelled operation
  72. * will be invoked with the asio::error::operation_aborted error code.
  73. */
  74. void cancel()
  75. {
  76. return this->get_service().cancel(this->get_implementation());
  77. }
  78. #if !defined(ASIO_NO_DEPRECATED)
  79. /// (Deprecated.) Perform forward resolution of a query to a list of entries.
  80. /**
  81. * This function is used to resolve a query into a list of endpoint entries.
  82. *
  83. * @param q A query object that determines what endpoints will be returned.
  84. *
  85. * @returns A range object representing the list of endpoint entries. A
  86. * successful call to this function is guaranteed to return a non-empty
  87. * range.
  88. *
  89. * @throws asio::system_error Thrown on failure.
  90. */
  91. results_type resolve(const query& q)
  92. {
  93. asio::error_code ec;
  94. results_type r = this->get_service().resolve(
  95. this->get_implementation(), q, ec);
  96. asio::detail::throw_error(ec, "resolve");
  97. return r;
  98. }
  99. /// (Deprecated.) Perform forward resolution of a query to a list of entries.
  100. /**
  101. * This function is used to resolve a query into a list of endpoint entries.
  102. *
  103. * @param q A query object that determines what endpoints will be returned.
  104. *
  105. * @param ec Set to indicate what error occurred, if any.
  106. *
  107. * @returns A range object representing the list of endpoint entries. An
  108. * empty range is returned if an error occurs. A successful call to this
  109. * function is guaranteed to return a non-empty range.
  110. */
  111. results_type resolve(const query& q, asio::error_code& ec)
  112. {
  113. return this->get_service().resolve(this->get_implementation(), q, ec);
  114. }
  115. #endif // !defined(ASIO_NO_DEPRECATED)
  116. /// Perform forward resolution of a query to a list of entries.
  117. /**
  118. * This function is used to resolve host and service names into a list of
  119. * endpoint entries.
  120. *
  121. * @param host A string identifying a location. May be a descriptive name or
  122. * a numeric address string. If an empty string and the passive flag has been
  123. * specified, the resolved endpoints are suitable for local service binding.
  124. * If an empty string and passive is not specified, the resolved endpoints
  125. * will use the loopback address.
  126. *
  127. * @param service A string identifying the requested service. This may be a
  128. * descriptive name or a numeric string corresponding to a port number. May
  129. * be an empty string, in which case all resolved endpoints will have a port
  130. * number of 0.
  131. *
  132. * @returns A range object representing the list of endpoint entries. A
  133. * successful call to this function is guaranteed to return a non-empty
  134. * range.
  135. *
  136. * @throws asio::system_error Thrown on failure.
  137. *
  138. * @note On POSIX systems, host names may be locally defined in the file
  139. * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
  140. * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
  141. * resolution is performed using DNS. Operating systems may use additional
  142. * locations when resolving host names (such as NETBIOS names on Windows).
  143. *
  144. * On POSIX systems, service names are typically defined in the file
  145. * <tt>/etc/services</tt>. On Windows, service names may be found in the file
  146. * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
  147. * may use additional locations when resolving service names.
  148. */
  149. results_type resolve(const std::string& host, const std::string& service)
  150. {
  151. return resolve(host, service, resolver_base::flags());
  152. }
  153. /// Perform forward resolution of a query to a list of entries.
  154. /**
  155. * This function is used to resolve host and service names into a list of
  156. * endpoint entries.
  157. *
  158. * @param host A string identifying a location. May be a descriptive name or
  159. * a numeric address string. If an empty string and the passive flag has been
  160. * specified, the resolved endpoints are suitable for local service binding.
  161. * If an empty string and passive is not specified, the resolved endpoints
  162. * will use the loopback address.
  163. *
  164. * @param service A string identifying the requested service. This may be a
  165. * descriptive name or a numeric string corresponding to a port number. May
  166. * be an empty string, in which case all resolved endpoints will have a port
  167. * number of 0.
  168. *
  169. * @param ec Set to indicate what error occurred, if any.
  170. *
  171. * @returns A range object representing the list of endpoint entries. An
  172. * empty range is returned if an error occurs. A successful call to this
  173. * function is guaranteed to return a non-empty range.
  174. *
  175. * @note On POSIX systems, host names may be locally defined in the file
  176. * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
  177. * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
  178. * resolution is performed using DNS. Operating systems may use additional
  179. * locations when resolving host names (such as NETBIOS names on Windows).
  180. *
  181. * On POSIX systems, service names are typically defined in the file
  182. * <tt>/etc/services</tt>. On Windows, service names may be found in the file
  183. * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
  184. * may use additional locations when resolving service names.
  185. */
  186. results_type resolve(const std::string& host, const std::string& service,
  187. asio::error_code& ec)
  188. {
  189. return resolve(host, service, resolver_base::flags(), ec);
  190. }
  191. /// Perform forward resolution of a query to a list of entries.
  192. /**
  193. * This function is used to resolve host and service names into a list of
  194. * endpoint entries.
  195. *
  196. * @param host A string identifying a location. May be a descriptive name or
  197. * a numeric address string. If an empty string and the passive flag has been
  198. * specified, the resolved endpoints are suitable for local service binding.
  199. * If an empty string and passive is not specified, the resolved endpoints
  200. * will use the loopback address.
  201. *
  202. * @param service A string identifying the requested service. This may be a
  203. * descriptive name or a numeric string corresponding to a port number. May
  204. * be an empty string, in which case all resolved endpoints will have a port
  205. * number of 0.
  206. *
  207. * @param resolve_flags A set of flags that determine how name resolution
  208. * should be performed. The default flags are suitable for communication with
  209. * remote hosts.
  210. *
  211. * @returns A range object representing the list of endpoint entries. A
  212. * successful call to this function is guaranteed to return a non-empty
  213. * range.
  214. *
  215. * @throws asio::system_error Thrown on failure.
  216. *
  217. * @note On POSIX systems, host names may be locally defined in the file
  218. * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
  219. * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
  220. * resolution is performed using DNS. Operating systems may use additional
  221. * locations when resolving host names (such as NETBIOS names on Windows).
  222. *
  223. * On POSIX systems, service names are typically defined in the file
  224. * <tt>/etc/services</tt>. On Windows, service names may be found in the file
  225. * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
  226. * may use additional locations when resolving service names.
  227. */
  228. results_type resolve(const std::string& host, const std::string& service,
  229. resolver_base::flags resolve_flags)
  230. {
  231. asio::error_code ec;
  232. basic_resolver_query<protocol_type> q(host, service, resolve_flags);
  233. results_type r = this->get_service().resolve(
  234. this->get_implementation(), q, ec);
  235. asio::detail::throw_error(ec, "resolve");
  236. return r;
  237. }
  238. /// Perform forward resolution of a query to a list of entries.
  239. /**
  240. * This function is used to resolve host and service names into a list of
  241. * endpoint entries.
  242. *
  243. * @param host A string identifying a location. May be a descriptive name or
  244. * a numeric address string. If an empty string and the passive flag has been
  245. * specified, the resolved endpoints are suitable for local service binding.
  246. * If an empty string and passive is not specified, the resolved endpoints
  247. * will use the loopback address.
  248. *
  249. * @param service A string identifying the requested service. This may be a
  250. * descriptive name or a numeric string corresponding to a port number. May
  251. * be an empty string, in which case all resolved endpoints will have a port
  252. * number of 0.
  253. *
  254. * @param resolve_flags A set of flags that determine how name resolution
  255. * should be performed. The default flags are suitable for communication with
  256. * remote hosts.
  257. *
  258. * @param ec Set to indicate what error occurred, if any.
  259. *
  260. * @returns A range object representing the list of endpoint entries. An
  261. * empty range is returned if an error occurs. A successful call to this
  262. * function is guaranteed to return a non-empty range.
  263. *
  264. * @note On POSIX systems, host names may be locally defined in the file
  265. * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
  266. * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
  267. * resolution is performed using DNS. Operating systems may use additional
  268. * locations when resolving host names (such as NETBIOS names on Windows).
  269. *
  270. * On POSIX systems, service names are typically defined in the file
  271. * <tt>/etc/services</tt>. On Windows, service names may be found in the file
  272. * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
  273. * may use additional locations when resolving service names.
  274. */
  275. results_type resolve(const std::string& host, const std::string& service,
  276. resolver_base::flags resolve_flags, asio::error_code& ec)
  277. {
  278. basic_resolver_query<protocol_type> q(host, service, resolve_flags);
  279. return this->get_service().resolve(this->get_implementation(), q, ec);
  280. }
  281. /// Perform forward resolution of a query to a list of entries.
  282. /**
  283. * This function is used to resolve host and service names into a list of
  284. * endpoint entries.
  285. *
  286. * @param protocol A protocol object, normally representing either the IPv4 or
  287. * IPv6 version of an internet protocol.
  288. *
  289. * @param host A string identifying a location. May be a descriptive name or
  290. * a numeric address string. If an empty string and the passive flag has been
  291. * specified, the resolved endpoints are suitable for local service binding.
  292. * If an empty string and passive is not specified, the resolved endpoints
  293. * will use the loopback address.
  294. *
  295. * @param service A string identifying the requested service. This may be a
  296. * descriptive name or a numeric string corresponding to a port number. May
  297. * be an empty string, in which case all resolved endpoints will have a port
  298. * number of 0.
  299. *
  300. * @returns A range object representing the list of endpoint entries. A
  301. * successful call to this function is guaranteed to return a non-empty
  302. * range.
  303. *
  304. * @throws asio::system_error Thrown on failure.
  305. *
  306. * @note On POSIX systems, host names may be locally defined in the file
  307. * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
  308. * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
  309. * resolution is performed using DNS. Operating systems may use additional
  310. * locations when resolving host names (such as NETBIOS names on Windows).
  311. *
  312. * On POSIX systems, service names are typically defined in the file
  313. * <tt>/etc/services</tt>. On Windows, service names may be found in the file
  314. * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
  315. * may use additional locations when resolving service names.
  316. */
  317. results_type resolve(const protocol_type& protocol, const std::string& host,
  318. const std::string& service)
  319. {
  320. return resolve(protocol, host, service, resolver_base::flags());
  321. }
  322. /// Perform forward resolution of a query to a list of entries.
  323. /**
  324. * This function is used to resolve host and service names into a list of
  325. * endpoint entries.
  326. *
  327. * @param protocol A protocol object, normally representing either the IPv4 or
  328. * IPv6 version of an internet protocol.
  329. *
  330. * @param host A string identifying a location. May be a descriptive name or
  331. * a numeric address string. If an empty string and the passive flag has been
  332. * specified, the resolved endpoints are suitable for local service binding.
  333. * If an empty string and passive is not specified, the resolved endpoints
  334. * will use the loopback address.
  335. *
  336. * @param service A string identifying the requested service. This may be a
  337. * descriptive name or a numeric string corresponding to a port number. May
  338. * be an empty string, in which case all resolved endpoints will have a port
  339. * number of 0.
  340. *
  341. * @param ec Set to indicate what error occurred, if any.
  342. *
  343. * @returns A range object representing the list of endpoint entries. An
  344. * empty range is returned if an error occurs. A successful call to this
  345. * function is guaranteed to return a non-empty range.
  346. *
  347. * @note On POSIX systems, host names may be locally defined in the file
  348. * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
  349. * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
  350. * resolution is performed using DNS. Operating systems may use additional
  351. * locations when resolving host names (such as NETBIOS names on Windows).
  352. *
  353. * On POSIX systems, service names are typically defined in the file
  354. * <tt>/etc/services</tt>. On Windows, service names may be found in the file
  355. * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
  356. * may use additional locations when resolving service names.
  357. */
  358. results_type resolve(const protocol_type& protocol, const std::string& host,
  359. const std::string& service, asio::error_code& ec)
  360. {
  361. return resolve(protocol, host, service, resolver_base::flags(), ec);
  362. }
  363. /// Perform forward resolution of a query to a list of entries.
  364. /**
  365. * This function is used to resolve host and service names into a list of
  366. * endpoint entries.
  367. *
  368. * @param protocol A protocol object, normally representing either the IPv4 or
  369. * IPv6 version of an internet protocol.
  370. *
  371. * @param host A string identifying a location. May be a descriptive name or
  372. * a numeric address string. If an empty string and the passive flag has been
  373. * specified, the resolved endpoints are suitable for local service binding.
  374. * If an empty string and passive is not specified, the resolved endpoints
  375. * will use the loopback address.
  376. *
  377. * @param service A string identifying the requested service. This may be a
  378. * descriptive name or a numeric string corresponding to a port number. May
  379. * be an empty string, in which case all resolved endpoints will have a port
  380. * number of 0.
  381. *
  382. * @param resolve_flags A set of flags that determine how name resolution
  383. * should be performed. The default flags are suitable for communication with
  384. * remote hosts.
  385. *
  386. * @returns A range object representing the list of endpoint entries. A
  387. * successful call to this function is guaranteed to return a non-empty
  388. * range.
  389. *
  390. * @throws asio::system_error Thrown on failure.
  391. *
  392. * @note On POSIX systems, host names may be locally defined in the file
  393. * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
  394. * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
  395. * resolution is performed using DNS. Operating systems may use additional
  396. * locations when resolving host names (such as NETBIOS names on Windows).
  397. *
  398. * On POSIX systems, service names are typically defined in the file
  399. * <tt>/etc/services</tt>. On Windows, service names may be found in the file
  400. * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
  401. * may use additional locations when resolving service names.
  402. */
  403. results_type resolve(const protocol_type& protocol, const std::string& host,
  404. const std::string& service, resolver_base::flags resolve_flags)
  405. {
  406. asio::error_code ec;
  407. basic_resolver_query<protocol_type> q(
  408. protocol, host, service, resolve_flags);
  409. results_type r = this->get_service().resolve(
  410. this->get_implementation(), q, ec);
  411. asio::detail::throw_error(ec, "resolve");
  412. return r;
  413. }
  414. /// Perform forward resolution of a query to a list of entries.
  415. /**
  416. * This function is used to resolve host and service names into a list of
  417. * endpoint entries.
  418. *
  419. * @param protocol A protocol object, normally representing either the IPv4 or
  420. * IPv6 version of an internet protocol.
  421. *
  422. * @param host A string identifying a location. May be a descriptive name or
  423. * a numeric address string. If an empty string and the passive flag has been
  424. * specified, the resolved endpoints are suitable for local service binding.
  425. * If an empty string and passive is not specified, the resolved endpoints
  426. * will use the loopback address.
  427. *
  428. * @param service A string identifying the requested service. This may be a
  429. * descriptive name or a numeric string corresponding to a port number. May
  430. * be an empty string, in which case all resolved endpoints will have a port
  431. * number of 0.
  432. *
  433. * @param resolve_flags A set of flags that determine how name resolution
  434. * should be performed. The default flags are suitable for communication with
  435. * remote hosts.
  436. *
  437. * @param ec Set to indicate what error occurred, if any.
  438. *
  439. * @returns A range object representing the list of endpoint entries. An
  440. * empty range is returned if an error occurs. A successful call to this
  441. * function is guaranteed to return a non-empty range.
  442. *
  443. * @note On POSIX systems, host names may be locally defined in the file
  444. * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
  445. * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
  446. * resolution is performed using DNS. Operating systems may use additional
  447. * locations when resolving host names (such as NETBIOS names on Windows).
  448. *
  449. * On POSIX systems, service names are typically defined in the file
  450. * <tt>/etc/services</tt>. On Windows, service names may be found in the file
  451. * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
  452. * may use additional locations when resolving service names.
  453. */
  454. results_type resolve(const protocol_type& protocol, const std::string& host,
  455. const std::string& service, resolver_base::flags resolve_flags,
  456. asio::error_code& ec)
  457. {
  458. basic_resolver_query<protocol_type> q(
  459. protocol, host, service, resolve_flags);
  460. return this->get_service().resolve(this->get_implementation(), q, ec);
  461. }
  462. #if !defined(ASIO_NO_DEPRECATED)
  463. /// (Deprecated.) Asynchronously perform forward resolution of a query to a
  464. /// list of entries.
  465. /**
  466. * This function is used to asynchronously resolve a query into a list of
  467. * endpoint entries.
  468. *
  469. * @param q A query object that determines what endpoints will be returned.
  470. *
  471. * @param handler The handler to be called when the resolve operation
  472. * completes. Copies will be made of the handler as required. The function
  473. * signature of the handler must be:
  474. * @code void handler(
  475. * const asio::error_code& error, // Result of operation.
  476. * resolver::results_type results // Resolved endpoints as a range.
  477. * ); @endcode
  478. * Regardless of whether the asynchronous operation completes immediately or
  479. * not, the handler will not be invoked from within this function. Invocation
  480. * of the handler will be performed in a manner equivalent to using
  481. * asio::io_context::post().
  482. *
  483. * A successful resolve operation is guaranteed to pass a non-empty range to
  484. * the handler.
  485. */
  486. template <typename ResolveHandler>
  487. ASIO_INITFN_RESULT_TYPE(ResolveHandler,
  488. void (asio::error_code, results_type))
  489. async_resolve(const query& q,
  490. ASIO_MOVE_ARG(ResolveHandler) handler)
  491. {
  492. // If you get an error on the following line it means that your handler does
  493. // not meet the documented type requirements for a ResolveHandler.
  494. ASIO_RESOLVE_HANDLER_CHECK(
  495. ResolveHandler, handler, results_type) type_check;
  496. return this->get_service().async_resolve(this->get_implementation(), q,
  497. ASIO_MOVE_CAST(ResolveHandler)(handler));
  498. }
  499. #endif // !defined(ASIO_NO_DEPRECATED)
  500. /// Asynchronously perform forward resolution of a query to a list of entries.
  501. /**
  502. * This function is used to resolve host and service names into a list of
  503. * endpoint entries.
  504. *
  505. * @param host A string identifying a location. May be a descriptive name or
  506. * a numeric address string. If an empty string and the passive flag has been
  507. * specified, the resolved endpoints are suitable for local service binding.
  508. * If an empty string and passive is not specified, the resolved endpoints
  509. * will use the loopback address.
  510. *
  511. * @param service A string identifying the requested service. This may be a
  512. * descriptive name or a numeric string corresponding to a port number. May
  513. * be an empty string, in which case all resolved endpoints will have a port
  514. * number of 0.
  515. *
  516. * @param handler The handler to be called when the resolve operation
  517. * completes. Copies will be made of the handler as required. The function
  518. * signature of the handler must be:
  519. * @code void handler(
  520. * const asio::error_code& error, // Result of operation.
  521. * resolver::results_type results // Resolved endpoints as a range.
  522. * ); @endcode
  523. * Regardless of whether the asynchronous operation completes immediately or
  524. * not, the handler will not be invoked from within this function. Invocation
  525. * of the handler will be performed in a manner equivalent to using
  526. * asio::io_context::post().
  527. *
  528. * A successful resolve operation is guaranteed to pass a non-empty range to
  529. * the handler.
  530. *
  531. * @note On POSIX systems, host names may be locally defined in the file
  532. * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
  533. * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
  534. * resolution is performed using DNS. Operating systems may use additional
  535. * locations when resolving host names (such as NETBIOS names on Windows).
  536. *
  537. * On POSIX systems, service names are typically defined in the file
  538. * <tt>/etc/services</tt>. On Windows, service names may be found in the file
  539. * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
  540. * may use additional locations when resolving service names.
  541. */
  542. template <typename ResolveHandler>
  543. ASIO_INITFN_RESULT_TYPE(ResolveHandler,
  544. void (asio::error_code, results_type))
  545. async_resolve(const std::string& host, const std::string& service,
  546. ASIO_MOVE_ARG(ResolveHandler) handler)
  547. {
  548. return async_resolve(host, service, resolver_base::flags(),
  549. ASIO_MOVE_CAST(ResolveHandler)(handler));
  550. }
  551. /// Asynchronously perform forward resolution of a query to a list of entries.
  552. /**
  553. * This function is used to resolve host and service names into a list of
  554. * endpoint entries.
  555. *
  556. * @param host A string identifying a location. May be a descriptive name or
  557. * a numeric address string. If an empty string and the passive flag has been
  558. * specified, the resolved endpoints are suitable for local service binding.
  559. * If an empty string and passive is not specified, the resolved endpoints
  560. * will use the loopback address.
  561. *
  562. * @param service A string identifying the requested service. This may be a
  563. * descriptive name or a numeric string corresponding to a port number. May
  564. * be an empty string, in which case all resolved endpoints will have a port
  565. * number of 0.
  566. *
  567. * @param resolve_flags A set of flags that determine how name resolution
  568. * should be performed. The default flags are suitable for communication with
  569. * remote hosts.
  570. *
  571. * @param handler The handler to be called when the resolve operation
  572. * completes. Copies will be made of the handler as required. The function
  573. * signature of the handler must be:
  574. * @code void handler(
  575. * const asio::error_code& error, // Result of operation.
  576. * resolver::results_type results // Resolved endpoints as a range.
  577. * ); @endcode
  578. * Regardless of whether the asynchronous operation completes immediately or
  579. * not, the handler will not be invoked from within this function. Invocation
  580. * of the handler will be performed in a manner equivalent to using
  581. * asio::io_context::post().
  582. *
  583. * A successful resolve operation is guaranteed to pass a non-empty range to
  584. * the handler.
  585. *
  586. * @note On POSIX systems, host names may be locally defined in the file
  587. * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
  588. * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
  589. * resolution is performed using DNS. Operating systems may use additional
  590. * locations when resolving host names (such as NETBIOS names on Windows).
  591. *
  592. * On POSIX systems, service names are typically defined in the file
  593. * <tt>/etc/services</tt>. On Windows, service names may be found in the file
  594. * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
  595. * may use additional locations when resolving service names.
  596. */
  597. template <typename ResolveHandler>
  598. ASIO_INITFN_RESULT_TYPE(ResolveHandler,
  599. void (asio::error_code, results_type))
  600. async_resolve(const std::string& host, const std::string& service,
  601. resolver_base::flags resolve_flags,
  602. ASIO_MOVE_ARG(ResolveHandler) handler)
  603. {
  604. // If you get an error on the following line it means that your handler does
  605. // not meet the documented type requirements for a ResolveHandler.
  606. ASIO_RESOLVE_HANDLER_CHECK(
  607. ResolveHandler, handler, results_type) type_check;
  608. basic_resolver_query<protocol_type> q(host, service, resolve_flags);
  609. return this->get_service().async_resolve(this->get_implementation(), q,
  610. ASIO_MOVE_CAST(ResolveHandler)(handler));
  611. }
  612. /// Asynchronously perform forward resolution of a query to a list of entries.
  613. /**
  614. * This function is used to resolve host and service names into a list of
  615. * endpoint entries.
  616. *
  617. * @param protocol A protocol object, normally representing either the IPv4 or
  618. * IPv6 version of an internet protocol.
  619. *
  620. * @param host A string identifying a location. May be a descriptive name or
  621. * a numeric address string. If an empty string and the passive flag has been
  622. * specified, the resolved endpoints are suitable for local service binding.
  623. * If an empty string and passive is not specified, the resolved endpoints
  624. * will use the loopback address.
  625. *
  626. * @param service A string identifying the requested service. This may be a
  627. * descriptive name or a numeric string corresponding to a port number. May
  628. * be an empty string, in which case all resolved endpoints will have a port
  629. * number of 0.
  630. *
  631. * @param handler The handler to be called when the resolve operation
  632. * completes. Copies will be made of the handler as required. The function
  633. * signature of the handler must be:
  634. * @code void handler(
  635. * const asio::error_code& error, // Result of operation.
  636. * resolver::results_type results // Resolved endpoints as a range.
  637. * ); @endcode
  638. * Regardless of whether the asynchronous operation completes immediately or
  639. * not, the handler will not be invoked from within this function. Invocation
  640. * of the handler will be performed in a manner equivalent to using
  641. * asio::io_context::post().
  642. *
  643. * A successful resolve operation is guaranteed to pass a non-empty range to
  644. * the handler.
  645. *
  646. * @note On POSIX systems, host names may be locally defined in the file
  647. * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
  648. * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
  649. * resolution is performed using DNS. Operating systems may use additional
  650. * locations when resolving host names (such as NETBIOS names on Windows).
  651. *
  652. * On POSIX systems, service names are typically defined in the file
  653. * <tt>/etc/services</tt>. On Windows, service names may be found in the file
  654. * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
  655. * may use additional locations when resolving service names.
  656. */
  657. template <typename ResolveHandler>
  658. ASIO_INITFN_RESULT_TYPE(ResolveHandler,
  659. void (asio::error_code, results_type))
  660. async_resolve(const protocol_type& protocol, const std::string& host,
  661. const std::string& service, ASIO_MOVE_ARG(ResolveHandler) handler)
  662. {
  663. return async_resolve(protocol, host, service, resolver_base::flags(),
  664. ASIO_MOVE_CAST(ResolveHandler)(handler));
  665. }
  666. /// Asynchronously perform forward resolution of a query to a list of entries.
  667. /**
  668. * This function is used to resolve host and service names into a list of
  669. * endpoint entries.
  670. *
  671. * @param protocol A protocol object, normally representing either the IPv4 or
  672. * IPv6 version of an internet protocol.
  673. *
  674. * @param host A string identifying a location. May be a descriptive name or
  675. * a numeric address string. If an empty string and the passive flag has been
  676. * specified, the resolved endpoints are suitable for local service binding.
  677. * If an empty string and passive is not specified, the resolved endpoints
  678. * will use the loopback address.
  679. *
  680. * @param service A string identifying the requested service. This may be a
  681. * descriptive name or a numeric string corresponding to a port number. May
  682. * be an empty string, in which case all resolved endpoints will have a port
  683. * number of 0.
  684. *
  685. * @param resolve_flags A set of flags that determine how name resolution
  686. * should be performed. The default flags are suitable for communication with
  687. * remote hosts.
  688. *
  689. * @param handler The handler to be called when the resolve operation
  690. * completes. Copies will be made of the handler as required. The function
  691. * signature of the handler must be:
  692. * @code void handler(
  693. * const asio::error_code& error, // Result of operation.
  694. * resolver::results_type results // Resolved endpoints as a range.
  695. * ); @endcode
  696. * Regardless of whether the asynchronous operation completes immediately or
  697. * not, the handler will not be invoked from within this function. Invocation
  698. * of the handler will be performed in a manner equivalent to using
  699. * asio::io_context::post().
  700. *
  701. * A successful resolve operation is guaranteed to pass a non-empty range to
  702. * the handler.
  703. *
  704. * @note On POSIX systems, host names may be locally defined in the file
  705. * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
  706. * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
  707. * resolution is performed using DNS. Operating systems may use additional
  708. * locations when resolving host names (such as NETBIOS names on Windows).
  709. *
  710. * On POSIX systems, service names are typically defined in the file
  711. * <tt>/etc/services</tt>. On Windows, service names may be found in the file
  712. * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
  713. * may use additional locations when resolving service names.
  714. */
  715. template <typename ResolveHandler>
  716. ASIO_INITFN_RESULT_TYPE(ResolveHandler,
  717. void (asio::error_code, results_type))
  718. async_resolve(const protocol_type& protocol, const std::string& host,
  719. const std::string& service, resolver_base::flags resolve_flags,
  720. ASIO_MOVE_ARG(ResolveHandler) handler)
  721. {
  722. // If you get an error on the following line it means that your handler does
  723. // not meet the documented type requirements for a ResolveHandler.
  724. ASIO_RESOLVE_HANDLER_CHECK(
  725. ResolveHandler, handler, results_type) type_check;
  726. basic_resolver_query<protocol_type> q(
  727. protocol, host, service, resolve_flags);
  728. return this->get_service().async_resolve(this->get_implementation(), q,
  729. ASIO_MOVE_CAST(ResolveHandler)(handler));
  730. }
  731. /// Perform reverse resolution of an endpoint to a list of entries.
  732. /**
  733. * This function is used to resolve an endpoint into a list of endpoint
  734. * entries.
  735. *
  736. * @param e An endpoint object that determines what endpoints will be
  737. * returned.
  738. *
  739. * @returns A range object representing the list of endpoint entries. A
  740. * successful call to this function is guaranteed to return a non-empty
  741. * range.
  742. *
  743. * @throws asio::system_error Thrown on failure.
  744. */
  745. results_type resolve(const endpoint_type& e)
  746. {
  747. asio::error_code ec;
  748. results_type i = this->get_service().resolve(
  749. this->get_implementation(), e, ec);
  750. asio::detail::throw_error(ec, "resolve");
  751. return i;
  752. }
  753. /// Perform reverse resolution of an endpoint to a list of entries.
  754. /**
  755. * This function is used to resolve an endpoint into a list of endpoint
  756. * entries.
  757. *
  758. * @param e An endpoint object that determines what endpoints will be
  759. * returned.
  760. *
  761. * @param ec Set to indicate what error occurred, if any.
  762. *
  763. * @returns A range object representing the list of endpoint entries. An
  764. * empty range is returned if an error occurs. A successful call to this
  765. * function is guaranteed to return a non-empty range.
  766. */
  767. results_type resolve(const endpoint_type& e, asio::error_code& ec)
  768. {
  769. return this->get_service().resolve(this->get_implementation(), e, ec);
  770. }
  771. /// Asynchronously perform reverse resolution of an endpoint to a list of
  772. /// entries.
  773. /**
  774. * This function is used to asynchronously resolve an endpoint into a list of
  775. * endpoint entries.
  776. *
  777. * @param e An endpoint object that determines what endpoints will be
  778. * returned.
  779. *
  780. * @param handler The handler to be called when the resolve operation
  781. * completes. Copies will be made of the handler as required. The function
  782. * signature of the handler must be:
  783. * @code void handler(
  784. * const asio::error_code& error, // Result of operation.
  785. * resolver::results_type results // Resolved endpoints as a range.
  786. * ); @endcode
  787. * Regardless of whether the asynchronous operation completes immediately or
  788. * not, the handler will not be invoked from within this function. Invocation
  789. * of the handler will be performed in a manner equivalent to using
  790. * asio::io_context::post().
  791. *
  792. * A successful resolve operation is guaranteed to pass a non-empty range to
  793. * the handler.
  794. */
  795. template <typename ResolveHandler>
  796. ASIO_INITFN_RESULT_TYPE(ResolveHandler,
  797. void (asio::error_code, results_type))
  798. async_resolve(const endpoint_type& e,
  799. ASIO_MOVE_ARG(ResolveHandler) handler)
  800. {
  801. // If you get an error on the following line it means that your handler does
  802. // not meet the documented type requirements for a ResolveHandler.
  803. ASIO_RESOLVE_HANDLER_CHECK(
  804. ResolveHandler, handler, results_type) type_check;
  805. return this->get_service().async_resolve(this->get_implementation(), e,
  806. ASIO_MOVE_CAST(ResolveHandler)(handler));
  807. }
  808. };
  809. } // namespace ip
  810. } // namespace asio
  811. #include "asio/detail/pop_options.hpp"
  812. #endif // ASIO_IP_BASIC_RESOLVER_HPP