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
17class GURL;
18
19namespace base {
20class FilePath;
21}
22
23namespace 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.
35class CookieOptions;
36class HttpRequestHeaders;
37class HttpResponseHeaders;
38class SocketStream;
39class URLRequest;
40
41class 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_
252