1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef NET_DNS_HOST_RESOLVER_H_
6#define NET_DNS_HOST_RESOLVER_H_
7
8#include <string>
9
10#include "base/memory/scoped_ptr.h"
11#include "net/base/address_family.h"
12#include "net/base/completion_callback.h"
13#include "net/base/host_port_pair.h"
14#include "net/base/net_export.h"
15#include "net/base/net_util.h"
16#include "net/base/prioritized_dispatcher.h"
17#include "net/base/request_priority.h"
18
19namespace base {
20class Value;
21}
22
23namespace net {
24
25class AddressList;
26class BoundNetLog;
27class HostCache;
28class HostResolverProc;
29class NetLog;
30
31// This class represents the task of resolving hostnames (or IP address
32// literal) to an AddressList object.
33//
34// HostResolver can handle multiple requests at a time, so when cancelling a
35// request the RequestHandle that was returned by Resolve() needs to be
36// given.  A simpler alternative for consumers that only have 1 outstanding
37// request at a time is to create a SingleRequestHostResolver wrapper around
38// HostResolver (which will automatically cancel the single request when it
39// goes out of scope).
40class NET_EXPORT HostResolver {
41 public:
42  // |max_concurrent_resolves| is how many resolve requests will be allowed to
43  // run in parallel. Pass HostResolver::kDefaultParallelism to choose a
44  // default value.
45  // |max_retry_attempts| is the maximum number of times we will retry for host
46  // resolution. Pass HostResolver::kDefaultRetryAttempts to choose a default
47  // value.
48  // |enable_caching| controls whether a HostCache is used.
49  struct NET_EXPORT Options {
50    Options();
51
52    PrioritizedDispatcher::Limits GetDispatcherLimits() const;
53
54    size_t max_concurrent_resolves;
55    size_t max_retry_attempts;
56    bool enable_caching;
57  };
58
59  // The parameters for doing a Resolve(). A hostname and port are
60  // required; the rest are optional (and have reasonable defaults).
61  class NET_EXPORT RequestInfo {
62   public:
63    explicit RequestInfo(const HostPortPair& host_port_pair);
64
65    const HostPortPair& host_port_pair() const { return host_port_pair_; }
66    void set_host_port_pair(const HostPortPair& host_port_pair) {
67      host_port_pair_ = host_port_pair;
68    }
69
70    int port() const { return host_port_pair_.port(); }
71    const std::string& hostname() const { return host_port_pair_.host(); }
72
73    AddressFamily address_family() const { return address_family_; }
74    void set_address_family(AddressFamily address_family) {
75      address_family_ = address_family;
76    }
77
78    HostResolverFlags host_resolver_flags() const {
79      return host_resolver_flags_;
80    }
81    void set_host_resolver_flags(HostResolverFlags host_resolver_flags) {
82      host_resolver_flags_ = host_resolver_flags;
83    }
84
85    bool allow_cached_response() const { return allow_cached_response_; }
86    void set_allow_cached_response(bool b) { allow_cached_response_ = b; }
87
88    bool is_speculative() const { return is_speculative_; }
89    void set_is_speculative(bool b) { is_speculative_ = b; }
90
91    bool is_my_ip_address() const { return is_my_ip_address_; }
92    void set_is_my_ip_address(bool b) { is_my_ip_address_ = b; }
93
94   private:
95    // The hostname to resolve, and the port to use in resulting sockaddrs.
96    HostPortPair host_port_pair_;
97
98    // The address family to restrict results to.
99    AddressFamily address_family_;
100
101    // Flags to use when resolving this request.
102    HostResolverFlags host_resolver_flags_;
103
104    // Whether it is ok to return a result from the host cache.
105    bool allow_cached_response_;
106
107    // Whether this request was started by the DNS prefetcher.
108    bool is_speculative_;
109
110    // Indicates a request for myIpAddress (to differentiate from other requests
111    // for localhost, currently used by Chrome OS).
112    bool is_my_ip_address_;
113  };
114
115  // Opaque type used to cancel a request.
116  typedef void* RequestHandle;
117
118  // Set Options.max_concurrent_resolves to this to select a default level
119  // of concurrency.
120  static const size_t kDefaultParallelism = 0;
121
122  // Set Options.max_retry_attempts to this to select a default retry value.
123  static const size_t kDefaultRetryAttempts = static_cast<size_t>(-1);
124
125  // If any completion callbacks are pending when the resolver is destroyed,
126  // the host resolutions are cancelled, and the completion callbacks will not
127  // be called.
128  virtual ~HostResolver();
129
130  // Resolves the given hostname (or IP address literal), filling out the
131  // |addresses| object upon success.  The |info.port| parameter will be set as
132  // the sin(6)_port field of the sockaddr_in{6} struct.  Returns OK if
133  // successful or an error code upon failure.  Returns
134  // ERR_NAME_NOT_RESOLVED if hostname is invalid, or if it is an
135  // incompatible IP literal (e.g. IPv6 is disabled and it is an IPv6
136  // literal).
137  //
138  // If the operation cannot be completed synchronously, ERR_IO_PENDING will
139  // be returned and the real result code will be passed to the completion
140  // callback.  Otherwise the result code is returned immediately from this
141  // call.
142  //
143  // If |out_req| is non-NULL, then |*out_req| will be filled with a handle to
144  // the async request. This handle is not valid after the request has
145  // completed.
146  //
147  // Profiling information for the request is saved to |net_log| if non-NULL.
148  virtual int Resolve(const RequestInfo& info,
149                      RequestPriority priority,
150                      AddressList* addresses,
151                      const CompletionCallback& callback,
152                      RequestHandle* out_req,
153                      const BoundNetLog& net_log) = 0;
154
155  // Resolves the given hostname (or IP address literal) out of cache or HOSTS
156  // file (if enabled) only. This is guaranteed to complete synchronously.
157  // This acts like |Resolve()| if the hostname is IP literal, or cached value
158  // or HOSTS entry exists. Otherwise, ERR_DNS_CACHE_MISS is returned.
159  virtual int ResolveFromCache(const RequestInfo& info,
160                               AddressList* addresses,
161                               const BoundNetLog& net_log) = 0;
162
163  // Cancels the specified request. |req| is the handle returned by Resolve().
164  // After a request is canceled, its completion callback will not be called.
165  // CancelRequest must NOT be called after the request's completion callback
166  // has already run or the request was canceled.
167  virtual void CancelRequest(RequestHandle req) = 0;
168
169  // Sets the default AddressFamily to use when requests have left it
170  // unspecified. For example, this could be used to restrict resolution
171  // results to AF_INET by passing in ADDRESS_FAMILY_IPV4, or to
172  // AF_INET6 by passing in ADDRESS_FAMILY_IPV6.
173  virtual void SetDefaultAddressFamily(AddressFamily address_family) {}
174  virtual AddressFamily GetDefaultAddressFamily() const;
175
176  // Enable or disable the built-in asynchronous DnsClient.
177  virtual void SetDnsClientEnabled(bool enabled);
178
179  // Returns the HostResolverCache |this| uses, or NULL if there isn't one.
180  // Used primarily to clear the cache and for getting debug information.
181  virtual HostCache* GetHostCache();
182
183  // Returns the current DNS configuration |this| is using, as a Value, or NULL
184  // if it's configured to always use the system host resolver.  Caller takes
185  // ownership of the returned Value.
186  virtual base::Value* GetDnsConfigAsValue() const;
187
188  // Creates a HostResolver implementation that queries the underlying system.
189  // (Except if a unit-test has changed the global HostResolverProc using
190  // ScopedHostResolverProc to intercept requests to the system).
191  static scoped_ptr<HostResolver> CreateSystemResolver(
192      const Options& options,
193      NetLog* net_log);
194
195  // As above, but uses default parameters.
196  static scoped_ptr<HostResolver> CreateDefaultResolver(NetLog* net_log);
197
198 protected:
199  HostResolver();
200
201 private:
202  DISALLOW_COPY_AND_ASSIGN(HostResolver);
203};
204
205}  // namespace net
206
207#endif  // NET_DNS_HOST_RESOLVER_H_
208