2 // ip/basic_resolver.hpp
3 // ~~~~~~~~~~~~~~~~~~~~~
5 // Copyright (c) 2003-2020 Christopher M. Kohlhoff (chris at kohlhoff dot com)
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)
11 #ifndef BOOST_ASIO_IP_BASIC_RESOLVER_HPP
12 #define BOOST_ASIO_IP_BASIC_RESOLVER_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
20 #include <boost/asio/any_io_executor.hpp>
21 #include <boost/asio/async_result.hpp>
22 #include <boost/asio/detail/handler_type_requirements.hpp>
23 #include <boost/asio/detail/io_object_impl.hpp>
24 #include <boost/asio/detail/non_const_lvalue.hpp>
25 #include <boost/asio/detail/string_view.hpp>
26 #include <boost/asio/detail/throw_error.hpp>
27 #include <boost/asio/error.hpp>
28 #include <boost/asio/execution_context.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>
36 # include <boost/asio/detail/resolver_service.hpp>
39 #if defined(BOOST_ASIO_HAS_MOVE)
41 #endif // defined(BOOST_ASIO_HAS_MOVE)
43 #include <boost/asio/detail/push_options.hpp>
49 #if !defined(BOOST_ASIO_IP_BASIC_RESOLVER_FWD_DECL)
50 #define BOOST_ASIO_IP_BASIC_RESOLVER_FWD_DECL
52 // Forward declaration with defaulted arguments.
53 template <typename InternetProtocol, typename Executor = any_io_executor>
56 #endif // !defined(BOOST_ASIO_IP_BASIC_RESOLVER_FWD_DECL)
58 /// Provides endpoint resolution functionality.
60 * The basic_resolver class template provides the ability to resolve a query
61 * to a list of endpoints.
64 * @e Distinct @e objects: Safe.@n
65 * @e Shared @e objects: Unsafe.
67 template <typename InternetProtocol, typename Executor>
69 : public resolver_base
72 /// The type of the executor associated with the object.
73 typedef Executor executor_type;
75 /// Rebinds the resolver type to another executor.
76 template <typename Executor1>
77 struct rebind_executor
79 /// The resolver type when rebound to the specified executor.
80 typedef basic_resolver<InternetProtocol, Executor1> other;
83 /// The protocol type.
84 typedef InternetProtocol protocol_type;
86 /// The endpoint type.
87 typedef typename InternetProtocol::endpoint endpoint_type;
89 #if !defined(BOOST_ASIO_NO_DEPRECATED)
90 /// (Deprecated.) The query type.
91 typedef basic_resolver_query<InternetProtocol> query;
93 /// (Deprecated.) The iterator type.
94 typedef basic_resolver_iterator<InternetProtocol> iterator;
95 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
98 typedef basic_resolver_results<InternetProtocol> results_type;
100 /// Construct with executor.
102 * This constructor creates a basic_resolver.
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
108 explicit basic_resolver(const executor_type& ex)
113 /// Construct with execution context.
115 * This constructor creates a basic_resolver.
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.
121 template <typename ExecutionContext>
122 explicit basic_resolver(ExecutionContext& context,
124 is_convertible<ExecutionContext&, execution_context&>::value
130 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
131 /// Move-construct a basic_resolver from another.
133 * This constructor moves a resolver from one object to another.
135 * @param other The other basic_resolver object from which the move will
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.
141 basic_resolver(basic_resolver&& other)
142 : impl_(std::move(other.impl_))
146 // All resolvers have access to each other's implementations.
147 template <typename InternetProtocol1, typename Executor1>
148 friend class basic_resolver;
150 /// Move-construct a basic_resolver from another.
152 * This constructor moves a resolver from one object to another.
154 * @param other The other basic_resolver object from which the move will
157 * @note Following the move, the moved-from object is in the same state as if
158 * constructed using the @c basic_resolver(const executor_type&) constructor.
160 template <typename Executor1>
161 basic_resolver(basic_resolver<InternetProtocol, Executor1>&& other,
163 is_convertible<Executor1, Executor>::value
165 : impl_(std::move(other.impl_))
169 /// Move-assign a basic_resolver from another.
171 * This assignment operator moves a resolver from one object to another.
172 * Cancels any outstanding asynchronous operations associated with the target
175 * @param other The other basic_resolver object from which the move will
178 * @note Following the move, the moved-from object is in the same state as if
179 * constructed using the @c basic_resolver(const executor_type&) constructor.
181 basic_resolver& operator=(basic_resolver&& other)
183 impl_ = std::move(other.impl_);
187 /// Move-assign a basic_resolver from another.
189 * This assignment operator moves a resolver from one object to another.
190 * Cancels any outstanding asynchronous operations associated with the target
193 * @param other The other basic_resolver object from which the move will
196 * @note Following the move, the moved-from object is in the same state as if
197 * constructed using the @c basic_resolver(const executor_type&) constructor.
199 template <typename Executor1>
201 is_convertible<Executor1, Executor>::value,
203 >::type operator=(basic_resolver<InternetProtocol, Executor1>&& other)
205 basic_resolver tmp(std::move(other));
206 impl_ = std::move(tmp.impl_);
209 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
211 /// Destroys the resolver.
213 * This function destroys the resolver, cancelling any outstanding
214 * asynchronous wait operations associated with the resolver as if by calling
221 /// Get the executor associated with the object.
222 executor_type get_executor() BOOST_ASIO_NOEXCEPT
224 return impl_.get_executor();
227 /// Cancel any asynchronous operations that are waiting on the resolver.
229 * This function forces the completion of any pending asynchronous
230 * operations on the host resolver. The handler for each cancelled operation
231 * will be invoked with the boost::asio::error::operation_aborted error code.
235 return impl_.get_service().cancel(impl_.get_implementation());
238 #if !defined(BOOST_ASIO_NO_DEPRECATED)
239 /// (Deprecated: Use overload with separate host and service parameters.)
240 /// Perform forward resolution of a query to a list of entries.
242 * This function is used to resolve a query into a list of endpoint entries.
244 * @param q A query object that determines what endpoints will be returned.
246 * @returns A range object representing the list of endpoint entries. A
247 * successful call to this function is guaranteed to return a non-empty
250 * @throws boost::system::system_error Thrown on failure.
252 results_type resolve(const query& q)
254 boost::system::error_code ec;
255 results_type r = impl_.get_service().resolve(
256 impl_.get_implementation(), q, ec);
257 boost::asio::detail::throw_error(ec, "resolve");
261 /// (Deprecated: Use overload with separate host and service parameters.)
262 /// Perform forward resolution of a query to a list of entries.
264 * This function is used to resolve a query into a list of endpoint entries.
266 * @param q A query object that determines what endpoints will be returned.
268 * @param ec Set to indicate what error occurred, if any.
270 * @returns A range object representing the list of endpoint entries. An
271 * empty range is returned if an error occurs. A successful call to this
272 * function is guaranteed to return a non-empty range.
274 results_type resolve(const query& q, boost::system::error_code& ec)
276 return impl_.get_service().resolve(impl_.get_implementation(), q, ec);
278 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
280 /// Perform forward resolution of a query to a list of entries.
282 * This function is used to resolve host and service names into a list of
285 * @param host A string identifying a location. May be a descriptive name or
286 * a numeric address string. If an empty string and the passive flag has been
287 * specified, the resolved endpoints are suitable for local service binding.
288 * If an empty string and passive is not specified, the resolved endpoints
289 * will use the loopback address.
291 * @param service A string identifying the requested service. This may be a
292 * descriptive name or a numeric string corresponding to a port number. May
293 * be an empty string, in which case all resolved endpoints will have a port
296 * @returns A range object representing the list of endpoint entries. A
297 * successful call to this function is guaranteed to return a non-empty
300 * @throws boost::system::system_error Thrown on failure.
302 * @note On POSIX systems, host names may be locally defined in the file
303 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
304 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
305 * resolution is performed using DNS. Operating systems may use additional
306 * locations when resolving host names (such as NETBIOS names on Windows).
308 * On POSIX systems, service names are typically defined in the file
309 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
310 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
311 * may use additional locations when resolving service names.
313 results_type resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
314 BOOST_ASIO_STRING_VIEW_PARAM service)
316 return resolve(host, service, resolver_base::flags());
319 /// Perform forward resolution of a query to a list of entries.
321 * This function is used to resolve host and service names into a list of
324 * @param host A string identifying a location. May be a descriptive name or
325 * a numeric address string. If an empty string and the passive flag has been
326 * specified, the resolved endpoints are suitable for local service binding.
327 * If an empty string and passive is not specified, the resolved endpoints
328 * will use the loopback address.
330 * @param service A string identifying the requested service. This may be a
331 * descriptive name or a numeric string corresponding to a port number. May
332 * be an empty string, in which case all resolved endpoints will have a port
335 * @param ec Set to indicate what error occurred, if any.
337 * @returns A range object representing the list of endpoint entries. An
338 * empty range is returned if an error occurs. A successful call to this
339 * function is guaranteed to return a non-empty range.
341 * @note On POSIX systems, host names may be locally defined in the file
342 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
343 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
344 * resolution is performed using DNS. Operating systems may use additional
345 * locations when resolving host names (such as NETBIOS names on Windows).
347 * On POSIX systems, service names are typically defined in the file
348 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
349 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
350 * may use additional locations when resolving service names.
352 results_type resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
353 BOOST_ASIO_STRING_VIEW_PARAM service, boost::system::error_code& ec)
355 return resolve(host, service, resolver_base::flags(), ec);
358 /// Perform forward resolution of a query to a list of entries.
360 * This function is used to resolve host and service names into a list of
363 * @param host A string identifying a location. May be a descriptive name or
364 * a numeric address string. If an empty string and the passive flag has been
365 * specified, the resolved endpoints are suitable for local service binding.
366 * If an empty string and passive is not specified, the resolved endpoints
367 * will use the loopback address.
369 * @param service A string identifying the requested service. This may be a
370 * descriptive name or a numeric string corresponding to a port number. May
371 * be an empty string, in which case all resolved endpoints will have a port
374 * @param resolve_flags A set of flags that determine how name resolution
375 * should be performed. The default flags are suitable for communication with
376 * remote hosts. See the @ref resolver_base documentation for the set of
379 * @returns A range object representing the list of endpoint entries. A
380 * successful call to this function is guaranteed to return a non-empty
383 * @throws boost::system::system_error Thrown on failure.
385 * @note On POSIX systems, host names may be locally defined in the file
386 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
387 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
388 * resolution is performed using DNS. Operating systems may use additional
389 * locations when resolving host names (such as NETBIOS names on Windows).
391 * On POSIX systems, service names are typically defined in the file
392 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
393 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
394 * may use additional locations when resolving service names.
396 results_type resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
397 BOOST_ASIO_STRING_VIEW_PARAM service, resolver_base::flags resolve_flags)
399 boost::system::error_code ec;
400 basic_resolver_query<protocol_type> q(static_cast<std::string>(host),
401 static_cast<std::string>(service), resolve_flags);
402 results_type r = impl_.get_service().resolve(
403 impl_.get_implementation(), q, ec);
404 boost::asio::detail::throw_error(ec, "resolve");
408 /// Perform forward resolution of a query to a list of entries.
410 * This function is used to resolve host and service names into a list of
413 * @param host A string identifying a location. May be a descriptive name or
414 * a numeric address string. If an empty string and the passive flag has been
415 * specified, the resolved endpoints are suitable for local service binding.
416 * If an empty string and passive is not specified, the resolved endpoints
417 * will use the loopback address.
419 * @param service A string identifying the requested service. This may be a
420 * descriptive name or a numeric string corresponding to a port number. May
421 * be an empty string, in which case all resolved endpoints will have a port
424 * @param resolve_flags A set of flags that determine how name resolution
425 * should be performed. The default flags are suitable for communication with
426 * remote hosts. See the @ref resolver_base documentation for the set of
429 * @param ec Set to indicate what error occurred, if any.
431 * @returns A range object representing the list of endpoint entries. An
432 * empty range is returned if an error occurs. A successful call to this
433 * function is guaranteed to return a non-empty range.
435 * @note On POSIX systems, host names may be locally defined in the file
436 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
437 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
438 * resolution is performed using DNS. Operating systems may use additional
439 * locations when resolving host names (such as NETBIOS names on Windows).
441 * On POSIX systems, service names are typically defined in the file
442 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
443 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
444 * may use additional locations when resolving service names.
446 results_type resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
447 BOOST_ASIO_STRING_VIEW_PARAM service, resolver_base::flags resolve_flags,
448 boost::system::error_code& ec)
450 basic_resolver_query<protocol_type> q(static_cast<std::string>(host),
451 static_cast<std::string>(service), resolve_flags);
452 return impl_.get_service().resolve(impl_.get_implementation(), q, ec);
455 /// Perform forward resolution of a query to a list of entries.
457 * This function is used to resolve host and service names into a list of
460 * @param protocol A protocol object, normally representing either the IPv4 or
461 * IPv6 version of an internet protocol.
463 * @param host A string identifying a location. May be a descriptive name or
464 * a numeric address string. If an empty string and the passive flag has been
465 * specified, the resolved endpoints are suitable for local service binding.
466 * If an empty string and passive is not specified, the resolved endpoints
467 * will use the loopback address.
469 * @param service A string identifying the requested service. This may be a
470 * descriptive name or a numeric string corresponding to a port number. May
471 * be an empty string, in which case all resolved endpoints will have a port
474 * @returns A range object representing the list of endpoint entries. A
475 * successful call to this function is guaranteed to return a non-empty
478 * @throws boost::system::system_error Thrown on failure.
480 * @note On POSIX systems, host names may be locally defined in the file
481 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
482 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
483 * resolution is performed using DNS. Operating systems may use additional
484 * locations when resolving host names (such as NETBIOS names on Windows).
486 * On POSIX systems, service names are typically defined in the file
487 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
488 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
489 * may use additional locations when resolving service names.
491 results_type resolve(const protocol_type& protocol,
492 BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service)
494 return resolve(protocol, host, service, resolver_base::flags());
497 /// Perform forward resolution of a query to a list of entries.
499 * This function is used to resolve host and service names into a list of
502 * @param protocol A protocol object, normally representing either the IPv4 or
503 * IPv6 version of an internet protocol.
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.
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
516 * @param ec Set to indicate what error occurred, if any.
518 * @returns A range object representing the list of endpoint entries. An
519 * empty range is returned if an error occurs. A successful call to this
520 * function is guaranteed to return a non-empty range.
522 * @note On POSIX systems, host names may be locally defined in the file
523 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
524 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
525 * resolution is performed using DNS. Operating systems may use additional
526 * locations when resolving host names (such as NETBIOS names on Windows).
528 * On POSIX systems, service names are typically defined in the file
529 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
530 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
531 * may use additional locations when resolving service names.
533 results_type resolve(const protocol_type& protocol,
534 BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
535 boost::system::error_code& ec)
537 return resolve(protocol, host, service, resolver_base::flags(), ec);
540 /// Perform forward resolution of a query to a list of entries.
542 * This function is used to resolve host and service names into a list of
545 * @param protocol A protocol object, normally representing either the IPv4 or
546 * IPv6 version of an internet protocol.
548 * @param host A string identifying a location. May be a descriptive name or
549 * a numeric address string. If an empty string and the passive flag has been
550 * specified, the resolved endpoints are suitable for local service binding.
551 * If an empty string and passive is not specified, the resolved endpoints
552 * will use the loopback address.
554 * @param service A string identifying the requested service. This may be a
555 * descriptive name or a numeric string corresponding to a port number. May
556 * be an empty string, in which case all resolved endpoints will have a port
559 * @param resolve_flags A set of flags that determine how name resolution
560 * should be performed. The default flags are suitable for communication with
561 * remote hosts. See the @ref resolver_base documentation for the set of
564 * @returns A range object representing the list of endpoint entries. A
565 * successful call to this function is guaranteed to return a non-empty
568 * @throws boost::system::system_error Thrown on failure.
570 * @note On POSIX systems, host names may be locally defined in the file
571 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
572 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
573 * resolution is performed using DNS. Operating systems may use additional
574 * locations when resolving host names (such as NETBIOS names on Windows).
576 * On POSIX systems, service names are typically defined in the file
577 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
578 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
579 * may use additional locations when resolving service names.
581 results_type resolve(const protocol_type& protocol,
582 BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
583 resolver_base::flags resolve_flags)
585 boost::system::error_code ec;
586 basic_resolver_query<protocol_type> q(
587 protocol, static_cast<std::string>(host),
588 static_cast<std::string>(service), resolve_flags);
589 results_type r = impl_.get_service().resolve(
590 impl_.get_implementation(), q, ec);
591 boost::asio::detail::throw_error(ec, "resolve");
595 /// Perform forward resolution of a query to a list of entries.
597 * This function is used to resolve host and service names into a list of
600 * @param protocol A protocol object, normally representing either the IPv4 or
601 * IPv6 version of an internet protocol.
603 * @param host A string identifying a location. May be a descriptive name or
604 * a numeric address string. If an empty string and the passive flag has been
605 * specified, the resolved endpoints are suitable for local service binding.
606 * If an empty string and passive is not specified, the resolved endpoints
607 * will use the loopback address.
609 * @param service A string identifying the requested service. This may be a
610 * descriptive name or a numeric string corresponding to a port number. May
611 * be an empty string, in which case all resolved endpoints will have a port
614 * @param resolve_flags A set of flags that determine how name resolution
615 * should be performed. The default flags are suitable for communication with
616 * remote hosts. See the @ref resolver_base documentation for the set of
619 * @param ec Set to indicate what error occurred, if any.
621 * @returns A range object representing the list of endpoint entries. An
622 * empty range is returned if an error occurs. A successful call to this
623 * function is guaranteed to return a non-empty range.
625 * @note On POSIX systems, host names may be locally defined in the file
626 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
627 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
628 * resolution is performed using DNS. Operating systems may use additional
629 * locations when resolving host names (such as NETBIOS names on Windows).
631 * On POSIX systems, service names are typically defined in the file
632 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
633 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
634 * may use additional locations when resolving service names.
636 results_type resolve(const protocol_type& protocol,
637 BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
638 resolver_base::flags resolve_flags, boost::system::error_code& ec)
640 basic_resolver_query<protocol_type> q(
641 protocol, static_cast<std::string>(host),
642 static_cast<std::string>(service), resolve_flags);
643 return impl_.get_service().resolve(impl_.get_implementation(), q, ec);
646 #if !defined(BOOST_ASIO_NO_DEPRECATED)
647 /// (Deprecated: Use overload with separate host and service parameters.)
648 /// Asynchronously perform forward resolution of a query to a list of entries.
650 * This function is used to asynchronously resolve a query into a list of
653 * @param q A query object that determines what endpoints will be returned.
655 * @param handler The handler to be called when the resolve operation
656 * completes. Copies will be made of the handler as required. The function
657 * signature of the handler must be:
658 * @code void handler(
659 * const boost::system::error_code& error, // Result of operation.
660 * resolver::results_type results // Resolved endpoints as a range.
662 * Regardless of whether the asynchronous operation completes immediately or
663 * not, the handler will not be invoked from within this function. On
664 * immediate completion, invocation of the handler will be performed in a
665 * manner equivalent to using boost::asio::post().
667 * A successful resolve operation is guaranteed to pass a non-empty range to
671 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
672 results_type)) ResolveHandler
673 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
674 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler,
675 void (boost::system::error_code, results_type))
676 async_resolve(const query& q,
677 BOOST_ASIO_MOVE_ARG(ResolveHandler) handler
678 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
680 return boost::asio::async_initiate<ResolveHandler,
681 void (boost::system::error_code, results_type)>(
682 initiate_async_resolve(this), handler, q);
684 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
686 /// Asynchronously perform forward resolution of a query to a list of entries.
688 * This function is used to resolve host and service names into a list of
691 * @param host A string identifying a location. May be a descriptive name or
692 * a numeric address string. If an empty string and the passive flag has been
693 * specified, the resolved endpoints are suitable for local service binding.
694 * If an empty string and passive is not specified, the resolved endpoints
695 * will use the loopback address.
697 * @param service A string identifying the requested service. This may be a
698 * descriptive name or a numeric string corresponding to a port number. May
699 * be an empty string, in which case all resolved endpoints will have a port
702 * @param handler The handler to be called when the resolve operation
703 * completes. Copies will be made of the handler as required. The function
704 * signature of the handler must be:
705 * @code void handler(
706 * const boost::system::error_code& error, // Result of operation.
707 * resolver::results_type results // Resolved endpoints as a range.
709 * Regardless of whether the asynchronous operation completes immediately or
710 * not, the handler will not be invoked from within this function. On
711 * immediate completion, invocation of the handler will be performed in a
712 * manner equivalent to using boost::asio::post().
714 * A successful resolve operation is guaranteed to pass a non-empty range to
717 * @note On POSIX systems, host names may be locally defined in the file
718 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
719 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
720 * resolution is performed using DNS. Operating systems may use additional
721 * locations when resolving host names (such as NETBIOS names on Windows).
723 * On POSIX systems, service names are typically defined in the file
724 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
725 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
726 * may use additional locations when resolving service names.
729 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
730 results_type)) ResolveHandler
731 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
732 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler,
733 void (boost::system::error_code, results_type))
734 async_resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
735 BOOST_ASIO_STRING_VIEW_PARAM service,
736 BOOST_ASIO_MOVE_ARG(ResolveHandler) handler
737 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
739 return async_resolve(host, service, resolver_base::flags(),
740 BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler));
743 /// Asynchronously perform forward resolution of a query to a list of entries.
745 * This function is used to resolve host and service names into a list of
748 * @param host A string identifying a location. May be a descriptive name or
749 * a numeric address string. If an empty string and the passive flag has been
750 * specified, the resolved endpoints are suitable for local service binding.
751 * If an empty string and passive is not specified, the resolved endpoints
752 * will use the loopback address.
754 * @param service A string identifying the requested service. This may be a
755 * descriptive name or a numeric string corresponding to a port number. May
756 * be an empty string, in which case all resolved endpoints will have a port
759 * @param resolve_flags A set of flags that determine how name resolution
760 * should be performed. The default flags are suitable for communication with
761 * remote hosts. See the @ref resolver_base documentation for the set of
764 * @param handler The handler to be called when the resolve operation
765 * completes. Copies will be made of the handler as required. The function
766 * signature of the handler must be:
767 * @code void handler(
768 * const boost::system::error_code& error, // Result of operation.
769 * resolver::results_type results // Resolved endpoints as a range.
771 * Regardless of whether the asynchronous operation completes immediately or
772 * not, the handler will not be invoked from within this function. On
773 * immediate completion, invocation of the handler will be performed in a
774 * manner equivalent to using boost::asio::post().
776 * A successful resolve operation is guaranteed to pass a non-empty range to
779 * @note On POSIX systems, host names may be locally defined in the file
780 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
781 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
782 * resolution is performed using DNS. Operating systems may use additional
783 * locations when resolving host names (such as NETBIOS names on Windows).
785 * On POSIX systems, service names are typically defined in the file
786 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
787 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
788 * may use additional locations when resolving service names.
791 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
792 results_type)) ResolveHandler
793 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
794 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler,
795 void (boost::system::error_code, results_type))
796 async_resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
797 BOOST_ASIO_STRING_VIEW_PARAM service,
798 resolver_base::flags resolve_flags,
799 BOOST_ASIO_MOVE_ARG(ResolveHandler) handler
800 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
802 basic_resolver_query<protocol_type> q(static_cast<std::string>(host),
803 static_cast<std::string>(service), resolve_flags);
805 return boost::asio::async_initiate<ResolveHandler,
806 void (boost::system::error_code, results_type)>(
807 initiate_async_resolve(this), handler, q);
810 /// Asynchronously perform forward resolution of a query to a list of entries.
812 * This function is used to resolve host and service names into a list of
815 * @param protocol A protocol object, normally representing either the IPv4 or
816 * IPv6 version of an internet protocol.
818 * @param host A string identifying a location. May be a descriptive name or
819 * a numeric address string. If an empty string and the passive flag has been
820 * specified, the resolved endpoints are suitable for local service binding.
821 * If an empty string and passive is not specified, the resolved endpoints
822 * will use the loopback address.
824 * @param service A string identifying the requested service. This may be a
825 * descriptive name or a numeric string corresponding to a port number. May
826 * be an empty string, in which case all resolved endpoints will have a port
829 * @param handler The handler to be called when the resolve operation
830 * completes. Copies will be made of the handler as required. The function
831 * signature of the handler must be:
832 * @code void handler(
833 * const boost::system::error_code& error, // Result of operation.
834 * resolver::results_type results // Resolved endpoints as a range.
836 * Regardless of whether the asynchronous operation completes immediately or
837 * not, the handler will not be invoked from within this function. On
838 * immediate completion, invocation of the handler will be performed in a
839 * manner equivalent to using boost::asio::post().
841 * A successful resolve operation is guaranteed to pass a non-empty range to
844 * @note On POSIX systems, host names may be locally defined in the file
845 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
846 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
847 * resolution is performed using DNS. Operating systems may use additional
848 * locations when resolving host names (such as NETBIOS names on Windows).
850 * On POSIX systems, service names are typically defined in the file
851 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
852 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
853 * may use additional locations when resolving service names.
856 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
857 results_type)) ResolveHandler
858 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
859 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler,
860 void (boost::system::error_code, results_type))
861 async_resolve(const protocol_type& protocol,
862 BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
863 BOOST_ASIO_MOVE_ARG(ResolveHandler) handler
864 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
866 return async_resolve(protocol, host, service, resolver_base::flags(),
867 BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler));
870 /// Asynchronously perform forward resolution of a query to a list of entries.
872 * This function is used to resolve host and service names into a list of
875 * @param protocol A protocol object, normally representing either the IPv4 or
876 * IPv6 version of an internet protocol.
878 * @param host A string identifying a location. May be a descriptive name or
879 * a numeric address string. If an empty string and the passive flag has been
880 * specified, the resolved endpoints are suitable for local service binding.
881 * If an empty string and passive is not specified, the resolved endpoints
882 * will use the loopback address.
884 * @param service A string identifying the requested service. This may be a
885 * descriptive name or a numeric string corresponding to a port number. May
886 * be an empty string, in which case all resolved endpoints will have a port
889 * @param resolve_flags A set of flags that determine how name resolution
890 * should be performed. The default flags are suitable for communication with
891 * remote hosts. See the @ref resolver_base documentation for the set of
894 * @param handler The handler to be called when the resolve 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 * const boost::system::error_code& error, // Result of operation.
899 * resolver::results_type results // Resolved endpoints as a range.
901 * Regardless of whether the asynchronous operation completes immediately or
902 * not, the handler will not be invoked from within this function. On
903 * immediate completion, invocation of the handler will be performed in a
904 * manner equivalent to using boost::asio::post().
906 * A successful resolve operation is guaranteed to pass a non-empty range to
909 * @note On POSIX systems, host names may be locally defined in the file
910 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
911 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
912 * resolution is performed using DNS. Operating systems may use additional
913 * locations when resolving host names (such as NETBIOS names on Windows).
915 * On POSIX systems, service names are typically defined in the file
916 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
917 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
918 * may use additional locations when resolving service names.
921 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
922 results_type)) ResolveHandler
923 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
924 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler,
925 void (boost::system::error_code, results_type))
926 async_resolve(const protocol_type& protocol,
927 BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
928 resolver_base::flags resolve_flags,
929 BOOST_ASIO_MOVE_ARG(ResolveHandler) handler
930 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
932 basic_resolver_query<protocol_type> q(
933 protocol, static_cast<std::string>(host),
934 static_cast<std::string>(service), resolve_flags);
936 return boost::asio::async_initiate<ResolveHandler,
937 void (boost::system::error_code, results_type)>(
938 initiate_async_resolve(this), handler, q);
941 /// Perform reverse resolution of an endpoint to a list of entries.
943 * This function is used to resolve an endpoint into a list of endpoint
946 * @param e An endpoint object that determines what endpoints will be
949 * @returns A range object representing the list of endpoint entries. A
950 * successful call to this function is guaranteed to return a non-empty
953 * @throws boost::system::system_error Thrown on failure.
955 results_type resolve(const endpoint_type& e)
957 boost::system::error_code ec;
958 results_type i = impl_.get_service().resolve(
959 impl_.get_implementation(), e, ec);
960 boost::asio::detail::throw_error(ec, "resolve");
964 /// Perform reverse resolution of an endpoint to a list of entries.
966 * This function is used to resolve an endpoint into a list of endpoint
969 * @param e An endpoint object that determines what endpoints will be
972 * @param ec Set to indicate what error occurred, if any.
974 * @returns A range object representing the list of endpoint entries. An
975 * empty range is returned if an error occurs. A successful call to this
976 * function is guaranteed to return a non-empty range.
978 results_type resolve(const endpoint_type& e, boost::system::error_code& ec)
980 return impl_.get_service().resolve(impl_.get_implementation(), e, ec);
983 /// Asynchronously perform reverse resolution of an endpoint to a list of
986 * This function is used to asynchronously resolve an endpoint into a list of
989 * @param e An endpoint object that determines what endpoints will be
992 * @param handler The handler to be called when the resolve operation
993 * completes. Copies will be made of the handler as required. The function
994 * signature of the handler must be:
995 * @code void handler(
996 * const boost::system::error_code& error, // Result of operation.
997 * resolver::results_type results // Resolved endpoints as a range.
999 * Regardless of whether the asynchronous operation completes immediately or
1000 * not, the handler will not be invoked from within this function. On
1001 * immediate completion, invocation of the handler will be performed in a
1002 * manner equivalent to using boost::asio::post().
1004 * A successful resolve operation is guaranteed to pass a non-empty range to
1008 BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code,
1009 results_type)) ResolveHandler
1010 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN_TYPE(executor_type)>
1011 BOOST_ASIO_INITFN_AUTO_RESULT_TYPE(ResolveHandler,
1012 void (boost::system::error_code, results_type))
1013 async_resolve(const endpoint_type& e,
1014 BOOST_ASIO_MOVE_ARG(ResolveHandler) handler
1015 BOOST_ASIO_DEFAULT_COMPLETION_TOKEN(executor_type))
1017 return boost::asio::async_initiate<ResolveHandler,
1018 void (boost::system::error_code, results_type)>(
1019 initiate_async_resolve(this), handler, e);
1023 // Disallow copying and assignment.
1024 basic_resolver(const basic_resolver&) BOOST_ASIO_DELETED;
1025 basic_resolver& operator=(const basic_resolver&) BOOST_ASIO_DELETED;
1027 class initiate_async_resolve
1030 typedef Executor executor_type;
1032 explicit initiate_async_resolve(basic_resolver* self)
1037 executor_type get_executor() const BOOST_ASIO_NOEXCEPT
1039 return self_->get_executor();
1042 template <typename ResolveHandler, typename Query>
1043 void operator()(BOOST_ASIO_MOVE_ARG(ResolveHandler) handler,
1044 const Query& q) const
1046 // If you get an error on the following line it means that your handler
1047 // does not meet the documented type requirements for a ResolveHandler.
1048 BOOST_ASIO_RESOLVE_HANDLER_CHECK(
1049 ResolveHandler, handler, results_type) type_check;
1051 boost::asio::detail::non_const_lvalue<ResolveHandler> handler2(handler);
1052 self_->impl_.get_service().async_resolve(
1053 self_->impl_.get_implementation(), q,
1054 handler2.value, self_->impl_.get_executor());
1058 basic_resolver* self_;
1061 # if defined(BOOST_ASIO_WINDOWS_RUNTIME)
1062 boost::asio::detail::io_object_impl<
1063 boost::asio::detail::winrt_resolver_service<InternetProtocol>,
1066 boost::asio::detail::io_object_impl<
1067 boost::asio::detail::resolver_service<InternetProtocol>,
1074 } // namespace boost
1076 #include <boost/asio/detail/pop_options.hpp>
1078 #endif // BOOST_ASIO_IP_BASIC_RESOLVER_HPP