src/net/dns/host_resolver.h

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