21 Internet protocol [internet]

21.17 Class template ip::basic_resolver [internet.resolver]

1

Objects of type basic_resolver<InternetProtocol> are used to perform name resolution. Name resolution is the translation of a host name and service name into a sequence of endpoints, or the translation of an endpoint into its corresponding host name and service name.

namespace std {
namespace experimental {
namespace net {
inline namespace v1 {
namespace ip {

  template<class InternetProtocol>
  class basic_resolver : public resolver_base
  {
  public:
    // types:

    using executor_type = io_context::executor_type;
    using protocol_type = InternetProtocol;
    using endpoint_type = typename InternetProtocol::endpoint;
    using results_type = basic_resolver_results<InternetProtocol>;

    // [internet.resolver.cons], construct / copy / destroy:

    explicit basic_resolver(io_context& ctx);
    basic_resolver(const basic_resolver&) = delete;
    basic_resolver(basic_resolver&& rhs) noexcept;

    ~basic_resolver();

    basic_resolver& operator=(const basic_resolver&) = delete;
    basic_resolver& operator=(basic_resolver&& rhs);

    // [internet.resolver.ops], basic_resolver operations:

    executor_type get_executor() noexcept;

    void cancel();

    results_type resolve(string_view host_name, string_view service_name);
    results_type resolve(string_view host_name, string_view service_name,
                         error_code& ec);
    results_type resolve(string_view host_name, string_view service_name,
                         flags f);
    results_type resolve(string_view host_name, string_view service_name,
                         flags f, error_code& ec);

    template<class CompletionToken>
      DEDUCED async_resolve(string_view host_name, string_view service_name,
                            CompletionToken&& token);
    template<class CompletionToken>
      DEDUCED async_resolve(string_view host_name, string_view service_name,
                            flags f, CompletionToken&& token);

    results_type resolve(const protocol_type& protocol,
                         string_view host_name, string_view service_name);
    results_type resolve(const protocol_type& protocol,
                         string_view host_name, string_view service_name,
                         error_code& ec);
    results_type resolve(const protocol_type& protocol,
                         string_view host_name, string_view service_name,
                         flags f);
    results_type resolve(const protocol_type& protocol,
                         string_view host_name, string_view service_name,
                         flags f, error_code& ec);

    template<class CompletionToken>
      DEDUCED async_resolve(const protocol_type& protocol,
                            string_view host_name, string_view service_name,
                            CompletionToken&& token);
    template<class CompletionToken>
      DEDUCED async_resolve(const protocol_type& protocol,
                            string_view host_name, string_view service_name,
                            flags f, CompletionToken&& token);

    results_type resolve(const endpoint_type& e);
    results_type resolve(const endpoint_type& e, error_code& ec);

    template<class CompletionToken>
      DEDUCED async_resolve(const endpoint_type& e,
                            CompletionToken&& token);
  };

} // namespace ip
} // inline namespace v1
} // namespace net
} // namespace experimental
} // namespace std

21.17.1 ip::basic_resolver constructors [internet.resolver.cons]

explicit basic_resolver(io_context& ctx);

1

Postconditions: get_executor() == ctx.get_executor().

basic_resolver(basic_resolver&& rhs) noexcept;

2

Effects: Move constructs an object of class basic_resolver<InternetProtocol> that refers to the state originally represented by rhs.

3

Postconditions: get_executor() == rhs.get_executor().

21.17.2 ip::basic_resolver destructor [internet.resolver.dtor]

~basic_resolver();

1

Effects: Destroys the resolver, canceling all asynchronous operations associated with this resolver as if by calling cancel().

21.17.3 ip::basic_resolver assignment [internet.resolver.assign]

basic_resolver& operator=(basic_resolver&& rhs);

1

Effects: Cancels all outstanding asynchronous operations associated with *this as if by calling cancel(), then moves into *this the state originally represented by rhs.

2

Postconditions: get_executor() == rhs.get_executor().

3

Returns: *this.

21.17.4 ip::basic_resolver operations [internet.resolver.ops]

executor_type get_executor() noexcept;

1

Returns: The associated executor.

void cancel();

2

Effects: Cancels all outstanding asynchronous resolve operations associated with *this. Completion handlers for canceled operations are passed an error code ec such that ec == errc::operation_canceled yields true.

3

Remarks: Does not block (C++ 2014 [defns.block]) the calling thread pending completion of the canceled operations.

results_type resolve(string_view host_name, string_view service_name); results_type resolve(string_view host_name, string_view service_name, error_code& ec);

4

Returns: resolve(host_name, service_name, resolver_base::flags(), ec).

results_type resolve(string_view host_name, string_view service_name, flags f); results_type resolve(string_view host_name, string_view service_name, flags f, error_code& ec);

5

Effects: If host_name.data() != nullptr, let H be an ntbs constructed from host_name; otherwise, let H be nullptr. If service_name.data() != nullptr, let S be an ntbs constructed from service_name; otherwise, let S be nullptr. Resolves a host name and service name, as if by POSIX: 

addrinfo hints;
hints.ai_flags = static_cast<int>(f);
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = endpoint_type().protocol().type();
hints.ai_protocol = endpoint_type().protocol().protocol();
hints.ai_addr = nullptr;
hints.ai_addrlen = 0;
hints.ai_canonname = nullptr;
hints.ai_next = nullptr;
addrinfo* result = nullptr;
getaddrinfo(H, S, &hints, &result);
6

Returns: On success, a non-empty results object containing the results of the resolve operation. Otherwise results_type().

template<class CompletionToken> DEDUCED async_resolve(string_view host_name, string_view service_name, CompletionToken&& token);

7

Returns: 

async_resolve(host_name, service_name, resolver_base::flags(),
              forward<CompletionToken>(token))

template<class CompletionToken> DEDUCED async_resolve(string_view host_name, string_view service_name, flags f, CompletionToken&& token);

8

Completion signature: void(error_code ec, results_type r).

9

Effects: If host_name.data() != nullptr, let H be an ntbs constructed from host_name; otherwise, let H be nullptr. If service_name.data() != nullptr, let S be an ntbs constructed from service_name; otherwise, let S be nullptr. Initiates an asynchronous operation to resolve a host name and service name, as if by POSIX: 

addrinfo hints;
hints.ai_flags = static_cast<int>(f);
hints.ai_family = AF_UNSPEC;
hints.ai_socktype = endpoint_type().protocol().type();
hints.ai_protocol = endpoint_type().protocol().protocol();
hints.ai_addr = nullptr;
hints.ai_addrlen = 0;
hints.ai_canonname = nullptr;
hints.ai_next = nullptr;
addrinfo* result = nullptr;
getaddrinfo(H, S, &hints, &result);

On success, r is a non-empty results object containing the results of the resolve operation. Otherwise, r is results_type().

results_type resolve(const protocol_type& protocol, string_view host_name, string_view service_name); results_type resolve(const protocol_type& protocol, string_view host_name, string_view service_name, error_code& ec);

10

Returns: resolve(protocol, host_name, service_name, resolver_base::flags(), ec).

results_type resolve(const protocol_type& protocol, string_view host_name, string_view service_name, flags f); results_type resolve(const protocol_type& protocol, string_view host_name, string_view service_name, flags f, error_code& ec);

11

Effects: If host_name.data() != nullptr, let H be an ntbs constructed from host_name; otherwise, let H be nullptr. If service_name.data() != nullptr, let S be an ntbs constructed from service_name; otherwise, let S be nullptr. Resolves a host name and service name, as if by POSIX: 

addrinfo hints;
hints.ai_flags = static_cast<int>(f);
hints.ai_family = protocol.family();
hints.ai_socktype = protocol.type();
hints.ai_protocol = protocol.protocol();
hints.ai_addr = nullptr;
hints.ai_addrlen = 0;
hints.ai_canonname = nullptr;
hints.ai_next = nullptr;
addrinfo* result = nullptr;
getaddrinfo(H, S, &hints, &result);
12

Returns: On success, a non-empty results object containing the results of the resolve operation. Otherwise results_type().

template<class CompletionToken> DEDUCED async_resolve(const protocol_type& protocol, string_view host_name, string_view service_name, CompletionToken&& token);

13

Returns: 

async_resolve(protocol, host_name, service_name, resolver_base::flags(),
              forward<CompletionToken>(token))

template<class CompletionToken> DEDUCED async_resolve(const protocol& protocol, string_view host_name, string_view service_name, flags f, CompletionToken&& token);

14

Completion signature: void(error_code ec, results_type r).

15

Effects: If host_name.data() != nullptr, let H be an ntbs constructed from host_name; otherwise, let H be nullptr. If service_name.data() != nullptr, let S be an ntbs constructed from service_name; otherwise, let S be nullptr. Initiates an asynchronous operation to resolve a host name and service name, as if by POSIX: 

addrinfo hints;
hints.ai_flags = static_cast<int>(f);
hints.ai_family = protocol.family();
hints.ai_socktype = protocol.type();
hints.ai_protocol = protocol.protocol();
hints.ai_addr = nullptr;
hints.ai_addrlen = 0;
hints.ai_canonname = nullptr;
hints.ai_next = nullptr;
addrinfo* result = nullptr;
getaddrinfo(H, S, &hints, &result);

On success, r is a non-empty results object containing the results of the resolve operation. Otherwise, r is results_type().

results_type resolve(const endpoint_type& e); results_type resolve(const endpoint_type& e, error_code& ec);

16

Effects: Let S1 and S2 be implementation-defined values that are sufficiently large to hold the host name and service name respectively. Resolves an endpoint as if by POSIX: 

char host_name[S1];
char service_name[S2];
int flags = 0;
if (endpoint_type().protocol().type() == SOCK_DGRAM)
  flags |= NI_DGRAM;
int result = getnameinfo((const sockaddr*)e.data(), e.size(),
                         host_name, S1,
                         service_name, S2,
                         flags);
if (result != 0){
  flags |= NI_NUMERICSERV;
  result = getnameinfo((const sockaddr*)e.data(), e.size(),
                       host_name, S1,
                       service_name, S2,
                       flags);
}
17

Returns: On success, a results object with size() == 1 containing the results of the resolve operation. Otherwise results_type().

template<class CompletionToken> DEDUCED async_resolve(const endpoint_type& e, CompletionToken&& token);

18

Completion signature: void(error_code ec, results_type r).

19

Effects: Let S1 and S2 be implementation-defined values that are sufficiently large to hold the host name and service name respectively. Initiates an asynchronous operation to resolve an endpoint as if by POSIX: 

char host_name[S1];
char service_name[S2];
int flags = 0;
if (endpoint_type().protocol().type() == SOCK_DGRAM)
  flags |= NI_DGRAM;
int result = getnameinfo((const sockaddr*)e.data(), e.size(),
                         host_name, S1,
                         service_name, S2,
                         flags);
if (result != 0){
  flags |= NI_NUMERICSERV;
  result = getnameinfo((const sockaddr*)e.data(), e.size(),
                       host_name, S1,
                       service_name, S2,
                       flags);
}

On success, r is a results object with size() == 1 containing the results of the resolve operation; otherwise, r is results_type().