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