boost/asio/ip/basic_resolver.hpp

   1 //
   2 // ip/basic_resolver.hpp
   3 // ~~~~~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   6 //
   7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
   8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   9 //
  10
  11 #ifndef BOOST_ASIO_IP_BASIC_RESOLVER_HPP
  12 #define BOOST_ASIO_IP_BASIC_RESOLVER_HPP
  13
  14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  15 # pragma once
  16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  17
  18 #include <boost/asio/detail/config.hpp>
  19 #include <string>
  20 #include <boost/asio/async_result.hpp>
  21 #include <boost/asio/detail/handler_type_requirements.hpp>
  22 #include <boost/asio/detail/io_object_impl.hpp>
  23 #include <boost/asio/detail/non_const_lvalue.hpp>
  24 #include <boost/asio/detail/string_view.hpp>
  25 #include <boost/asio/detail/throw_error.hpp>
  26 #include <boost/asio/error.hpp>
  27 #include <boost/asio/execution_context.hpp>
  28 #include <boost/asio/executor.hpp>
  29 #include <boost/asio/ip/basic_resolver_iterator.hpp>
  30 #include <boost/asio/ip/basic_resolver_query.hpp>
  31 #include <boost/asio/ip/basic_resolver_results.hpp>
  32 #include <boost/asio/ip/resolver_base.hpp>
  33 #if defined(BOOST_ASIO_WINDOWS_RUNTIME)
  34 # include <boost/asio/detail/winrt_resolver_service.hpp>
  35 #else
  36 # include <boost/asio/detail/resolver_service.hpp>
  37 #endif
  38
  39 #if defined(BOOST_ASIO_HAS_MOVE)
  40 # include <utility>
  41 #endif // defined(BOOST_ASIO_HAS_MOVE)
  42
  43 #include <boost/asio/detail/push_options.hpp>
  44
  45 namespace boost {
  46 namespace asio {
  47 namespace ip {
  48
  49 #if !defined(BOOST_ASIO_IP_BASIC_RESOLVER_FWD_DECL)
  50 #define BOOST_ASIO_IP_BASIC_RESOLVER_FWD_DECL
  51
  52 // Forward declaration with defaulted arguments.
  53 template <typename InternetProtocol, typename Executor = executor>
  54 class basic_resolver;
  55
  56 #endif // !defined(BOOST_ASIO_IP_BASIC_RESOLVER_FWD_DECL)
  57
  58 /// Provides endpoint resolution functionality.
  59 /**
  60  * The basic_resolver class template provides the ability to resolve a query
  61  * to a list of endpoints.
  62  *
  63  * @par Thread Safety
  64  * @e Distinct @e objects: Safe.@n
  65  * @e Shared @e objects: Unsafe.
  66  */
  67 template <typename InternetProtocol, typename Executor>
  68 class basic_resolver
  69   : public resolver_base
  70 {
  71 public:
  72   /// The type of the executor associated with the object.
  73   typedef Executor executor_type;
  74
  75   /// Rebinds the resolver type to another executor.
  76   template <typename Executor1>
  77   struct rebind_executor
  78   {
  79     /// The resolver type when rebound to the specified executor.
  80     typedef basic_resolver<InternetProtocol, Executor1> other;
  81   };
  82
  83   /// The protocol type.
  84   typedef InternetProtocol protocol_type;
  85
  86   /// The endpoint type.
  87   typedef typename InternetProtocol::endpoint endpoint_type;
  88
  89 #if !defined(BOOST_ASIO_NO_DEPRECATED)
  90   /// (Deprecated.) The query type.
  91   typedef basic_resolver_query<InternetProtocol> query;
  92
  93   /// (Deprecated.) The iterator type.
  94   typedef basic_resolver_iterator<InternetProtocol> iterator;
  95 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
  96
  97   /// The results type.
  98   typedef basic_resolver_results<InternetProtocol> results_type;
  99
 100   /// Construct with executor.
 101   /**
 102    * This constructor creates a basic_resolver.
 103    *
 104    * @param ex The I/O executor that the resolver will use, by default, to
 105    * dispatch handlers for any asynchronous operations performed on the
 106    * resolver.
 107    */
 108   explicit basic_resolver(const executor_type& ex)
 109     : impl_(ex)
 110   {
 111   }
 112
 113   /// Construct with execution context.
 114   /**
 115    * This constructor creates a basic_resolver.
 116    *
 117    * @param context An execution context which provides the I/O executor that
 118    * the resolver will use, by default, to dispatch handlers for any
 119    * asynchronous operations performed on the resolver.
 120    */
 121   template <typename ExecutionContext>
 122   explicit basic_resolver(ExecutionContext& context,
 123       typename enable_if<
 124         is_convertible<ExecutionContext&, execution_context&>::value
 125       >::type* = 0)
 126     : impl_(context)
 127   {
 128   }
 129
 130 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 131   /// Move-construct a basic_resolver from another.
 132   /**
 133    * This constructor moves a resolver from one object to another.
 134    *
 135    * @param other The other basic_resolver object from which the move will
 136    * occur.
 137    *
 138    * @note Following the move, the moved-from object is in the same state as if
 139    * constructed using the @c basic_resolver(const executor_type&) constructor.
 140    */
 141   basic_resolver(basic_resolver&& other)
 142     : impl_(std::move(other.impl_))
 143   {
 144   }
 145
 146   /// Move-assign a basic_resolver from another.
 147   /**
 148    * This assignment operator moves a resolver from one object to another.
 149    * Cancels any outstanding asynchronous operations associated with the target
 150    * object.
 151    *
 152    * @param other The other basic_resolver object from which the move will
 153    * occur.
 154    *
 155    * @note Following the move, the moved-from object is in the same state as if
 156    * constructed using the @c basic_resolver(const executor_type&) constructor.
 157    */
 158   basic_resolver& operator=(basic_resolver&& other)
 159   {
 160     impl_ = std::move(other.impl_);
 161     return *this;
 162   }
 163 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
 164
 165   /// Destroys the resolver.
 166   /**
 167    * This function destroys the resolver, cancelling any outstanding
 168    * asynchronous wait operations associated with the resolver as if by calling
 169    * @c cancel.
 170    */
 171   ~basic_resolver()
 172   {
 173   }
 174
 175   /// Get the executor associated with the object.
 176   executor_type get_executor() BOOST_ASIO_NOEXCEPT
 177   {
 178     return impl_.get_executor();
 179   }
 180
 181   /// Cancel any asynchronous operations that are waiting on the resolver.
 182   /**
 183    * This function forces the completion of any pending asynchronous
 184    * operations on the host resolver. The handler for each cancelled operation
 185    * will be invoked with the boost::asio::error::operation_aborted error code.
 186    */
 187   void cancel()
 188   {
 189     return impl_.get_service().cancel(impl_.get_implementation());
 190   }
 191
 192 #if !defined(BOOST_ASIO_NO_DEPRECATED)
 193   /// (Deprecated: Use overload with separate host and service parameters.)
 194   /// Perform forward resolution of a query to a list of entries.
 195   /**
 196    * This function is used to resolve a query into a list of endpoint entries.
 197    *
 198    * @param q A query object that determines what endpoints will be returned.
 199    *
 200    * @returns A range object representing the list of endpoint entries. A
 201    * successful call to this function is guaranteed to return a non-empty
 202    * range.
 203    *
 204    * @throws boost::system::system_error Thrown on failure.
 205    */
 206   results_type resolve(const query& q)
 207   {
 208     boost::system::error_code ec;
 209     results_type r = impl_.get_service().resolve(
 210         impl_.get_implementation(), q, ec);
 211     boost::asio::detail::throw_error(ec, "resolve");
 212     return r;
 213   }
 214
 215   /// (Deprecated: Use overload with separate host and service parameters.)
 216   /// Perform forward resolution of a query to a list of entries.
 217   /**
 218    * This function is used to resolve a query into a list of endpoint entries.
 219    *
 220    * @param q A query object that determines what endpoints will be returned.
 221    *
 222    * @param ec Set to indicate what error occurred, if any.
 223    *
 224    * @returns A range object representing the list of endpoint entries. An
 225    * empty range is returned if an error occurs. A successful call to this
 226    * function is guaranteed to return a non-empty range.
 227    */
 228   results_type resolve(const query& q, boost::system::error_code& ec)
 229   {
 230     return impl_.get_service().resolve(impl_.get_implementation(), q, ec);
 231   }
 232 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
 233
 234   /// Perform forward resolution of a query to a list of entries.
 235   /**
 236    * This function is used to resolve host and service names into a list of
 237    * endpoint entries.
 238    *
 239    * @param host A string identifying a location. May be a descriptive name or
 240    * a numeric address string. If an empty string and the passive flag has been
 241    * specified, the resolved endpoints are suitable for local service binding.
 242    * If an empty string and passive is not specified, the resolved endpoints
 243    * will use the loopback address.
 244    *
 245    * @param service A string identifying the requested service. This may be a
 246    * descriptive name or a numeric string corresponding to a port number. May
 247    * be an empty string, in which case all resolved endpoints will have a port
 248    * number of 0.
 249    *
 250    * @returns A range object representing the list of endpoint entries. A
 251    * successful call to this function is guaranteed to return a non-empty
 252    * range.
 253    *
 254    * @throws boost::system::system_error Thrown on failure.
 255    *
 256    * @note On POSIX systems, host names may be locally defined in the file
 257    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
 258    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
 259    * resolution is performed using DNS. Operating systems may use additional
 260    * locations when resolving host names (such as NETBIOS names on Windows).
 261    *
 262    * On POSIX systems, service names are typically defined in the file
 263    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
 264    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
 265    * may use additional locations when resolving service names.
 266    */
 267   results_type resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
 268       BOOST_ASIO_STRING_VIEW_PARAM service)
 269   {
 270     return resolve(host, service, resolver_base::flags());
 271   }
 272
 273   /// Perform forward resolution of a query to a list of entries.
 274   /**
 275    * This function is used to resolve host and service names into a list of
 276    * endpoint entries.
 277    *
 278    * @param host A string identifying a location. May be a descriptive name or
 279    * a numeric address string. If an empty string and the passive flag has been
 280    * specified, the resolved endpoints are suitable for local service binding.
 281    * If an empty string and passive is not specified, the resolved endpoints
 282    * will use the loopback address.
 283    *
 284    * @param service A string identifying the requested service. This may be a
 285    * descriptive name or a numeric string corresponding to a port number. May
 286    * be an empty string, in which case all resolved endpoints will have a port
 287    * number of 0.
 288    *
 289    * @param ec Set to indicate what error occurred, if any.
 290    *
 291    * @returns A range object representing the list of endpoint entries. An
 292    * empty range is returned if an error occurs. A successful call to this
 293    * function is guaranteed to return a non-empty range.
 294    *
 295    * @note On POSIX systems, host names may be locally defined in the file
 296    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
 297    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
 298    * resolution is performed using DNS. Operating systems may use additional
 299    * locations when resolving host names (such as NETBIOS names on Windows).
 300    *
 301    * On POSIX systems, service names are typically defined in the file
 302    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
 303    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
 304    * may use additional locations when resolving service names.
 305    */
 306   results_type resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
 307       BOOST_ASIO_STRING_VIEW_PARAM service, boost::system::error_code& ec)
 308   {
 309     return resolve(host, service, resolver_base::flags(), ec);
 310   }
 311
 312   /// Perform forward resolution of a query to a list of entries.
 313   /**
 314    * This function is used to resolve host and service names into a list of
 315    * endpoint entries.
 316    *
 317    * @param host A string identifying a location. May be a descriptive name or
 318    * a numeric address string. If an empty string and the passive flag has been
 319    * specified, the resolved endpoints are suitable for local service binding.
 320    * If an empty string and passive is not specified, the resolved endpoints
 321    * will use the loopback address.
 322    *
 323    * @param service A string identifying the requested service. This may be a
 324    * descriptive name or a numeric string corresponding to a port number. May
 325    * be an empty string, in which case all resolved endpoints will have a port
 326    * number of 0.
 327    *
 328    * @param resolve_flags A set of flags that determine how name resolution
 329    * should be performed. The default flags are suitable for communication with
 330    * remote hosts. See the @ref resolver_base documentation for the set of
 331    * available flags.
 332    *
 333    * @returns A range object representing the list of endpoint entries. A
 334    * successful call to this function is guaranteed to return a non-empty
 335    * range.
 336    *
 337    * @throws boost::system::system_error Thrown on failure.
 338    *
 339    * @note On POSIX systems, host names may be locally defined in the file
 340    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
 341    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
 342    * resolution is performed using DNS. Operating systems may use additional
 343    * locations when resolving host names (such as NETBIOS names on Windows).
 344    *
 345    * On POSIX systems, service names are typically defined in the file
 346    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
 347    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
 348    * may use additional locations when resolving service names.
 349    */
 350   results_type resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
 351       BOOST_ASIO_STRING_VIEW_PARAM service, resolver_base::flags resolve_flags)
 352   {
 353     boost::system::error_code ec;
 354     basic_resolver_query<protocol_type> q(static_cast<std::string>(host),
 355         static_cast<std::string>(service), resolve_flags);
 356     results_type r = impl_.get_service().resolve(
 357         impl_.get_implementation(), q, ec);
 358     boost::asio::detail::throw_error(ec, "resolve");
 359     return r;
 360   }
 361
 362   /// Perform forward resolution of a query to a list of entries.
 363   /**
 364    * This function is used to resolve host and service names into a list of
 365    * endpoint entries.
 366    *
 367    * @param host A string identifying a location. May be a descriptive name or
 368    * a numeric address string. If an empty string and the passive flag has been
 369    * specified, the resolved endpoints are suitable for local service binding.
 370    * If an empty string and passive is not specified, the resolved endpoints
 371    * will use the loopback address.
 372    *
 373    * @param service A string identifying the requested service. This may be a
 374    * descriptive name or a numeric string corresponding to a port number. May
 375    * be an empty string, in which case all resolved endpoints will have a port
 376    * number of 0.
 377    *
 378    * @param resolve_flags A set of flags that determine how name resolution
 379    * should be performed. The default flags are suitable for communication with
 380    * remote hosts. See the @ref resolver_base documentation for the set of
 381    * available flags.
 382    *
 383    * @param ec Set to indicate what error occurred, if any.
 384    *
 385    * @returns A range object representing the list of endpoint entries. An
 386    * empty range is returned if an error occurs. A successful call to this
 387    * function is guaranteed to return a non-empty range.
 388    *
 389    * @note On POSIX systems, host names may be locally defined in the file
 390    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
 391    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
 392    * resolution is performed using DNS. Operating systems may use additional
 393    * locations when resolving host names (such as NETBIOS names on Windows).
 394    *
 395    * On POSIX systems, service names are typically defined in the file
 396    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
 397    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
 398    * may use additional locations when resolving service names.
 399    */
 400   results_type resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
 401       BOOST_ASIO_STRING_VIEW_PARAM service, resolver_base::flags resolve_flags,
 402       boost::system::error_code& ec)
 403   {
 404     basic_resolver_query<protocol_type> q(static_cast<std::string>(host),
 405         static_cast<std::string>(service), resolve_flags);
 406     return impl_.get_service().resolve(impl_.get_implementation(), q, ec);
 407   }
 408
 409   /// Perform forward resolution of a query to a list of entries.
 410   /**
 411    * This function is used to resolve host and service names into a list of
 412    * endpoint entries.
 413    *
 414    * @param protocol A protocol object, normally representing either the IPv4 or
 415    * IPv6 version of an internet protocol.
 416    *
 417    * @param host A string identifying a location. May be a descriptive name or
 418    * a numeric address string. If an empty string and the passive flag has been
 419    * specified, the resolved endpoints are suitable for local service binding.
 420    * If an empty string and passive is not specified, the resolved endpoints
 421    * will use the loopback address.
 422    *
 423    * @param service A string identifying the requested service. This may be a
 424    * descriptive name or a numeric string corresponding to a port number. May
 425    * be an empty string, in which case all resolved endpoints will have a port
 426    * number of 0.
 427    *
 428    * @returns A range object representing the list of endpoint entries. A
 429    * successful call to this function is guaranteed to return a non-empty
 430    * range.
 431    *
 432    * @throws boost::system::system_error Thrown on failure.
 433    *
 434    * @note On POSIX systems, host names may be locally defined in the file
 435    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
 436    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
 437    * resolution is performed using DNS. Operating systems may use additional
 438    * locations when resolving host names (such as NETBIOS names on Windows).
 439    *
 440    * On POSIX systems, service names are typically defined in the file
 441    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
 442    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
 443    * may use additional locations when resolving service names.
 444    */
 445   results_type resolve(const protocol_type& protocol,
 446       BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service)
 447   {
 448     return resolve(protocol, host, service, resolver_base::flags());
 449   }
 450
 451   /// Perform forward resolution of a query to a list of entries.
 452   /**
 453    * This function is used to resolve host and service names into a list of
 454    * endpoint entries.
 455    *
 456    * @param protocol A protocol object, normally representing either the IPv4 or
 457    * IPv6 version of an internet protocol.
 458    *
 459    * @param host A string identifying a location. May be a descriptive name or
 460    * a numeric address string. If an empty string and the passive flag has been
 461    * specified, the resolved endpoints are suitable for local service binding.
 462    * If an empty string and passive is not specified, the resolved endpoints
 463    * will use the loopback address.
 464    *
 465    * @param service A string identifying the requested service. This may be a
 466    * descriptive name or a numeric string corresponding to a port number. May
 467    * be an empty string, in which case all resolved endpoints will have a port
 468    * number of 0.
 469    *
 470    * @param ec Set to indicate what error occurred, if any.
 471    *
 472    * @returns A range object representing the list of endpoint entries. An
 473    * empty range is returned if an error occurs. A successful call to this
 474    * function is guaranteed to return a non-empty range.
 475    *
 476    * @note On POSIX systems, host names may be locally defined in the file
 477    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
 478    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
 479    * resolution is performed using DNS. Operating systems may use additional
 480    * locations when resolving host names (such as NETBIOS names on Windows).
 481    *
 482    * On POSIX systems, service names are typically defined in the file
 483    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
 484    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
 485    * may use additional locations when resolving service names.
 486    */
 487   results_type resolve(const protocol_type& protocol,
 488       BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
 489       boost::system::error_code& ec)
 490   {
 491     return resolve(protocol, host, service, resolver_base::flags(), ec);
 492   }
 493
 494   /// Perform forward resolution of a query to a list of entries.
 495   /**
 496    * This function is used to resolve host and service names into a list of
 497    * endpoint entries.
 498    *
 499    * @param protocol A protocol object, normally representing either the IPv4 or
 500    * IPv6 version of an internet protocol.
 501    *
 502    * @param host A string identifying a location. May be a descriptive name or
 503    * a numeric address string. If an empty string and the passive flag has been
 504    * specified, the resolved endpoints are suitable for local service binding.
 505    * If an empty string and passive is not specified, the resolved endpoints
 506    * will use the loopback address.
 507    *
 508    * @param service A string identifying the requested service. This may be a
 509    * descriptive name or a numeric string corresponding to a port number. May
 510    * be an empty string, in which case all resolved endpoints will have a port
 511    * number of 0.
 512    *
 513    * @param resolve_flags A set of flags that determine how name resolution
 514    * should be performed. The default flags are suitable for communication with
 515    * remote hosts. See the @ref resolver_base documentation for the set of
 516    * available flags.
 517    *
 518    * @returns A range object representing the list of endpoint entries. A
 519    * successful call to this function is guaranteed to return a non-empty
 520    * range.
 521    *
 522    * @throws boost::system::system_error Thrown on failure.
 523    *
 524    * @note On POSIX systems, host names may be locally defined in the file
 525    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
 526    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
 527    * resolution is performed using DNS. Operating systems may use additional
 528    * locations when resolving host names (such as NETBIOS names on Windows).
 529    *
 530    * On POSIX systems, service names are typically defined in the file
 531    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
 532    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
 533    * may use additional locations when resolving service names.
 534    */
 535   results_type resolve(const protocol_type& protocol,
 536       BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
 537       resolver_base::flags resolve_flags)
 538   {
 539     boost::system::error_code ec;
 540     basic_resolver_query<protocol_type> q(
 541         protocol, static_cast<std::string>(host),
 542         static_cast<std::string>(service), resolve_flags);
 543     results_type r = impl_.get_service().resolve(
 544         impl_.get_implementation(), q, ec);
 545     boost::asio::detail::throw_error(ec, "resolve");
 546     return r;
 547   }
 548
 549   /// Perform forward resolution of a query to a list of entries.
 550   /**
 551    * This function is used to resolve host and service names into a list of
 552    * endpoint entries.
 553    *
 554    * @param protocol A protocol object, normally representing either the IPv4 or
 555    * IPv6 version of an internet protocol.
 556    *
 557    * @param host A string identifying a location. May be a descriptive name or
 558    * a numeric address string. If an empty string and the passive flag has been
 559    * specified, the resolved endpoints are suitable for local service binding.
 560    * If an empty string and passive is not specified, the resolved endpoints
 561    * will use the loopback address.
 562    *
 563    * @param service A string identifying the requested service. This may be a
 564    * descriptive name or a numeric string corresponding to a port number. May
 565    * be an empty string, in which case all resolved endpoints will have a port
 566    * number of 0.
 567    *
 568    * @param resolve_flags A set of flags that determine how name resolution
 569    * should be performed. The default flags are suitable for communication with
 570    * remote hosts. See the @ref resolver_base documentation for the set of
 571    * available flags.
 572    *
 573    * @param ec Set to indicate what error occurred, if any.
 574    *
 575    * @returns A range object representing the list of endpoint entries. An
 576    * empty range is returned if an error occurs. A successful call to this
 577    * function is guaranteed to return a non-empty range.
 578    *
 579    * @note On POSIX systems, host names may be locally defined in the file
 580    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
 581    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
 582    * resolution is performed using DNS. Operating systems may use additional
 583    * locations when resolving host names (such as NETBIOS names on Windows).
 584    *
 585    * On POSIX systems, service names are typically defined in the file
 586    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
 587    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
 588    * may use additional locations when resolving service names.
 589    */
 590   results_type resolve(const protocol_type& protocol,
 591       BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
 592       resolver_base::flags resolve_flags, boost::system::error_code& ec)
 593   {
 594     basic_resolver_query<protocol_type> q(
 595         protocol, static_cast<std::string>(host),
 596         static_cast<std::string>(service), resolve_flags);
 597     return impl_.get_service().resolve(impl_.get_implementation(), q, ec);
 598   }
 599
 600 #if !defined(BOOST_ASIO_NO_DEPRECATED)
 601   /// (Deprecated: Use overload with separate host and service parameters.)
 602   /// Asynchronously perform forward resolution of a query to a list of entries.
 603   /**
 604    * This function is used to asynchronously resolve a query into a list of
 605    * endpoint entries.
 606    *
 607    * @param q A query object that determines what endpoints will be returned.
 608    *
 609    * @param handler The handler to be called when the resolve operation
 610    * completes. Copies will be made of the handler as required. The function
 611    * signature of the handler must be:
 612    * @code void handler(
 613    *   const boost::system::error_code& error, // Result of operation.
 614    *   resolver::results_type results // Resolved endpoints as a range.
 615    * ); @endcode
 616    * Regardless of whether the asynchronous operation completes immediately or
 617    * not, the handler will not be invoked from within this function. On
 618    * immediate completion, invocation of the handler will be performed in a
 619    * manner equivalent to using boost::asio::post().
 620    *
 621    * A successful resolve operation is guaranteed to pass a non-empty range to
 622    * the handler.
 623    */
 624   template <
 625       BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 626         results_type)) ResolveHandler
 627           BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
 628   BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler,
 629       void (boost::system::error_code, results_type))
 630   async_resolve(const query& q,
 631       BOOST_ASIO_MOVE_ARG(ResolveHandler) handler
 632         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
 633   {
 634     return boost::asio::async_initiate<ResolveHandler,
 635       void (boost::system::error_code, results_type)>(
 636         initiate_async_resolve(this), handler, q);
 637   }
 638 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
 639
 640   /// Asynchronously perform forward resolution of a query to a list of entries.
 641   /**
 642    * This function is used to resolve host and service names into a list of
 643    * endpoint entries.
 644    *
 645    * @param host A string identifying a location. May be a descriptive name or
 646    * a numeric address string. If an empty string and the passive flag has been
 647    * specified, the resolved endpoints are suitable for local service binding.
 648    * If an empty string and passive is not specified, the resolved endpoints
 649    * will use the loopback address.
 650    *
 651    * @param service A string identifying the requested service. This may be a
 652    * descriptive name or a numeric string corresponding to a port number. May
 653    * be an empty string, in which case all resolved endpoints will have a port
 654    * number of 0.
 655    *
 656    * @param handler The handler to be called when the resolve operation
 657    * completes. Copies will be made of the handler as required. The function
 658    * signature of the handler must be:
 659    * @code void handler(
 660    *   const boost::system::error_code& error, // Result of operation.
 661    *   resolver::results_type results // Resolved endpoints as a range.
 662    * ); @endcode
 663    * Regardless of whether the asynchronous operation completes immediately or
 664    * not, the handler will not be invoked from within this function. On
 665    * immediate completion, invocation of the handler will be performed in a
 666    * manner equivalent to using boost::asio::post().
 667    *
 668    * A successful resolve operation is guaranteed to pass a non-empty range to
 669    * the handler.
 670    *
 671    * @note On POSIX systems, host names may be locally defined in the file
 672    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
 673    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
 674    * resolution is performed using DNS. Operating systems may use additional
 675    * locations when resolving host names (such as NETBIOS names on Windows).
 676    *
 677    * On POSIX systems, service names are typically defined in the file
 678    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
 679    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
 680    * may use additional locations when resolving service names.
 681    */
 682   template <
 683       BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 684         results_type)) ResolveHandler
 685           BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
 686   BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler,
 687       void (boost::system::error_code, results_type))
 688   async_resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
 689       BOOST_ASIO_STRING_VIEW_PARAM service,
 690       BOOST_ASIO_MOVE_ARG(ResolveHandler) handler
 691         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
 692   {
 693     return async_resolve(host, service, resolver_base::flags(),
 694         BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler));
 695   }
 696
 697   /// Asynchronously perform forward resolution of a query to a list of entries.
 698   /**
 699    * This function is used to resolve host and service names into a list of
 700    * endpoint entries.
 701    *
 702    * @param host A string identifying a location. May be a descriptive name or
 703    * a numeric address string. If an empty string and the passive flag has been
 704    * specified, the resolved endpoints are suitable for local service binding.
 705    * If an empty string and passive is not specified, the resolved endpoints
 706    * will use the loopback address.
 707    *
 708    * @param service A string identifying the requested service. This may be a
 709    * descriptive name or a numeric string corresponding to a port number. May
 710    * be an empty string, in which case all resolved endpoints will have a port
 711    * number of 0.
 712    *
 713    * @param resolve_flags A set of flags that determine how name resolution
 714    * should be performed. The default flags are suitable for communication with
 715    * remote hosts. See the @ref resolver_base documentation for the set of
 716    * available flags.
 717    *
 718    * @param handler The handler to be called when the resolve 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    *   const boost::system::error_code& error, // Result of operation.
 723    *   resolver::results_type results // Resolved endpoints as a range.
 724    * ); @endcode
 725    * Regardless of whether the asynchronous operation completes immediately or
 726    * not, the handler will not be invoked from within this function. On
 727    * immediate completion, invocation of the handler will be performed in a
 728    * manner equivalent to using boost::asio::post().
 729    *
 730    * A successful resolve operation is guaranteed to pass a non-empty range to
 731    * the handler.
 732    *
 733    * @note On POSIX systems, host names may be locally defined in the file
 734    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
 735    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
 736    * resolution is performed using DNS. Operating systems may use additional
 737    * locations when resolving host names (such as NETBIOS names on Windows).
 738    *
 739    * On POSIX systems, service names are typically defined in the file
 740    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
 741    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
 742    * may use additional locations when resolving service names.
 743    */
 744   template <
 745       BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 746         results_type)) ResolveHandler
 747           BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
 748   BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler,
 749       void (boost::system::error_code, results_type))
 750   async_resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
 751       BOOST_ASIO_STRING_VIEW_PARAM service,
 752       resolver_base::flags resolve_flags,
 753       BOOST_ASIO_MOVE_ARG(ResolveHandler) handler
 754         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
 755   {
 756     basic_resolver_query<protocol_type> q(static_cast<std::string>(host),
 757         static_cast<std::string>(service), resolve_flags);
 758
 759     return boost::asio::async_initiate<ResolveHandler,
 760       void (boost::system::error_code, results_type)>(
 761         initiate_async_resolve(this), handler, q);
 762   }
 763
 764   /// Asynchronously perform forward resolution of a query to a list of entries.
 765   /**
 766    * This function is used to resolve host and service names into a list of
 767    * endpoint entries.
 768    *
 769    * @param protocol A protocol object, normally representing either the IPv4 or
 770    * IPv6 version of an internet protocol.
 771    *
 772    * @param host A string identifying a location. May be a descriptive name or
 773    * a numeric address string. If an empty string and the passive flag has been
 774    * specified, the resolved endpoints are suitable for local service binding.
 775    * If an empty string and passive is not specified, the resolved endpoints
 776    * will use the loopback address.
 777    *
 778    * @param service A string identifying the requested service. This may be a
 779    * descriptive name or a numeric string corresponding to a port number. May
 780    * be an empty string, in which case all resolved endpoints will have a port
 781    * number of 0.
 782    *
 783    * @param handler The handler to be called when the resolve operation
 784    * completes. Copies will be made of the handler as required. The function
 785    * signature of the handler must be:
 786    * @code void handler(
 787    *   const boost::system::error_code& error, // Result of operation.
 788    *   resolver::results_type results // Resolved endpoints as a range.
 789    * ); @endcode
 790    * Regardless of whether the asynchronous operation completes immediately or
 791    * not, the handler will not be invoked from within this function. On
 792    * immediate completion, invocation of the handler will be performed in a
 793    * manner equivalent to using boost::asio::post().
 794    *
 795    * A successful resolve operation is guaranteed to pass a non-empty range to
 796    * the handler.
 797    *
 798    * @note On POSIX systems, host names may be locally defined in the file
 799    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
 800    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
 801    * resolution is performed using DNS. Operating systems may use additional
 802    * locations when resolving host names (such as NETBIOS names on Windows).
 803    *
 804    * On POSIX systems, service names are typically defined in the file
 805    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
 806    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
 807    * may use additional locations when resolving service names.
 808    */
 809   template <
 810       BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 811         results_type)) ResolveHandler
 812           BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
 813   BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler,
 814       void (boost::system::error_code, results_type))
 815   async_resolve(const protocol_type& protocol,
 816       BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
 817       BOOST_ASIO_MOVE_ARG(ResolveHandler) handler
 818         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
 819   {
 820     return async_resolve(protocol, host, service, resolver_base::flags(),
 821         BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler));
 822   }
 823
 824   /// Asynchronously perform forward resolution of a query to a list of entries.
 825   /**
 826    * This function is used to resolve host and service names into a list of
 827    * endpoint entries.
 828    *
 829    * @param protocol A protocol object, normally representing either the IPv4 or
 830    * IPv6 version of an internet protocol.
 831    *
 832    * @param host A string identifying a location. May be a descriptive name or
 833    * a numeric address string. If an empty string and the passive flag has been
 834    * specified, the resolved endpoints are suitable for local service binding.
 835    * If an empty string and passive is not specified, the resolved endpoints
 836    * will use the loopback address.
 837    *
 838    * @param service A string identifying the requested service. This may be a
 839    * descriptive name or a numeric string corresponding to a port number. May
 840    * be an empty string, in which case all resolved endpoints will have a port
 841    * number of 0.
 842    *
 843    * @param resolve_flags A set of flags that determine how name resolution
 844    * should be performed. The default flags are suitable for communication with
 845    * remote hosts. See the @ref resolver_base documentation for the set of
 846    * available flags.
 847    *
 848    * @param handler The handler to be called when the resolve operation
 849    * completes. Copies will be made of the handler as required. The function
 850    * signature of the handler must be:
 851    * @code void handler(
 852    *   const boost::system::error_code& error, // Result of operation.
 853    *   resolver::results_type results // Resolved endpoints as a range.
 854    * ); @endcode
 855    * Regardless of whether the asynchronous operation completes immediately or
 856    * not, the handler will not be invoked from within this function. On
 857    * immediate completion, invocation of the handler will be performed in a
 858    * manner equivalent to using boost::asio::post().
 859    *
 860    * A successful resolve operation is guaranteed to pass a non-empty range to
 861    * the handler.
 862    *
 863    * @note On POSIX systems, host names may be locally defined in the file
 864    * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
 865    * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
 866    * resolution is performed using DNS. Operating systems may use additional
 867    * locations when resolving host names (such as NETBIOS names on Windows).
 868    *
 869    * On POSIX systems, service names are typically defined in the file
 870    * <tt>/etc/services</tt>. On Windows, service names may be found in the file
 871    * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
 872    * may use additional locations when resolving service names.
 873    */
 874   template <
 875       BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 876         results_type)) ResolveHandler
 877           BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
 878   BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler,
 879       void (boost::system::error_code, results_type))
 880   async_resolve(const protocol_type& protocol,
 881       BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
 882       resolver_base::flags resolve_flags,
 883       BOOST_ASIO_MOVE_ARG(ResolveHandler) handler
 884         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
 885   {
 886     basic_resolver_query<protocol_type> q(
 887         protocol, static_cast<std::string>(host),
 888         static_cast<std::string>(service), resolve_flags);
 889
 890     return boost::asio::async_initiate<ResolveHandler,
 891       void (boost::system::error_code, results_type)>(
 892         initiate_async_resolve(this), handler, q);
 893   }
 894
 895   /// Perform reverse resolution of an endpoint to a list of entries.
 896   /**
 897    * This function is used to resolve an endpoint into a list of endpoint
 898    * entries.
 899    *
 900    * @param e An endpoint object that determines what endpoints will be
 901    * returned.
 902    *
 903    * @returns A range object representing the list of endpoint entries. A
 904    * successful call to this function is guaranteed to return a non-empty
 905    * range.
 906    *
 907    * @throws boost::system::system_error Thrown on failure.
 908    */
 909   results_type resolve(const endpoint_type& e)
 910   {
 911     boost::system::error_code ec;
 912     results_type i = impl_.get_service().resolve(
 913         impl_.get_implementation(), e, ec);
 914     boost::asio::detail::throw_error(ec, "resolve");
 915     return i;
 916   }
 917
 918   /// Perform reverse resolution of an endpoint to a list of entries.
 919   /**
 920    * This function is used to resolve an endpoint into a list of endpoint
 921    * entries.
 922    *
 923    * @param e An endpoint object that determines what endpoints will be
 924    * returned.
 925    *
 926    * @param ec Set to indicate what error occurred, if any.
 927    *
 928    * @returns A range object representing the list of endpoint entries. An
 929    * empty range is returned if an error occurs. A successful call to this
 930    * function is guaranteed to return a non-empty range.
 931    */
 932   results_type resolve(const endpoint_type& e, boost::system::error_code& ec)
 933   {
 934     return impl_.get_service().resolve(impl_.get_implementation(), e, ec);
 935   }
 936
 937   /// Asynchronously perform reverse resolution of an endpoint to a list of
 938   /// entries.
 939   /**
 940    * This function is used to asynchronously resolve an endpoint into a list of
 941    * endpoint entries.
 942    *
 943    * @param e An endpoint object that determines what endpoints will be
 944    * returned.
 945    *
 946    * @param handler The handler to be called when the resolve operation
 947    * completes. Copies will be made of the handler as required. The function
 948    * signature of the handler must be:
 949    * @code void handler(
 950    *   const boost::system::error_code& error, // Result of operation.
 951    *   resolver::results_type results // Resolved endpoints as a range.
 952    * ); @endcode
 953    * Regardless of whether the asynchronous operation completes immediately or
 954    * not, the handler will not be invoked from within this function. On
 955    * immediate completion, invocation of the handler will be performed in a
 956    * manner equivalent to using boost::asio::post().
 957    *
 958    * A successful resolve operation is guaranteed to pass a non-empty range to
 959    * the handler.
 960    */
 961   template <
 962       BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
 963         results_type)) ResolveHandler
 964           BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
 965   BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler,
 966       void (boost::system::error_code, results_type))
 967   async_resolve(const endpoint_type& e,
 968       BOOST_ASIO_MOVE_ARG(ResolveHandler) handler
 969         BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
 970   {
 971     return boost::asio::async_initiate<ResolveHandler,
 972       void (boost::system::error_code, results_type)>(
 973         initiate_async_resolve(this), handler, e);
 974   }
 975
 976 private:
 977   // Disallow copying and assignment.
 978   basic_resolver(const basic_resolver&) BOOST_ASIO_DELETED;
 979   basic_resolver& operator=(const basic_resolver&) BOOST_ASIO_DELETED;
 980
 981   class initiate_async_resolve
 982   {
 983   public:
 984     typedef Executor executor_type;
 985
 986     explicit initiate_async_resolve(basic_resolver* self)
 987       : self_(self)
 988     {
 989     }
 990
 991     executor_type get_executor() const BOOST_ASIO_NOEXCEPT
 992     {
 993       return self_->get_executor();
 994     }
 995
 996     template <typename ResolveHandler, typename Query>
 997     void operator()(BOOST_ASIO_MOVE_ARG(ResolveHandler) handler,
 998         const Query& q) const
 999     {
1000       // If you get an error on the following line it means that your handler
1001       // does not meet the documented type requirements for a ResolveHandler.
1002       BOOST_ASIO_RESOLVE_HANDLER_CHECK(
1003           ResolveHandler, handler, results_type) type_check;
1004
1005       boost::asio::detail::non_const_lvalue<ResolveHandler> handler2(handler);
1006       self_->impl_.get_service().async_resolve(
1007           self_->impl_.get_implementation(), q, handler2.value,
1008           self_->impl_.get_implementation_executor());
1009     }
1010
1011   private:
1012     basic_resolver* self_;
1013   };
1014
1015 # if defined(BOOST_ASIO_WINDOWS_RUNTIME)
1016   boost::asio::detail::io_object_impl<
1017     boost::asio::detail::winrt_resolver_service<InternetProtocol>,
1018     Executor> impl_;
1019 # else
1020   boost::asio::detail::io_object_impl<
1021     boost::asio::detail::resolver_service<InternetProtocol>,
1022     Executor> impl_;
1023 # endif
1024 };
1025
1026 } // namespace ip
1027 } // namespace asio
1028 } // namespace boost
1029
1030 #include <boost/asio/detail/pop_options.hpp>
1031
1032 #endif // BOOST_ASIO_IP_BASIC_RESOLVER_HPP