Home | History | Annotate | Download | only in dns 
      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 
     19 namespace base {
     20 class Value;
     21 }
     22 
     23 namespace net {
     24 
     25 class AddressList;
     26 class BoundNetLog;
     27 class HostCache;
     28 class HostResolverProc;
     29 class 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).
     40 class 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