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_BASE_NETWORK_DELEGATE_H_ 6 #define NET_BASE_NETWORK_DELEGATE_H_ 7 8 #include <string> 9 10 #include "base/callback.h" 11 #include "base/strings/string16.h" 12 #include "base/threading/non_thread_safe.h" 13 #include "net/base/auth.h" 14 #include "net/base/completion_callback.h" 15 #include "net/cookies/canonical_cookie.h" 16 17 class GURL; 18 19 namespace base { 20 class FilePath; 21 } 22 23 namespace net { 24 25 // NOTE: Layering violations! 26 // We decided to accept these violations (depending 27 // on other net/ submodules from net/base/), because otherwise NetworkDelegate 28 // would have to be broken up into too many smaller interfaces targeted to each 29 // submodule. Also, since the lower levels in net/ may callback into higher 30 // levels, we may encounter dangerous casting issues. 31 // 32 // NOTE: It is not okay to add any compile-time dependencies on symbols outside 33 // of net/base here, because we have a net_base library. Forward declarations 34 // are ok. 35 class CookieOptions; 36 class HttpRequestHeaders; 37 class HttpResponseHeaders; 38 class SocketStream; 39 class URLRequest; 40 41 class NET_EXPORT NetworkDelegate : public base::NonThreadSafe { 42 public: 43 // AuthRequiredResponse indicates how a NetworkDelegate handles an 44 // OnAuthRequired call. It's placed in this file to prevent url_request.h 45 // from having to include network_delegate.h. 46 enum AuthRequiredResponse { 47 AUTH_REQUIRED_RESPONSE_NO_ACTION, 48 AUTH_REQUIRED_RESPONSE_SET_AUTH, 49 AUTH_REQUIRED_RESPONSE_CANCEL_AUTH, 50 AUTH_REQUIRED_RESPONSE_IO_PENDING, 51 }; 52 typedef base::Callback<void(AuthRequiredResponse)> AuthCallback; 53 54 enum RequestWaitState { 55 REQUEST_WAIT_STATE_CACHE_START, 56 REQUEST_WAIT_STATE_CACHE_FINISH, 57 REQUEST_WAIT_STATE_NETWORK_START, 58 REQUEST_WAIT_STATE_NETWORK_FINISH, 59 REQUEST_WAIT_STATE_RESET 60 }; 61 62 virtual ~NetworkDelegate() {} 63 64 // Notification interface called by the network stack. Note that these 65 // functions mostly forward to the private virtuals. They also add some sanity 66 // checking on parameters. See the corresponding virtuals for explanations of 67 // the methods and their arguments. 68 int NotifyBeforeURLRequest(URLRequest* request, 69 const CompletionCallback& callback, 70 GURL* new_url); 71 int NotifyBeforeSendHeaders(URLRequest* request, 72 const CompletionCallback& callback, 73 HttpRequestHeaders* headers); 74 void NotifySendHeaders(URLRequest* request, 75 const HttpRequestHeaders& headers); 76 int NotifyHeadersReceived( 77 URLRequest* request, 78 const CompletionCallback& callback, 79 const HttpResponseHeaders* original_response_headers, 80 scoped_refptr<HttpResponseHeaders>* override_response_headers); 81 void NotifyBeforeRedirect(URLRequest* request, 82 const GURL& new_location); 83 void NotifyResponseStarted(URLRequest* request); 84 void NotifyRawBytesRead(const URLRequest& request, int bytes_read); 85 void NotifyCompleted(URLRequest* request, bool started); 86 void NotifyURLRequestDestroyed(URLRequest* request); 87 void NotifyPACScriptError(int line_number, const base::string16& error); 88 AuthRequiredResponse NotifyAuthRequired(URLRequest* request, 89 const AuthChallengeInfo& auth_info, 90 const AuthCallback& callback, 91 AuthCredentials* credentials); 92 bool CanGetCookies(const URLRequest& request, 93 const CookieList& cookie_list); 94 bool CanSetCookie(const URLRequest& request, 95 const std::string& cookie_line, 96 CookieOptions* options); 97 bool CanAccessFile(const URLRequest& request, 98 const base::FilePath& path) const; 99 bool CanThrottleRequest(const URLRequest& request) const; 100 bool CanEnablePrivacyMode(const GURL& url, 101 const GURL& first_party_for_cookies) const; 102 103 int NotifyBeforeSocketStreamConnect(SocketStream* socket, 104 const CompletionCallback& callback); 105 106 void NotifyRequestWaitStateChange(const URLRequest& request, 107 RequestWaitState state); 108 109 private: 110 // This is the interface for subclasses of NetworkDelegate to implement. These 111 // member functions will be called by the respective public notification 112 // member function, which will perform basic sanity checking. 113 114 // Called before a request is sent. Allows the delegate to rewrite the URL 115 // being fetched by modifying |new_url|. |callback| and |new_url| are valid 116 // only until OnURLRequestDestroyed is called for this request. Returns a net 117 // status code, generally either OK to continue with the request or 118 // ERR_IO_PENDING if the result is not ready yet. A status code other than OK 119 // and ERR_IO_PENDING will cancel the request and report the status code as 120 // the reason. 121 virtual int OnBeforeURLRequest(URLRequest* request, 122 const CompletionCallback& callback, 123 GURL* new_url) = 0; 124 125 // Called right before the HTTP headers are sent. Allows the delegate to 126 // read/write |headers| before they get sent out. |callback| and |headers| are 127 // valid only until OnCompleted or OnURLRequestDestroyed is called for this 128 // request. 129 // Returns a net status code. 130 virtual int OnBeforeSendHeaders(URLRequest* request, 131 const CompletionCallback& callback, 132 HttpRequestHeaders* headers) = 0; 133 134 // Called right before the HTTP request(s) are being sent to the network. 135 // |headers| is only valid until OnCompleted or OnURLRequestDestroyed is 136 // called for this request. 137 virtual void OnSendHeaders(URLRequest* request, 138 const HttpRequestHeaders& headers) = 0; 139 140 // Called for HTTP requests when the headers have been received. Returns a net 141 // status code, generally either OK to continue with the request or 142 // ERR_IO_PENDING if the result is not ready yet. A status code other than OK 143 // and ERR_IO_PENDING will cancel the request and report the status code as 144 // the reason. 145 // |original_response_headers| contains the headers as received over the 146 // network, these must not be modified. |override_response_headers| can be set 147 // to new values, that should be considered as overriding 148 // |original_response_headers|. 149 // |callback|, |original_response_headers|, and |override_response_headers| 150 // are only valid until OnURLRequestDestroyed is called for this request. 151 virtual int OnHeadersReceived( 152 URLRequest* request, 153 const CompletionCallback& callback, 154 const HttpResponseHeaders* original_response_headers, 155 scoped_refptr<HttpResponseHeaders>* override_response_headers) = 0; 156 157 // Called right after a redirect response code was received. 158 // |new_location| is only valid until OnURLRequestDestroyed is called for this 159 // request. 160 virtual void OnBeforeRedirect(URLRequest* request, 161 const GURL& new_location) = 0; 162 163 // This corresponds to URLRequestDelegate::OnResponseStarted. 164 virtual void OnResponseStarted(URLRequest* request) = 0; 165 166 // Called every time we read raw bytes. 167 virtual void OnRawBytesRead(const URLRequest& request, int bytes_read) = 0; 168 169 // Indicates that the URL request has been completed or failed. 170 // |started| indicates whether the request has been started. If false, 171 // some information like the socket address is not available. 172 virtual void OnCompleted(URLRequest* request, bool started) = 0; 173 174 // Called when an URLRequest is being destroyed. Note that the request is 175 // being deleted, so it's not safe to call any methods that may result in 176 // a virtual method call. 177 virtual void OnURLRequestDestroyed(URLRequest* request) = 0; 178 179 // Corresponds to ProxyResolverJSBindings::OnError. 180 virtual void OnPACScriptError(int line_number, 181 const base::string16& error) = 0; 182 183 // Called when a request receives an authentication challenge 184 // specified by |auth_info|, and is unable to respond using cached 185 // credentials. |callback| and |credentials| must be non-NULL, and must 186 // be valid until OnURLRequestDestroyed is called for |request|. 187 // 188 // The following return values are allowed: 189 // - AUTH_REQUIRED_RESPONSE_NO_ACTION: |auth_info| is observed, but 190 // no action is being taken on it. 191 // - AUTH_REQUIRED_RESPONSE_SET_AUTH: |credentials| is filled in with 192 // a username and password, which should be used in a response to 193 // |auth_info|. 194 // - AUTH_REQUIRED_RESPONSE_CANCEL_AUTH: The authentication challenge 195 // should not be attempted. 196 // - AUTH_REQUIRED_RESPONSE_IO_PENDING: The action will be decided 197 // asynchronously. |callback| will be invoked when the decision is made, 198 // and one of the other AuthRequiredResponse values will be passed in with 199 // the same semantics as described above. 200 virtual AuthRequiredResponse OnAuthRequired( 201 URLRequest* request, 202 const AuthChallengeInfo& auth_info, 203 const AuthCallback& callback, 204 AuthCredentials* credentials) = 0; 205 206 // Called when reading cookies to allow the network delegate to block access 207 // to the cookie. This method will never be invoked when 208 // LOAD_DO_NOT_SEND_COOKIES is specified. 209 virtual bool OnCanGetCookies(const URLRequest& request, 210 const CookieList& cookie_list) = 0; 211 212 // Called when a cookie is set to allow the network delegate to block access 213 // to the cookie. This method will never be invoked when 214 // LOAD_DO_NOT_SAVE_COOKIES is specified. 215 virtual bool OnCanSetCookie(const URLRequest& request, 216 const std::string& cookie_line, 217 CookieOptions* options) = 0; 218 219 // Called when a file access is attempted to allow the network delegate to 220 // allow or block access to the given file path. Returns true if access is 221 // allowed. 222 virtual bool OnCanAccessFile(const URLRequest& request, 223 const base::FilePath& path) const = 0; 224 225 // Returns true if the given request may be rejected when the 226 // URLRequestThrottlerManager believes the server servicing the 227 // request is overloaded or down. 228 virtual bool OnCanThrottleRequest(const URLRequest& request) const = 0; 229 230 // Returns true if the given |url| has to be requested over connection that 231 // is not tracked by the server. Usually is false, unless user privacy 232 // settings block cookies from being get or set. 233 virtual bool OnCanEnablePrivacyMode( 234 const GURL& url, 235 const GURL& first_party_for_cookies) const; 236 237 // Called before a SocketStream tries to connect. 238 virtual int OnBeforeSocketStreamConnect( 239 SocketStream* socket, const CompletionCallback& callback) = 0; 240 241 // Called when the completion of a URLRequest is blocking on a cache 242 // action or a network action, or when that is no longer the case. 243 // REQUEST_WAIT_STATE_RESET indicates for a given URLRequest 244 // cancellation of any pending waits for this request. 245 virtual void OnRequestWaitStateChange(const URLRequest& request, 246 RequestWaitState state) = 0; 247 }; 248 249 } // namespace net 250 251 #endif // NET_BASE_NETWORK_DELEGATE_H_ 252
