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 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   //
 122   // The default implementation returns OK (continue with request).
 123   virtual int OnBeforeURLRequest(URLRequest* request,
 124                                  const CompletionCallback& callback,
 125                                  GURL* new_url);
 126
 127   // Called right before the HTTP headers are sent. Allows the delegate to
 128   // read/write |headers| before they get sent out. |callback| and |headers| are
 129   // valid only until OnCompleted or OnURLRequestDestroyed is called for this
 130   // request.
 131   // See OnBeforeURLRequest for return value description. Returns OK by default.
 132   virtual int OnBeforeSendHeaders(URLRequest* request,
 133                                   const CompletionCallback& callback,
 134                                   HttpRequestHeaders* headers);
 135
 136   // Called right before the HTTP request(s) are being sent to the network.
 137   // |headers| is only valid until OnCompleted or OnURLRequestDestroyed is
 138   // called for this request.
 139   virtual void OnSendHeaders(URLRequest* request,
 140                              const HttpRequestHeaders& headers);
 141
 142   // Called for HTTP requests when the headers have been received.
 143   // |original_response_headers| contains the headers as received over the
 144   // network, these must not be modified. |override_response_headers| can be set
 145   // to new values, that should be considered as overriding
 146   // |original_response_headers|.
 147   // |callback|, |original_response_headers|, and |override_response_headers|
 148   // are only valid until OnURLRequestDestroyed is called for this request.
 149   // See OnBeforeURLRequest for return value description. Returns OK by default.
 150   virtual int OnHeadersReceived(
 151       URLRequest* request,
 152       const CompletionCallback& callback,
 153       const HttpResponseHeaders* original_response_headers,
 154       scoped_refptr<HttpResponseHeaders>* override_response_headers);
 155
 156   // Called right after a redirect response code was received.
 157   // |new_location| is only valid until OnURLRequestDestroyed is called for this
 158   // request.
 159   virtual void OnBeforeRedirect(URLRequest* request,
 160                                 const GURL& new_location);
 161
 162   // This corresponds to URLRequestDelegate::OnResponseStarted.
 163   virtual void OnResponseStarted(URLRequest* request);
 164
 165   // Called every time we read raw bytes.
 166   virtual void OnRawBytesRead(const URLRequest& request, int bytes_read);
 167
 168   // Indicates that the URL request has been completed or failed.
 169   // |started| indicates whether the request has been started. If false,
 170   // some information like the socket address is not available.
 171   virtual void OnCompleted(URLRequest* request, bool started);
 172
 173   // Called when an URLRequest is being destroyed. Note that the request is
 174   // being deleted, so it's not safe to call any methods that may result in
 175   // a virtual method call.
 176   virtual void OnURLRequestDestroyed(URLRequest* request);
 177
 178   // Corresponds to ProxyResolverJSBindings::OnError.
 179   virtual void OnPACScriptError(int line_number,
 180                                 const base::string16& error);
 181
 182   // Called when a request receives an authentication challenge
 183   // specified by |auth_info|, and is unable to respond using cached
 184   // credentials. |callback| and |credentials| must be non-NULL, and must
 185   // be valid until OnURLRequestDestroyed is called for |request|.
 186   //
 187   // The following return values are allowed:
 188   //  - AUTH_REQUIRED_RESPONSE_NO_ACTION: |auth_info| is observed, but
 189   //    no action is being taken on it.
 190   //  - AUTH_REQUIRED_RESPONSE_SET_AUTH: |credentials| is filled in with
 191   //    a username and password, which should be used in a response to
 192   //    |auth_info|.
 193   //  - AUTH_REQUIRED_RESPONSE_CANCEL_AUTH: The authentication challenge
 194   //    should not be attempted.
 195   //  - AUTH_REQUIRED_RESPONSE_IO_PENDING: The action will be decided
 196   //    asynchronously. |callback| will be invoked when the decision is made,
 197   //    and one of the other AuthRequiredResponse values will be passed in with
 198   //    the same semantics as described above.
 199   virtual AuthRequiredResponse OnAuthRequired(
 200       URLRequest* request,
 201       const AuthChallengeInfo& auth_info,
 202       const AuthCallback& callback,
 203       AuthCredentials* credentials);
 204
 205   // Called when reading cookies to allow the network delegate to block access
 206   // to the cookie. This method will never be invoked when
 207   // LOAD_DO_NOT_SEND_COOKIES is specified.
 208   virtual bool OnCanGetCookies(const URLRequest& request,
 209                                const CookieList& cookie_list);
 210
 211   // Called when a cookie is set to allow the network delegate to block access
 212   // to the cookie. This method will never be invoked when
 213   // LOAD_DO_NOT_SAVE_COOKIES is specified.
 214   virtual bool OnCanSetCookie(const URLRequest& request,
 215                               const std::string& cookie_line,
 216                               CookieOptions* options);
 217
 218   // Called when a file access is attempted to allow the network delegate to
 219   // allow or block access to the given file path.  Returns true if access is
 220   // allowed.
 221   virtual bool OnCanAccessFile(const URLRequest& request,
 222                                const base::FilePath& path) const;
 223
 224   // Returns true if the given request may be rejected when the
 225   // URLRequestThrottlerManager believes the server servicing the
 226   // request is overloaded or down.
 227   virtual bool OnCanThrottleRequest(const URLRequest& request) const;
 228
 229   // Returns true if the given |url| has to be requested over connection that
 230   // is not tracked by the server. Usually is false, unless user privacy
 231   // settings block cookies from being get or set.
 232   virtual bool OnCanEnablePrivacyMode(
 233       const GURL& url,
 234       const GURL& first_party_for_cookies) const;
 235
 236   // Called before a SocketStream tries to connect.
 237   // See OnBeforeURLRequest for return value description. Returns OK by default.
 238   virtual int OnBeforeSocketStreamConnect(
 239       SocketStream* socket, const CompletionCallback& callback);
 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);
 247 };
 248
 249 }  // namespace net
 250
 251 #endif  // NET_BASE_NETWORK_DELEGATE_H_