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 required, 57 // 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 RequestPriority priority() const { return priority_; } 89 void set_priority(RequestPriority priority) { priority_ = priority; } 90 91 private: 92 // The hostname to resolve, and the port to use in resulting sockaddrs. 93 HostPortPair host_port_pair_; 94 95 // The address family to restrict results to. 96 AddressFamily address_family_; 97 98 // Flags to use when resolving this request. 99 HostResolverFlags host_resolver_flags_; 100 101 // Whether it is ok to return a result from the host cache. 102 bool allow_cached_response_; 103 104 // Whether this request was started by the DNS prefetcher. 105 bool is_speculative_; 106 107 // The priority for the request. 108 RequestPriority priority_; 109 }; 110 111 // Opaque type used to cancel a request. 112 typedef void* RequestHandle; 113 114 // This value can be passed into CreateSystemResolver as the 115 // |max_concurrent_resolves| parameter. It will select a default level of 116 // concurrency. 117 static const size_t kDefaultParallelism = 0; 118 119 // This value can be passed into CreateSystemResolver as the 120 // |max_retry_attempts| parameter. 121 static const size_t kDefaultRetryAttempts = -1; 122 123 // If any completion callbacks are pending when the resolver is destroyed, 124 // the host resolutions are cancelled, and the completion callbacks will not 125 // be called. 126 virtual ~HostResolver(); 127 128 // Resolves the given hostname (or IP address literal), filling out the 129 // |addresses| object upon success. The |info.port| parameter will be set as 130 // the sin(6)_port field of the sockaddr_in{6} struct. Returns OK if 131 // successful or an error code upon failure. Returns 132 // ERR_NAME_NOT_RESOLVED if hostname is invalid, or if it is an 133 // incompatible IP literal (e.g. IPv6 is disabled and it is an IPv6 134 // literal). 135 // 136 // If the operation cannot be completed synchronously, ERR_IO_PENDING will 137 // be returned and the real result code will be passed to the completion 138 // callback. Otherwise the result code is returned immediately from this 139 // call. 140 // 141 // If |out_req| is non-NULL, then |*out_req| will be filled with a handle to 142 // the async request. This handle is not valid after the request has 143 // completed. 144 // 145 // Profiling information for the request is saved to |net_log| if non-NULL. 146 virtual int Resolve(const RequestInfo& info, 147 AddressList* addresses, 148 const CompletionCallback& callback, 149 RequestHandle* out_req, 150 const BoundNetLog& net_log) = 0; 151 152 // Resolves the given hostname (or IP address literal) out of cache or HOSTS 153 // file (if enabled) only. This is guaranteed to complete synchronously. 154 // This acts like |Resolve()| if the hostname is IP literal, or cached value 155 // or HOSTS entry exists. Otherwise, ERR_DNS_CACHE_MISS is returned. 156 virtual int ResolveFromCache(const RequestInfo& info, 157 AddressList* addresses, 158 const BoundNetLog& net_log) = 0; 159 160 // Cancels the specified request. |req| is the handle returned by Resolve(). 161 // After a request is canceled, its completion callback will not be called. 162 // CancelRequest must NOT be called after the request's completion callback 163 // has already run or the request was canceled. 164 virtual void CancelRequest(RequestHandle req) = 0; 165 166 // Sets the default AddressFamily to use when requests have left it 167 // unspecified. For example, this could be used to restrict resolution 168 // results to AF_INET by passing in ADDRESS_FAMILY_IPV4, or to 169 // AF_INET6 by passing in ADDRESS_FAMILY_IPV6. 170 virtual void SetDefaultAddressFamily(AddressFamily address_family) {} 171 virtual AddressFamily GetDefaultAddressFamily() const; 172 173 // Enable or disable the built-in asynchronous DnsClient. 174 virtual void SetDnsClientEnabled(bool enabled); 175 176 // Returns the HostResolverCache |this| uses, or NULL if there isn't one. 177 // Used primarily to clear the cache and for getting debug information. 178 virtual HostCache* GetHostCache(); 179 180 // Returns the current DNS configuration |this| is using, as a Value, or NULL 181 // if it's configured to always use the system host resolver. Caller takes 182 // ownership of the returned Value. 183 virtual base::Value* GetDnsConfigAsValue() const; 184 185 // Creates a HostResolver implementation that queries the underlying system. 186 // (Except if a unit-test has changed the global HostResolverProc using 187 // ScopedHostResolverProc to intercept requests to the system). 188 static scoped_ptr<HostResolver> CreateSystemResolver( 189 const Options& options, 190 NetLog* net_log); 191 192 // As above, but uses default parameters. 193 static scoped_ptr<HostResolver> CreateDefaultResolver(NetLog* net_log); 194 195 protected: 196 HostResolver(); 197 198 private: 199 DISALLOW_COPY_AND_ASSIGN(HostResolver); 200 }; 201 202 } // namespace net 203 204 #endif // NET_DNS_HOST_RESOLVER_H_ 205