2 // ip/basic_resolver.hpp
3 // ~~~~~~~~~~~~~~~~~~~~~
5 // Copyright (c) 2003-2017 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/async_result.hpp>
21 #include <boost/asio/basic_io_object.hpp>
22 #include <boost/asio/detail/handler_type_requirements.hpp>
23 #include <boost/asio/detail/string_view.hpp>
24 #include <boost/asio/detail/throw_error.hpp>
25 #include <boost/asio/error.hpp>
26 #include <boost/asio/io_context.hpp>
27 #include <boost/asio/ip/basic_resolver_iterator.hpp>
28 #include <boost/asio/ip/basic_resolver_query.hpp>
29 #include <boost/asio/ip/basic_resolver_results.hpp>
30 #include <boost/asio/ip/resolver_base.hpp>
32 #if defined(BOOST_ASIO_HAS_MOVE)
34 #endif // defined(BOOST_ASIO_HAS_MOVE)
36 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
37 # include <boost/asio/ip/resolver_service.hpp>
38 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
39 # if defined(BOOST_ASIO_WINDOWS_RUNTIME)
40 # include <boost/asio/detail/winrt_resolver_service.hpp>
41 # define BOOST_ASIO_SVC_T \
42 boost::asio::detail::winrt_resolver_service<InternetProtocol>
44 # include <boost/asio/detail/resolver_service.hpp>
45 # define BOOST_ASIO_SVC_T \
46 boost::asio::detail::resolver_service<InternetProtocol>
48 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
50 #include <boost/asio/detail/push_options.hpp>
56 /// Provides endpoint resolution functionality.
58 * The basic_resolver class template provides the ability to resolve a query
59 * to a list of endpoints.
62 * @e Distinct @e objects: Safe.@n
63 * @e Shared @e objects: Unsafe.
65 template <typename InternetProtocol
66 BOOST_ASIO_SVC_TPARAM_DEF1(= resolver_service<InternetProtocol>)>
68 : BOOST_ASIO_SVC_ACCESS basic_io_object<BOOST_ASIO_SVC_T>,
72 /// The type of the executor associated with the object.
73 typedef io_context::executor_type executor_type;
75 /// The protocol type.
76 typedef InternetProtocol protocol_type;
78 /// The endpoint type.
79 typedef typename InternetProtocol::endpoint endpoint_type;
81 #if !defined(BOOST_ASIO_NO_DEPRECATED)
82 /// (Deprecated.) The query type.
83 typedef basic_resolver_query<InternetProtocol> query;
85 /// (Deprecated.) The iterator type.
86 typedef basic_resolver_iterator<InternetProtocol> iterator;
87 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
90 typedef basic_resolver_results<InternetProtocol> results_type;
94 * This constructor creates a basic_resolver.
96 * @param io_context The io_context object that the resolver will use to
97 * dispatch handlers for any asynchronous operations performed on the
100 explicit basic_resolver(boost::asio::io_context& io_context)
101 : basic_io_object<BOOST_ASIO_SVC_T>(io_context)
105 #if defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
106 /// Move-construct a basic_resolver from another.
108 * This constructor moves a resolver from one object to another.
110 * @param other The other basic_resolver object from which the move will
113 * @note Following the move, the moved-from object is in the same state as if
114 * constructed using the @c basic_resolver(io_context&) constructor.
116 basic_resolver(basic_resolver&& other)
117 : basic_io_object<BOOST_ASIO_SVC_T>(std::move(other))
121 /// Move-assign a basic_resolver from another.
123 * This assignment operator moves a resolver from one object to another.
124 * Cancels any outstanding asynchronous operations associated with the target
127 * @param other The other basic_resolver object from which the move will
130 * @note Following the move, the moved-from object is in the same state as if
131 * constructed using the @c basic_resolver(io_context&) constructor.
133 basic_resolver& operator=(basic_resolver&& other)
135 basic_io_object<BOOST_ASIO_SVC_T>::operator=(std::move(other));
138 #endif // defined(BOOST_ASIO_HAS_MOVE) || defined(GENERATING_DOCUMENTATION)
140 /// Destroys the resolver.
142 * This function destroys the resolver, cancelling any outstanding
143 * asynchronous wait operations associated with the resolver as if by calling
150 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
151 // These functions are provided by basic_io_object<>.
152 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
153 #if !defined(BOOST_ASIO_NO_DEPRECATED)
154 /// (Deprecated: Use get_executor().) Get the io_context associated with the
157 * This function may be used to obtain the io_context object that the I/O
158 * object uses to dispatch handlers for asynchronous operations.
160 * @return A reference to the io_context object that the I/O object will use
161 * to dispatch handlers. Ownership is not transferred to the caller.
163 boost::asio::io_context& get_io_context()
165 return basic_io_object<BOOST_ASIO_SVC_T>::get_io_context();
168 /// (Deprecated: Use get_executor().) Get the io_context associated with the
171 * This function may be used to obtain the io_context object that the I/O
172 * object uses to dispatch handlers for asynchronous operations.
174 * @return A reference to the io_context object that the I/O object will use
175 * to dispatch handlers. Ownership is not transferred to the caller.
177 boost::asio::io_context& get_io_service()
179 return basic_io_object<BOOST_ASIO_SVC_T>::get_io_service();
181 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
183 /// Get the executor associated with the object.
184 executor_type get_executor() BOOST_ASIO_NOEXCEPT
186 return basic_io_object<BOOST_ASIO_SVC_T>::get_executor();
188 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
190 /// Cancel any asynchronous operations that are waiting on the resolver.
192 * This function forces the completion of any pending asynchronous
193 * operations on the host resolver. The handler for each cancelled operation
194 * will be invoked with the boost::asio::error::operation_aborted error code.
198 return this->get_service().cancel(this->get_implementation());
201 #if !defined(BOOST_ASIO_NO_DEPRECATED)
202 /// (Deprecated.) Perform forward resolution of a query to a list of entries.
204 * This function is used to resolve a query into a list of endpoint entries.
206 * @param q A query object that determines what endpoints will be returned.
208 * @returns A range object representing the list of endpoint entries. A
209 * successful call to this function is guaranteed to return a non-empty
212 * @throws boost::system::system_error Thrown on failure.
214 results_type resolve(const query& q)
216 boost::system::error_code ec;
217 results_type r = this->get_service().resolve(
218 this->get_implementation(), q, ec);
219 boost::asio::detail::throw_error(ec, "resolve");
223 /// (Deprecated.) Perform forward resolution of a query to a list of entries.
225 * This function is used to resolve a query into a list of endpoint entries.
227 * @param q A query object that determines what endpoints will be returned.
229 * @param ec Set to indicate what error occurred, if any.
231 * @returns A range object representing the list of endpoint entries. An
232 * empty range is returned if an error occurs. A successful call to this
233 * function is guaranteed to return a non-empty range.
235 results_type resolve(const query& q, boost::system::error_code& ec)
237 return this->get_service().resolve(this->get_implementation(), q, ec);
239 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
241 /// Perform forward resolution of a query to a list of entries.
243 * This function is used to resolve host and service names into a list of
246 * @param host A string identifying a location. May be a descriptive name or
247 * a numeric address string. If an empty string and the passive flag has been
248 * specified, the resolved endpoints are suitable for local service binding.
249 * If an empty string and passive is not specified, the resolved endpoints
250 * will use the loopback address.
252 * @param service A string identifying the requested service. This may be a
253 * descriptive name or a numeric string corresponding to a port number. May
254 * be an empty string, in which case all resolved endpoints will have a port
257 * @returns A range object representing the list of endpoint entries. A
258 * successful call to this function is guaranteed to return a non-empty
261 * @throws boost::system::system_error Thrown on failure.
263 * @note On POSIX systems, host names may be locally defined in the file
264 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
265 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
266 * resolution is performed using DNS. Operating systems may use additional
267 * locations when resolving host names (such as NETBIOS names on Windows).
269 * On POSIX systems, service names are typically defined in the file
270 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
271 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
272 * may use additional locations when resolving service names.
274 results_type resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
275 BOOST_ASIO_STRING_VIEW_PARAM service)
277 return resolve(host, service, resolver_base::flags());
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 * @param ec Set to indicate what error occurred, if any.
298 * @returns A range object representing the list of endpoint entries. An
299 * empty range is returned if an error occurs. A successful call to this
300 * function is guaranteed to return a non-empty range.
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, boost::system::error_code& ec)
316 return resolve(host, service, resolver_base::flags(), ec);
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 resolve_flags A set of flags that determine how name resolution
336 * should be performed. The default flags are suitable for communication with
339 * @returns A range object representing the list of endpoint entries. A
340 * successful call to this function is guaranteed to return a non-empty
343 * @throws boost::system::system_error Thrown on failure.
345 * @note On POSIX systems, host names may be locally defined in the file
346 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
347 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
348 * resolution is performed using DNS. Operating systems may use additional
349 * locations when resolving host names (such as NETBIOS names on Windows).
351 * On POSIX systems, service names are typically defined in the file
352 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
353 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
354 * may use additional locations when resolving service names.
356 results_type resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
357 BOOST_ASIO_STRING_VIEW_PARAM service, resolver_base::flags resolve_flags)
359 boost::system::error_code ec;
360 basic_resolver_query<protocol_type> q(static_cast<std::string>(host),
361 static_cast<std::string>(service), resolve_flags);
362 results_type r = this->get_service().resolve(
363 this->get_implementation(), q, ec);
364 boost::asio::detail::throw_error(ec, "resolve");
368 /// Perform forward resolution of a query to a list of entries.
370 * This function is used to resolve host and service names into a list of
373 * @param host A string identifying a location. May be a descriptive name or
374 * a numeric address string. If an empty string and the passive flag has been
375 * specified, the resolved endpoints are suitable for local service binding.
376 * If an empty string and passive is not specified, the resolved endpoints
377 * will use the loopback address.
379 * @param service A string identifying the requested service. This may be a
380 * descriptive name or a numeric string corresponding to a port number. May
381 * be an empty string, in which case all resolved endpoints will have a port
384 * @param resolve_flags A set of flags that determine how name resolution
385 * should be performed. The default flags are suitable for communication with
388 * @param ec Set to indicate what error occurred, if any.
390 * @returns A range object representing the list of endpoint entries. An
391 * empty range is returned if an error occurs. A successful call to this
392 * function is guaranteed to return a non-empty range.
394 * @note On POSIX systems, host names may be locally defined in the file
395 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
396 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
397 * resolution is performed using DNS. Operating systems may use additional
398 * locations when resolving host names (such as NETBIOS names on Windows).
400 * On POSIX systems, service names are typically defined in the file
401 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
402 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
403 * may use additional locations when resolving service names.
405 results_type resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
406 BOOST_ASIO_STRING_VIEW_PARAM service, resolver_base::flags resolve_flags,
407 boost::system::error_code& ec)
409 basic_resolver_query<protocol_type> q(static_cast<std::string>(host),
410 static_cast<std::string>(service), resolve_flags);
411 return this->get_service().resolve(this->get_implementation(), q, ec);
414 /// Perform forward resolution of a query to a list of entries.
416 * This function is used to resolve host and service names into a list of
419 * @param protocol A protocol object, normally representing either the IPv4 or
420 * IPv6 version of an internet protocol.
422 * @param host A string identifying a location. May be a descriptive name or
423 * a numeric address string. If an empty string and the passive flag has been
424 * specified, the resolved endpoints are suitable for local service binding.
425 * If an empty string and passive is not specified, the resolved endpoints
426 * will use the loopback address.
428 * @param service A string identifying the requested service. This may be a
429 * descriptive name or a numeric string corresponding to a port number. May
430 * be an empty string, in which case all resolved endpoints will have a port
433 * @returns A range object representing the list of endpoint entries. A
434 * successful call to this function is guaranteed to return a non-empty
437 * @throws boost::system::system_error Thrown on failure.
439 * @note On POSIX systems, host names may be locally defined in the file
440 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
441 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
442 * resolution is performed using DNS. Operating systems may use additional
443 * locations when resolving host names (such as NETBIOS names on Windows).
445 * On POSIX systems, service names are typically defined in the file
446 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
447 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
448 * may use additional locations when resolving service names.
450 results_type resolve(const protocol_type& protocol,
451 BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service)
453 return resolve(protocol, host, service, resolver_base::flags());
456 /// Perform forward resolution of a query to a list of entries.
458 * This function is used to resolve host and service names into a list of
461 * @param protocol A protocol object, normally representing either the IPv4 or
462 * IPv6 version of an internet protocol.
464 * @param host A string identifying a location. May be a descriptive name or
465 * a numeric address string. If an empty string and the passive flag has been
466 * specified, the resolved endpoints are suitable for local service binding.
467 * If an empty string and passive is not specified, the resolved endpoints
468 * will use the loopback address.
470 * @param service A string identifying the requested service. This may be a
471 * descriptive name or a numeric string corresponding to a port number. May
472 * be an empty string, in which case all resolved endpoints will have a port
475 * @param ec Set to indicate what error occurred, if any.
477 * @returns A range object representing the list of endpoint entries. An
478 * empty range is returned if an error occurs. A successful call to this
479 * function is guaranteed to return a non-empty range.
481 * @note On POSIX systems, host names may be locally defined in the file
482 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
483 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
484 * resolution is performed using DNS. Operating systems may use additional
485 * locations when resolving host names (such as NETBIOS names on Windows).
487 * On POSIX systems, service names are typically defined in the file
488 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
489 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
490 * may use additional locations when resolving service names.
492 results_type resolve(const protocol_type& protocol,
493 BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
494 boost::system::error_code& ec)
496 return resolve(protocol, host, service, resolver_base::flags(), ec);
499 /// Perform forward resolution of a query to a list of entries.
501 * This function is used to resolve host and service names into a list of
504 * @param protocol A protocol object, normally representing either the IPv4 or
505 * IPv6 version of an internet protocol.
507 * @param host A string identifying a location. May be a descriptive name or
508 * a numeric address string. If an empty string and the passive flag has been
509 * specified, the resolved endpoints are suitable for local service binding.
510 * If an empty string and passive is not specified, the resolved endpoints
511 * will use the loopback address.
513 * @param service A string identifying the requested service. This may be a
514 * descriptive name or a numeric string corresponding to a port number. May
515 * be an empty string, in which case all resolved endpoints will have a port
518 * @param resolve_flags A set of flags that determine how name resolution
519 * should be performed. The default flags are suitable for communication with
522 * @returns A range object representing the list of endpoint entries. A
523 * successful call to this function is guaranteed to return a non-empty
526 * @throws boost::system::system_error Thrown on failure.
528 * @note On POSIX systems, host names may be locally defined in the file
529 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
530 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
531 * resolution is performed using DNS. Operating systems may use additional
532 * locations when resolving host names (such as NETBIOS names on Windows).
534 * On POSIX systems, service names are typically defined in the file
535 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
536 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
537 * may use additional locations when resolving service names.
539 results_type resolve(const protocol_type& protocol,
540 BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
541 resolver_base::flags resolve_flags)
543 boost::system::error_code ec;
544 basic_resolver_query<protocol_type> q(
545 protocol, static_cast<std::string>(host),
546 static_cast<std::string>(service), resolve_flags);
547 results_type r = this->get_service().resolve(
548 this->get_implementation(), q, ec);
549 boost::asio::detail::throw_error(ec, "resolve");
553 /// Perform forward resolution of a query to a list of entries.
555 * This function is used to resolve host and service names into a list of
558 * @param protocol A protocol object, normally representing either the IPv4 or
559 * IPv6 version of an internet protocol.
561 * @param host A string identifying a location. May be a descriptive name or
562 * a numeric address string. If an empty string and the passive flag has been
563 * specified, the resolved endpoints are suitable for local service binding.
564 * If an empty string and passive is not specified, the resolved endpoints
565 * will use the loopback address.
567 * @param service A string identifying the requested service. This may be a
568 * descriptive name or a numeric string corresponding to a port number. May
569 * be an empty string, in which case all resolved endpoints will have a port
572 * @param resolve_flags A set of flags that determine how name resolution
573 * should be performed. The default flags are suitable for communication with
576 * @param ec Set to indicate what error occurred, if any.
578 * @returns A range object representing the list of endpoint entries. An
579 * empty range is returned if an error occurs. A successful call to this
580 * function is guaranteed to return a non-empty range.
582 * @note On POSIX systems, host names may be locally defined in the file
583 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
584 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
585 * resolution is performed using DNS. Operating systems may use additional
586 * locations when resolving host names (such as NETBIOS names on Windows).
588 * On POSIX systems, service names are typically defined in the file
589 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
590 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
591 * may use additional locations when resolving service names.
593 results_type resolve(const protocol_type& protocol,
594 BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
595 resolver_base::flags resolve_flags, boost::system::error_code& ec)
597 basic_resolver_query<protocol_type> q(
598 protocol, static_cast<std::string>(host),
599 static_cast<std::string>(service), resolve_flags);
600 return this->get_service().resolve(this->get_implementation(), q, ec);
603 #if !defined(BOOST_ASIO_NO_DEPRECATED)
604 /// (Deprecated.) Asynchronously perform forward resolution of a query to a
607 * This function is used to asynchronously resolve a query into a list of
610 * @param q A query object that determines what endpoints will be returned.
612 * @param handler The handler to be called when the resolve operation
613 * completes. Copies will be made of the handler as required. The function
614 * signature of the handler must be:
615 * @code void handler(
616 * const boost::system::error_code& error, // Result of operation.
617 * resolver::results_type results // Resolved endpoints as a range.
619 * Regardless of whether the asynchronous operation completes immediately or
620 * not, the handler will not be invoked from within this function. Invocation
621 * of the handler will be performed in a manner equivalent to using
622 * boost::asio::io_context::post().
624 * A successful resolve operation is guaranteed to pass a non-empty range to
627 template <typename ResolveHandler>
628 BOOST_ASIO_INITFN_RESULT_TYPE(ResolveHandler,
629 void (boost::system::error_code, results_type))
630 async_resolve(const query& q,
631 BOOST_ASIO_MOVE_ARG(ResolveHandler) handler)
633 // If you get an error on the following line it means that your handler does
634 // not meet the documented type requirements for a ResolveHandler.
635 BOOST_ASIO_RESOLVE_HANDLER_CHECK(
636 ResolveHandler, handler, results_type) type_check;
638 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
639 return this->get_service().async_resolve(this->get_implementation(), q,
640 BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler));
641 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
642 boost::asio::async_completion<ResolveHandler,
643 void (boost::system::error_code, results_type)> init(handler);
645 this->get_service().async_resolve(
646 this->get_implementation(), q, init.completion_handler);
648 return init.result.get();
649 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
651 #endif // !defined(BOOST_ASIO_NO_DEPRECATED)
653 /// Asynchronously perform forward resolution of a query to a list of entries.
655 * This function is used to resolve host and service names into a list of
658 * @param host A string identifying a location. May be a descriptive name or
659 * a numeric address string. If an empty string and the passive flag has been
660 * specified, the resolved endpoints are suitable for local service binding.
661 * If an empty string and passive is not specified, the resolved endpoints
662 * will use the loopback address.
664 * @param service A string identifying the requested service. This may be a
665 * descriptive name or a numeric string corresponding to a port number. May
666 * be an empty string, in which case all resolved endpoints will have a port
669 * @param handler The handler to be called when the resolve operation
670 * completes. Copies will be made of the handler as required. The function
671 * signature of the handler must be:
672 * @code void handler(
673 * const boost::system::error_code& error, // Result of operation.
674 * resolver::results_type results // Resolved endpoints as a range.
676 * Regardless of whether the asynchronous operation completes immediately or
677 * not, the handler will not be invoked from within this function. Invocation
678 * of the handler will be performed in a manner equivalent to using
679 * boost::asio::io_context::post().
681 * A successful resolve operation is guaranteed to pass a non-empty range to
684 * @note On POSIX systems, host names may be locally defined in the file
685 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
686 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
687 * resolution is performed using DNS. Operating systems may use additional
688 * locations when resolving host names (such as NETBIOS names on Windows).
690 * On POSIX systems, service names are typically defined in the file
691 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
692 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
693 * may use additional locations when resolving service names.
695 template <typename ResolveHandler>
696 BOOST_ASIO_INITFN_RESULT_TYPE(ResolveHandler,
697 void (boost::system::error_code, results_type))
698 async_resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
699 BOOST_ASIO_STRING_VIEW_PARAM service,
700 BOOST_ASIO_MOVE_ARG(ResolveHandler) handler)
702 return async_resolve(host, service, resolver_base::flags(),
703 BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler));
706 /// Asynchronously perform forward resolution of a query to a list of entries.
708 * This function is used to resolve host and service names into a list of
711 * @param host A string identifying a location. May be a descriptive name or
712 * a numeric address string. If an empty string and the passive flag has been
713 * specified, the resolved endpoints are suitable for local service binding.
714 * If an empty string and passive is not specified, the resolved endpoints
715 * will use the loopback address.
717 * @param service A string identifying the requested service. This may be a
718 * descriptive name or a numeric string corresponding to a port number. May
719 * be an empty string, in which case all resolved endpoints will have a port
722 * @param resolve_flags A set of flags that determine how name resolution
723 * should be performed. The default flags are suitable for communication with
726 * @param handler The handler to be called when the resolve operation
727 * completes. Copies will be made of the handler as required. The function
728 * signature of the handler must be:
729 * @code void handler(
730 * const boost::system::error_code& error, // Result of operation.
731 * resolver::results_type results // Resolved endpoints as a range.
733 * Regardless of whether the asynchronous operation completes immediately or
734 * not, the handler will not be invoked from within this function. Invocation
735 * of the handler will be performed in a manner equivalent to using
736 * boost::asio::io_context::post().
738 * A successful resolve operation is guaranteed to pass a non-empty range to
741 * @note On POSIX systems, host names may be locally defined in the file
742 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
743 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
744 * resolution is performed using DNS. Operating systems may use additional
745 * locations when resolving host names (such as NETBIOS names on Windows).
747 * On POSIX systems, service names are typically defined in the file
748 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
749 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
750 * may use additional locations when resolving service names.
752 template <typename ResolveHandler>
753 BOOST_ASIO_INITFN_RESULT_TYPE(ResolveHandler,
754 void (boost::system::error_code, results_type))
755 async_resolve(BOOST_ASIO_STRING_VIEW_PARAM host,
756 BOOST_ASIO_STRING_VIEW_PARAM service,
757 resolver_base::flags resolve_flags,
758 BOOST_ASIO_MOVE_ARG(ResolveHandler) handler)
760 // If you get an error on the following line it means that your handler does
761 // not meet the documented type requirements for a ResolveHandler.
762 BOOST_ASIO_RESOLVE_HANDLER_CHECK(
763 ResolveHandler, handler, results_type) type_check;
765 basic_resolver_query<protocol_type> q(static_cast<std::string>(host),
766 static_cast<std::string>(service), resolve_flags);
768 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
769 return this->get_service().async_resolve(this->get_implementation(), q,
770 BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler));
771 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
772 boost::asio::async_completion<ResolveHandler,
773 void (boost::system::error_code, results_type)> init(handler);
775 this->get_service().async_resolve(
776 this->get_implementation(), q, init.completion_handler);
778 return init.result.get();
779 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
782 /// Asynchronously perform forward resolution of a query to a list of entries.
784 * This function is used to resolve host and service names into a list of
787 * @param protocol A protocol object, normally representing either the IPv4 or
788 * IPv6 version of an internet protocol.
790 * @param host A string identifying a location. May be a descriptive name or
791 * a numeric address string. If an empty string and the passive flag has been
792 * specified, the resolved endpoints are suitable for local service binding.
793 * If an empty string and passive is not specified, the resolved endpoints
794 * will use the loopback address.
796 * @param service A string identifying the requested service. This may be a
797 * descriptive name or a numeric string corresponding to a port number. May
798 * be an empty string, in which case all resolved endpoints will have a port
801 * @param handler The handler to be called when the resolve operation
802 * completes. Copies will be made of the handler as required. The function
803 * signature of the handler must be:
804 * @code void handler(
805 * const boost::system::error_code& error, // Result of operation.
806 * resolver::results_type results // Resolved endpoints as a range.
808 * Regardless of whether the asynchronous operation completes immediately or
809 * not, the handler will not be invoked from within this function. Invocation
810 * of the handler will be performed in a manner equivalent to using
811 * boost::asio::io_context::post().
813 * A successful resolve operation is guaranteed to pass a non-empty range to
816 * @note On POSIX systems, host names may be locally defined in the file
817 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
818 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
819 * resolution is performed using DNS. Operating systems may use additional
820 * locations when resolving host names (such as NETBIOS names on Windows).
822 * On POSIX systems, service names are typically defined in the file
823 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
824 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
825 * may use additional locations when resolving service names.
827 template <typename ResolveHandler>
828 BOOST_ASIO_INITFN_RESULT_TYPE(ResolveHandler,
829 void (boost::system::error_code, results_type))
830 async_resolve(const protocol_type& protocol,
831 BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
832 BOOST_ASIO_MOVE_ARG(ResolveHandler) handler)
834 return async_resolve(protocol, host, service, resolver_base::flags(),
835 BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler));
838 /// Asynchronously perform forward resolution of a query to a list of entries.
840 * This function is used to resolve host and service names into a list of
843 * @param protocol A protocol object, normally representing either the IPv4 or
844 * IPv6 version of an internet protocol.
846 * @param host A string identifying a location. May be a descriptive name or
847 * a numeric address string. If an empty string and the passive flag has been
848 * specified, the resolved endpoints are suitable for local service binding.
849 * If an empty string and passive is not specified, the resolved endpoints
850 * will use the loopback address.
852 * @param service A string identifying the requested service. This may be a
853 * descriptive name or a numeric string corresponding to a port number. May
854 * be an empty string, in which case all resolved endpoints will have a port
857 * @param resolve_flags A set of flags that determine how name resolution
858 * should be performed. The default flags are suitable for communication with
861 * @param handler The handler to be called when the resolve operation
862 * completes. Copies will be made of the handler as required. The function
863 * signature of the handler must be:
864 * @code void handler(
865 * const boost::system::error_code& error, // Result of operation.
866 * resolver::results_type results // Resolved endpoints as a range.
868 * Regardless of whether the asynchronous operation completes immediately or
869 * not, the handler will not be invoked from within this function. Invocation
870 * of the handler will be performed in a manner equivalent to using
871 * boost::asio::io_context::post().
873 * A successful resolve operation is guaranteed to pass a non-empty range to
876 * @note On POSIX systems, host names may be locally defined in the file
877 * <tt>/etc/hosts</tt>. On Windows, host names may be defined in the file
878 * <tt>c:\\windows\\system32\\drivers\\etc\\hosts</tt>. Remote host name
879 * resolution is performed using DNS. Operating systems may use additional
880 * locations when resolving host names (such as NETBIOS names on Windows).
882 * On POSIX systems, service names are typically defined in the file
883 * <tt>/etc/services</tt>. On Windows, service names may be found in the file
884 * <tt>c:\\windows\\system32\\drivers\\etc\\services</tt>. Operating systems
885 * may use additional locations when resolving service names.
887 template <typename ResolveHandler>
888 BOOST_ASIO_INITFN_RESULT_TYPE(ResolveHandler,
889 void (boost::system::error_code, results_type))
890 async_resolve(const protocol_type& protocol,
891 BOOST_ASIO_STRING_VIEW_PARAM host, BOOST_ASIO_STRING_VIEW_PARAM service,
892 resolver_base::flags resolve_flags,
893 BOOST_ASIO_MOVE_ARG(ResolveHandler) handler)
895 // If you get an error on the following line it means that your handler does
896 // not meet the documented type requirements for a ResolveHandler.
897 BOOST_ASIO_RESOLVE_HANDLER_CHECK(
898 ResolveHandler, handler, results_type) type_check;
900 basic_resolver_query<protocol_type> q(
901 protocol, static_cast<std::string>(host),
902 static_cast<std::string>(service), resolve_flags);
904 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
905 return this->get_service().async_resolve(this->get_implementation(), q,
906 BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler));
907 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
908 boost::asio::async_completion<ResolveHandler,
909 void (boost::system::error_code, results_type)> init(handler);
911 this->get_service().async_resolve(
912 this->get_implementation(), q, init.completion_handler);
914 return init.result.get();
915 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
918 /// Perform reverse resolution of an endpoint to a list of entries.
920 * This function is used to resolve an endpoint into a list of endpoint
923 * @param e An endpoint object that determines what endpoints will be
926 * @returns A range object representing the list of endpoint entries. A
927 * successful call to this function is guaranteed to return a non-empty
930 * @throws boost::system::system_error Thrown on failure.
932 results_type resolve(const endpoint_type& e)
934 boost::system::error_code ec;
935 results_type i = this->get_service().resolve(
936 this->get_implementation(), e, ec);
937 boost::asio::detail::throw_error(ec, "resolve");
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 * @param ec Set to indicate what error occurred, if any.
951 * @returns A range object representing the list of endpoint entries. An
952 * empty range is returned if an error occurs. A successful call to this
953 * function is guaranteed to return a non-empty range.
955 results_type resolve(const endpoint_type& e, boost::system::error_code& ec)
957 return this->get_service().resolve(this->get_implementation(), e, ec);
960 /// Asynchronously perform reverse resolution of an endpoint to a list of
963 * This function is used to asynchronously resolve an endpoint into a list of
966 * @param e An endpoint object that determines what endpoints will be
969 * @param handler The handler to be called when the resolve operation
970 * completes. Copies will be made of the handler as required. The function
971 * signature of the handler must be:
972 * @code void handler(
973 * const boost::system::error_code& error, // Result of operation.
974 * resolver::results_type results // Resolved endpoints as a range.
976 * Regardless of whether the asynchronous operation completes immediately or
977 * not, the handler will not be invoked from within this function. Invocation
978 * of the handler will be performed in a manner equivalent to using
979 * boost::asio::io_context::post().
981 * A successful resolve operation is guaranteed to pass a non-empty range to
984 template <typename ResolveHandler>
985 BOOST_ASIO_INITFN_RESULT_TYPE(ResolveHandler,
986 void (boost::system::error_code, results_type))
987 async_resolve(const endpoint_type& e,
988 BOOST_ASIO_MOVE_ARG(ResolveHandler) handler)
990 // If you get an error on the following line it means that your handler does
991 // not meet the documented type requirements for a ResolveHandler.
992 BOOST_ASIO_RESOLVE_HANDLER_CHECK(
993 ResolveHandler, handler, results_type) type_check;
995 #if defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
996 return this->get_service().async_resolve(this->get_implementation(), e,
997 BOOST_ASIO_MOVE_CAST(ResolveHandler)(handler));
998 #else // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
999 boost::asio::async_completion<ResolveHandler,
1000 void (boost::system::error_code, results_type)> init(handler);
1002 this->get_service().async_resolve(
1003 this->get_implementation(), e, init.completion_handler);
1005 return init.result.get();
1006 #endif // defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
1012 } // namespace boost
1014 #include <boost/asio/detail/pop_options.hpp>
1016 #if !defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
1017 # undef BOOST_ASIO_SVC_T
1018 #endif // !defined(BOOST_ASIO_ENABLE_OLD_SERVICES)
1020 #endif // BOOST_ASIO_IP_BASIC_RESOLVER_HPP