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

source code of boost/libs/asio/include/boost/asio/ip/basic_resolver.hpp