src/net/base/network_delegate.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_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 ProxyInfo;
  39 class ProxyServer;
  40 class ProxyService;
  41 class SocketStream;
  42 class URLRequest;
  43
  44 class NET_EXPORT NetworkDelegate : public base::NonThreadSafe {
  45  public:
  46   // AuthRequiredResponse indicates how a NetworkDelegate handles an
  47   // OnAuthRequired call. It's placed in this file to prevent url_request.h
  48   // from having to include network_delegate.h.
  49   enum AuthRequiredResponse {
  50     AUTH_REQUIRED_RESPONSE_NO_ACTION,
  51     AUTH_REQUIRED_RESPONSE_SET_AUTH,
  52     AUTH_REQUIRED_RESPONSE_CANCEL_AUTH,
  53     AUTH_REQUIRED_RESPONSE_IO_PENDING,
  54   };
  55   typedef base::Callback<void(AuthRequiredResponse)> AuthCallback;
  56
  57   virtual ~NetworkDelegate() {}
  58
  59   // Notification interface called by the network stack. Note that these
  60   // functions mostly forward to the private virtuals. They also add some sanity
  61   // checking on parameters. See the corresponding virtuals for explanations of
  62   // the methods and their arguments.
  63   int NotifyBeforeURLRequest(URLRequest* request,
  64                              const CompletionCallback& callback,
  65                              GURL* new_url);
  66   void NotifyResolveProxy(const GURL& url,
  67                           int load_flags,
  68                           const ProxyService& proxy_service,
  69                           ProxyInfo* result);
  70   void NotifyProxyFallback(const ProxyServer& bad_proxy,
  71                            int net_error);
  72   int NotifyBeforeSendHeaders(URLRequest* request,
  73                               const CompletionCallback& callback,
  74                               HttpRequestHeaders* headers);
  75   void NotifyBeforeSendProxyHeaders(URLRequest* request,
  76                                     const ProxyInfo& proxy_info,
  77                                     HttpRequestHeaders* headers);
  78   void NotifySendHeaders(URLRequest* request,
  79                          const HttpRequestHeaders& headers);
  80   int NotifyHeadersReceived(
  81       URLRequest* request,
  82       const CompletionCallback& callback,
  83       const HttpResponseHeaders* original_response_headers,
  84       scoped_refptr<HttpResponseHeaders>* override_response_headers,
  85       GURL* allowed_unsafe_redirect_url);
  86   void NotifyBeforeRedirect(URLRequest* request,
  87                             const GURL& new_location);
  88   void NotifyResponseStarted(URLRequest* request);
  89   void NotifyRawBytesRead(const URLRequest& request, int bytes_read);
  90   void NotifyCompleted(URLRequest* request, bool started);
  91   void NotifyURLRequestDestroyed(URLRequest* request);
  92   void NotifyPACScriptError(int line_number, const base::string16& error);
  93   AuthRequiredResponse NotifyAuthRequired(URLRequest* request,
  94                                           const AuthChallengeInfo& auth_info,
  95                                           const AuthCallback& callback,
  96                                           AuthCredentials* credentials);
  97   bool CanGetCookies(const URLRequest& request,
  98                      const CookieList& cookie_list);
  99   bool CanSetCookie(const URLRequest& request,
 100                     const std::string& cookie_line,
 101                     CookieOptions* options);
 102   bool CanAccessFile(const URLRequest& request,
 103                      const base::FilePath& path) const;
 104   bool CanThrottleRequest(const URLRequest& request) const;
 105   bool CanEnablePrivacyMode(const GURL& url,
 106                             const GURL& first_party_for_cookies) const;
 107
 108   int NotifyBeforeSocketStreamConnect(SocketStream* socket,
 109                                       const CompletionCallback& callback);
 110
 111  private:
 112   // This is the interface for subclasses of NetworkDelegate to implement. These
 113   // member functions will be called by the respective public notification
 114   // member function, which will perform basic sanity checking.
 115
 116   // Called before a request is sent. Allows the delegate to rewrite the URL
 117   // being fetched by modifying |new_url|. If set, the URL must be valid. The
 118   // reference fragment from the original URL is not automatically appended to
 119   // |new_url|; callers are responsible for copying the reference fragment if
 120   // desired.
 121   // |callback| and |new_url| are valid only until OnURLRequestDestroyed is
 122   // called for this request. Returns a net status code, generally either OK to
 123   // continue with the request or ERR_IO_PENDING if the result is not ready yet.
 124   // A status code other than OK and ERR_IO_PENDING will cancel the request and
 125   // report the status code as the reason.
 126   //
 127   // The default implementation returns OK (continue with request).
 128   virtual int OnBeforeURLRequest(URLRequest* request,
 129                                  const CompletionCallback& callback,
 130                                  GURL* new_url);
 131
 132   // Called as the proxy is being resolved for |url|. Allows the delegate to
 133   // override the proxy resolution decision made by ProxyService. The delegate
 134   // may override the decision by modifying the ProxyInfo |result|.
 135   virtual void OnResolveProxy(const GURL& url,
 136                               int load_flags,
 137                               const ProxyService& proxy_service,
 138                               ProxyInfo* result);
 139
 140   // Called when use of |bad_proxy| fails due to |net_error|. |net_error| is
 141   // the network error encountered, if any, and OK if the fallback was
 142   // for a reason other than a network error (e.g. the proxy service was
 143   // explicitly directed to skip a proxy).
 144   virtual void OnProxyFallback(const ProxyServer& bad_proxy,
 145                                int net_error);
 146
 147   // Called right before the HTTP headers are sent. Allows the delegate to
 148   // read/write |headers| before they get sent out. |callback| and |headers| are
 149   // valid only until OnCompleted or OnURLRequestDestroyed is called for this
 150   // request.
 151   // See OnBeforeURLRequest for return value description. Returns OK by default.
 152   virtual int OnBeforeSendHeaders(URLRequest* request,
 153                                   const CompletionCallback& callback,
 154                                   HttpRequestHeaders* headers);
 155
 156   // Called after a proxy connection. Allows the delegate to read/write
 157   // |headers| before they get sent out. |headers| is valid only until
 158   // OnCompleted or OnURLRequestDestroyed is called for this request.
 159   virtual void OnBeforeSendProxyHeaders(URLRequest* request,
 160                                         const ProxyInfo& proxy_info,
 161                                         HttpRequestHeaders* headers);
 162
 163   // Called right before the HTTP request(s) are being sent to the network.
 164   // |headers| is only valid until OnCompleted or OnURLRequestDestroyed is
 165   // called for this request.
 166   virtual void OnSendHeaders(URLRequest* request,
 167                              const HttpRequestHeaders& headers);
 168
 169   // Called for HTTP requests when the headers have been received.
 170   // |original_response_headers| contains the headers as received over the
 171   // network, these must not be modified. |override_response_headers| can be set
 172   // to new values, that should be considered as overriding
 173   // |original_response_headers|.
 174   // If the response is a redirect, and the Location response header value is
 175   // identical to |allowed_unsafe_redirect_url|, then the redirect is never
 176   // blocked and the reference fragment is not copied from the original URL
 177   // to the redirection target.
 178   //
 179   // |callback|, |original_response_headers|, and |override_response_headers|
 180   // are only valid until OnURLRequestDestroyed is called for this request.
 181   // See OnBeforeURLRequest for return value description. Returns OK by default.
 182   virtual int OnHeadersReceived(
 183       URLRequest* request,
 184       const CompletionCallback& callback,
 185       const HttpResponseHeaders* original_response_headers,
 186       scoped_refptr<HttpResponseHeaders>* override_response_headers,
 187       GURL* allowed_unsafe_redirect_url);
 188
 189   // Called right after a redirect response code was received.
 190   // |new_location| is only valid until OnURLRequestDestroyed is called for this
 191   // request.
 192   virtual void OnBeforeRedirect(URLRequest* request,
 193                                 const GURL& new_location);
 194
 195   // This corresponds to URLRequestDelegate::OnResponseStarted.
 196   virtual void OnResponseStarted(URLRequest* request);
 197
 198   // Called every time we read raw bytes.
 199   virtual void OnRawBytesRead(const URLRequest& request, int bytes_read);
 200
 201   // Indicates that the URL request has been completed or failed.
 202   // |started| indicates whether the request has been started. If false,
 203   // some information like the socket address is not available.
 204   virtual void OnCompleted(URLRequest* request, bool started);
 205
 206   // Called when an URLRequest is being destroyed. Note that the request is
 207   // being deleted, so it's not safe to call any methods that may result in
 208   // a virtual method call.
 209   virtual void OnURLRequestDestroyed(URLRequest* request);
 210
 211   // Corresponds to ProxyResolverJSBindings::OnError.
 212   virtual void OnPACScriptError(int line_number,
 213                                 const base::string16& error);
 214
 215   // Called when a request receives an authentication challenge
 216   // specified by |auth_info|, and is unable to respond using cached
 217   // credentials. |callback| and |credentials| must be non-NULL, and must
 218   // be valid until OnURLRequestDestroyed is called for |request|.
 219   //
 220   // The following return values are allowed:
 221   //  - AUTH_REQUIRED_RESPONSE_NO_ACTION: |auth_info| is observed, but
 222   //    no action is being taken on it.
 223   //  - AUTH_REQUIRED_RESPONSE_SET_AUTH: |credentials| is filled in with
 224   //    a username and password, which should be used in a response to
 225   //    |auth_info|.
 226   //  - AUTH_REQUIRED_RESPONSE_CANCEL_AUTH: The authentication challenge
 227   //    should not be attempted.
 228   //  - AUTH_REQUIRED_RESPONSE_IO_PENDING: The action will be decided
 229   //    asynchronously. |callback| will be invoked when the decision is made,
 230   //    and one of the other AuthRequiredResponse values will be passed in with
 231   //    the same semantics as described above.
 232   virtual AuthRequiredResponse OnAuthRequired(
 233       URLRequest* request,
 234       const AuthChallengeInfo& auth_info,
 235       const AuthCallback& callback,
 236       AuthCredentials* credentials);
 237
 238   // Called when reading cookies to allow the network delegate to block access
 239   // to the cookie. This method will never be invoked when
 240   // LOAD_DO_NOT_SEND_COOKIES is specified.
 241   virtual bool OnCanGetCookies(const URLRequest& request,
 242                                const CookieList& cookie_list);
 243
 244   // Called when a cookie is set to allow the network delegate to block access
 245   // to the cookie. This method will never be invoked when
 246   // LOAD_DO_NOT_SAVE_COOKIES is specified.
 247   virtual bool OnCanSetCookie(const URLRequest& request,
 248                               const std::string& cookie_line,
 249                               CookieOptions* options);
 250
 251   // Called when a file access is attempted to allow the network delegate to
 252   // allow or block access to the given file path.  Returns true if access is
 253   // allowed.
 254   virtual bool OnCanAccessFile(const URLRequest& request,
 255                                const base::FilePath& path) const;
 256
 257   // Returns true if the given request may be rejected when the
 258   // URLRequestThrottlerManager believes the server servicing the
 259   // request is overloaded or down.
 260   virtual bool OnCanThrottleRequest(const URLRequest& request) const;
 261
 262   // Returns true if the given |url| has to be requested over connection that
 263   // is not tracked by the server. Usually is false, unless user privacy
 264   // settings block cookies from being get or set.
 265   virtual bool OnCanEnablePrivacyMode(
 266       const GURL& url,
 267       const GURL& first_party_for_cookies) const;
 268
 269   // Called before a SocketStream tries to connect.
 270   // See OnBeforeURLRequest for return value description. Returns OK by default.
 271   virtual int OnBeforeSocketStreamConnect(
 272       SocketStream* socket, const CompletionCallback& callback);
 273 };
 274
 275 }  // namespace net
 276
 277 #endif  // NET_BASE_NETWORK_DELEGATE_H_