Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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_URL_REQUEST_URL_FETCHER_H_ |
| 6 | #define NET_URL_REQUEST_URL_FETCHER_H_ |
| 7 | |
| 8 | #include <string> |
| 9 | #include <vector> |
| 10 | |
| 11 | #include "base/callback_forward.h" |
| 12 | #include "base/memory/ref_counted.h" |
Torne (Richard Coles) | 4e180b6 | 2013-10-18 15:46:22 +0100 | [diff] [blame] | 13 | #include "base/memory/scoped_ptr.h" |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 14 | #include "base/supports_user_data.h" |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 15 | #include "net/base/net_export.h" |
Torne (Richard Coles) | 5d1f7b1 | 2014-02-21 12:16:55 +0000 | [diff] [blame] | 16 | #include "net/url_request/url_request.h" |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 17 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 18 | class GURL; |
| 19 | |
| 20 | namespace base { |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 21 | class FilePath; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 22 | class MessageLoopProxy; |
Torne (Richard Coles) | f2477e0 | 2013-11-28 11:55:43 +0000 | [diff] [blame] | 23 | class SequencedTaskRunner; |
| 24 | class TaskRunner; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 25 | class TimeDelta; |
| 26 | } |
| 27 | |
| 28 | namespace net { |
| 29 | class HostPortPair; |
| 30 | class HttpRequestHeaders; |
| 31 | class HttpResponseHeaders; |
| 32 | class URLFetcherDelegate; |
Torne (Richard Coles) | 4e180b6 | 2013-10-18 15:46:22 +0100 | [diff] [blame] | 33 | class URLFetcherResponseWriter; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 34 | class URLRequestContextGetter; |
| 35 | class URLRequestStatus; |
| 36 | typedef std::vector<std::string> ResponseCookies; |
| 37 | |
| 38 | // To use this class, create an instance with the desired URL and a pointer to |
| 39 | // the object to be notified when the URL has been loaded: |
Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 40 | // scoped_ptr<URLFetcher> fetcher(URLFetcher::Create("http://www.google.com", |
| 41 | // URLFetcher::GET, |
| 42 | // this)); |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 43 | // |
| 44 | // You must also set a request context getter: |
| 45 | // |
| 46 | // fetcher->SetRequestContext(&my_request_context_getter); |
| 47 | // |
| 48 | // Then, optionally set properties on this object, like the request context or |
| 49 | // extra headers: |
| 50 | // fetcher->set_extra_request_headers("X-Foo: bar"); |
| 51 | // |
| 52 | // Finally, start the request: |
| 53 | // fetcher->Start(); |
| 54 | // |
Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 55 | // You may cancel the request by destroying the URLFetcher: |
| 56 | // fetcher.reset(); |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 57 | // |
| 58 | // The object you supply as a delegate must inherit from |
| 59 | // URLFetcherDelegate; when the fetch is completed, |
| 60 | // OnURLFetchComplete() will be called with a pointer to the URLFetcher. From |
| 61 | // that point until the original URLFetcher instance is destroyed, you may use |
| 62 | // accessor methods to see the result of the fetch. You should copy these |
| 63 | // objects if you need them to live longer than the URLFetcher instance. If the |
| 64 | // URLFetcher instance is destroyed before the callback happens, the fetch will |
| 65 | // be canceled and no callback will occur. |
| 66 | // |
| 67 | // You may create the URLFetcher instance on any thread; OnURLFetchComplete() |
| 68 | // will be called back on the same thread you use to create the instance. |
| 69 | // |
| 70 | // |
| 71 | // NOTE: By default URLFetcher requests are NOT intercepted, except when |
| 72 | // interception is explicitly enabled in tests. |
| 73 | class NET_EXPORT URLFetcher { |
| 74 | public: |
| 75 | // Imposible http response code. Used to signal that no http response code |
| 76 | // was received. |
| 77 | enum ResponseCode { |
| 78 | RESPONSE_CODE_INVALID = -1 |
| 79 | }; |
| 80 | |
| 81 | enum RequestType { |
| 82 | GET, |
| 83 | POST, |
| 84 | HEAD, |
| 85 | DELETE_REQUEST, // DELETE is already taken on Windows. |
| 86 | // <winnt.h> defines a DELETE macro. |
| 87 | PUT, |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 88 | PATCH, |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 89 | }; |
| 90 | |
| 91 | // Used by SetURLRequestUserData. The callback should make a fresh |
| 92 | // base::SupportsUserData::Data object every time it's called. |
| 93 | typedef base::Callback<base::SupportsUserData::Data*()> CreateDataCallback; |
| 94 | |
| 95 | virtual ~URLFetcher(); |
| 96 | |
| 97 | // |url| is the URL to send the request to. |
| 98 | // |request_type| is the type of request to make. |
| 99 | // |d| the object that will receive the callback on fetch completion. |
Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 100 | // Caller is responsible for destroying the returned URLFetcher. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 101 | static URLFetcher* Create(const GURL& url, |
| 102 | URLFetcher::RequestType request_type, |
| 103 | URLFetcherDelegate* d); |
| 104 | |
| 105 | // Like above, but if there's a URLFetcherFactory registered with the |
| 106 | // implementation it will be used. |id| may be used during testing to identify |
| 107 | // who is creating the URLFetcher. |
Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 108 | // Caller is responsible for destroying the returned URLFetcher. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 109 | static URLFetcher* Create(int id, |
| 110 | const GURL& url, |
| 111 | URLFetcher::RequestType request_type, |
| 112 | URLFetcherDelegate* d); |
| 113 | |
| 114 | // Cancels all existing URLFetchers. Will notify the URLFetcherDelegates. |
| 115 | // Note that any new URLFetchers created while this is running will not be |
| 116 | // cancelled. Typically, one would call this in the CleanUp() method of an IO |
| 117 | // thread, so that no new URLRequests would be able to start on the IO thread |
| 118 | // anyway. This doesn't prevent new URLFetchers from trying to post to the IO |
| 119 | // thread though, even though the task won't ever run. |
| 120 | static void CancelAll(); |
| 121 | |
| 122 | // Normally interception is disabled for URLFetcher, but you can use this |
| 123 | // to enable it for tests. Also see ScopedURLFetcherFactory for another way |
| 124 | // of testing code that uses an URLFetcher. |
| 125 | static void SetEnableInterceptionForTests(bool enabled); |
| 126 | |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 127 | // Normally, URLFetcher will abort loads that request SSL client certificate |
| 128 | // authentication, but this method may be used to cause URLFetchers to ignore |
| 129 | // requests for client certificates and continue anonymously. Because such |
| 130 | // behaviour affects the URLRequestContext's shared network state and socket |
| 131 | // pools, it should only be used for testing. |
| 132 | static void SetIgnoreCertificateRequests(bool ignored); |
| 133 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 134 | // Sets data only needed by POSTs. All callers making POST requests should |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 135 | // call one of the SetUpload* methods before the request is started. |
| 136 | // |upload_content_type| is the MIME type of the content, while |
| 137 | // |upload_content| is the data to be sent (the Content-Length header value |
| 138 | // will be set to the length of this data). |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 139 | virtual void SetUploadData(const std::string& upload_content_type, |
| 140 | const std::string& upload_content) = 0; |
| 141 | |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 142 | // Sets data only needed by POSTs. All callers making POST requests should |
| 143 | // call one of the SetUpload* methods before the request is started. |
| 144 | // |upload_content_type| is the MIME type of the content, while |
| 145 | // |file_path| is the path to the file containing the data to be sent (the |
| 146 | // Content-Length header value will be set to the length of this file). |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 147 | // |range_offset| and |range_length| specify the range of the part |
| 148 | // to be uploaded. To upload the whole file, (0, kuint64max) can be used. |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 149 | // |file_task_runner| will be used for all file operations. |
| 150 | virtual void SetUploadFilePath( |
| 151 | const std::string& upload_content_type, |
| 152 | const base::FilePath& file_path, |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 153 | uint64 range_offset, |
| 154 | uint64 range_length, |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 155 | scoped_refptr<base::TaskRunner> file_task_runner) = 0; |
| 156 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 157 | // Indicates that the POST data is sent via chunked transfer encoding. |
| 158 | // This may only be called before calling Start(). |
| 159 | // Use AppendChunkToUpload() to give the data chunks after calling Start(). |
| 160 | virtual void SetChunkedUpload(const std::string& upload_content_type) = 0; |
| 161 | |
| 162 | // Adds the given bytes to a request's POST data transmitted using chunked |
| 163 | // transfer encoding. |
| 164 | // This method should be called ONLY after calling Start(). |
| 165 | virtual void AppendChunkToUpload(const std::string& data, |
| 166 | bool is_last_chunk) = 0; |
| 167 | |
| 168 | // Set one or more load flags as defined in net/base/load_flags.h. Must be |
| 169 | // called before the request is started. |
| 170 | virtual void SetLoadFlags(int load_flags) = 0; |
| 171 | |
| 172 | // Returns the current load flags. |
| 173 | virtual int GetLoadFlags() const = 0; |
| 174 | |
| 175 | // The referrer URL for the request. Must be called before the request is |
| 176 | // started. |
| 177 | virtual void SetReferrer(const std::string& referrer) = 0; |
| 178 | |
Torne (Richard Coles) | 5d1f7b1 | 2014-02-21 12:16:55 +0000 | [diff] [blame] | 179 | // The referrer policy to apply when updating the referrer during redirects. |
| 180 | // The referrer policy may only be changed before Start() is called. |
| 181 | virtual void SetReferrerPolicy( |
| 182 | URLRequest::ReferrerPolicy referrer_policy) = 0; |
| 183 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 184 | // Set extra headers on the request. Must be called before the request |
| 185 | // is started. |
| 186 | // This replaces the entire extra request headers. |
| 187 | virtual void SetExtraRequestHeaders( |
| 188 | const std::string& extra_request_headers) = 0; |
| 189 | |
| 190 | // Add header (with format field-name ":" [ field-value ]) to the request |
| 191 | // headers. Must be called before the request is started. |
| 192 | // This appends the header to the current extra request headers. |
| 193 | virtual void AddExtraRequestHeader(const std::string& header_line) = 0; |
| 194 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 195 | // Set the URLRequestContext on the request. Must be called before the |
| 196 | // request is started. |
| 197 | virtual void SetRequestContext( |
| 198 | URLRequestContextGetter* request_context_getter) = 0; |
| 199 | |
| 200 | // Set the URL that should be consulted for the third-party cookie |
| 201 | // blocking policy. |
| 202 | virtual void SetFirstPartyForCookies( |
| 203 | const GURL& first_party_for_cookies) = 0; |
| 204 | |
| 205 | // Set the key and data callback that is used when setting the user |
| 206 | // data on any URLRequest objects this object creates. |
| 207 | virtual void SetURLRequestUserData( |
| 208 | const void* key, |
| 209 | const CreateDataCallback& create_data_callback) = 0; |
| 210 | |
| 211 | // If |stop_on_redirect| is true, 3xx responses will cause the fetch to halt |
| 212 | // immediately rather than continue through the redirect. OnURLFetchComplete |
| 213 | // will be called, with the URLFetcher's URL set to the redirect destination, |
| 214 | // its status set to CANCELED, and its response code set to the relevant 3xx |
| 215 | // server response code. |
| 216 | virtual void SetStopOnRedirect(bool stop_on_redirect) = 0; |
| 217 | |
| 218 | // If |retry| is false, 5xx responses will be propagated to the observer, |
| 219 | // if it is true URLFetcher will automatically re-execute the request, |
| 220 | // after backoff_delay() elapses. URLFetcher has it set to true by default. |
| 221 | virtual void SetAutomaticallyRetryOn5xx(bool retry) = 0; |
| 222 | |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 223 | virtual void SetMaxRetriesOn5xx(int max_retries) = 0; |
| 224 | virtual int GetMaxRetriesOn5xx() const = 0; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 225 | |
| 226 | // Returns the back-off delay before the request will be retried, |
| 227 | // when a 5xx response was received. |
| 228 | virtual base::TimeDelta GetBackoffDelay() const = 0; |
| 229 | |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 230 | // Retries up to |max_retries| times when requests fail with |
| 231 | // ERR_NETWORK_CHANGED. If ERR_NETWORK_CHANGED is received after having |
| 232 | // retried |max_retries| times then it is propagated to the observer. |
| 233 | virtual void SetAutomaticallyRetryOnNetworkChanges(int max_retries) = 0; |
| 234 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 235 | // By default, the response is saved in a string. Call this method to save the |
| 236 | // response to a file instead. Must be called before Start(). |
| 237 | // |file_task_runner| will be used for all file operations. |
| 238 | // To save to a temporary file, use SaveResponseToTemporaryFile(). |
| 239 | // The created file is removed when the URLFetcher is deleted unless you |
| 240 | // take ownership by calling GetResponseAsFilePath(). |
| 241 | virtual void SaveResponseToFileAtPath( |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 242 | const base::FilePath& file_path, |
Torne (Richard Coles) | f2477e0 | 2013-11-28 11:55:43 +0000 | [diff] [blame] | 243 | scoped_refptr<base::SequencedTaskRunner> file_task_runner) = 0; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 244 | |
| 245 | // By default, the response is saved in a string. Call this method to save the |
| 246 | // response to a temporary file instead. Must be called before Start(). |
| 247 | // |file_task_runner| will be used for all file operations. |
| 248 | // The created file is removed when the URLFetcher is deleted unless you |
| 249 | // take ownership by calling GetResponseAsFilePath(). |
| 250 | virtual void SaveResponseToTemporaryFile( |
Torne (Richard Coles) | f2477e0 | 2013-11-28 11:55:43 +0000 | [diff] [blame] | 251 | scoped_refptr<base::SequencedTaskRunner> file_task_runner) = 0; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 252 | |
Torne (Richard Coles) | 4e180b6 | 2013-10-18 15:46:22 +0100 | [diff] [blame] | 253 | // By default, the response is saved in a string. Call this method to use the |
| 254 | // specified writer to save the response. Must be called before Start(). |
| 255 | virtual void SaveResponseWithWriter( |
| 256 | scoped_ptr<URLFetcherResponseWriter> response_writer) = 0; |
| 257 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 258 | // Retrieve the response headers from the request. Must only be called after |
| 259 | // the OnURLFetchComplete callback has run. |
| 260 | virtual HttpResponseHeaders* GetResponseHeaders() const = 0; |
| 261 | |
| 262 | // Retrieve the remote socket address from the request. Must only |
| 263 | // be called after the OnURLFetchComplete callback has run and if |
| 264 | // the request has not failed. |
| 265 | virtual HostPortPair GetSocketAddress() const = 0; |
| 266 | |
| 267 | // Returns true if the request was delivered through a proxy. Must only |
| 268 | // be called after the OnURLFetchComplete callback has run and the request |
| 269 | // has not failed. |
| 270 | virtual bool WasFetchedViaProxy() const = 0; |
| 271 | |
| 272 | // Start the request. After this is called, you may not change any other |
| 273 | // settings. |
| 274 | virtual void Start() = 0; |
| 275 | |
| 276 | // Return the URL that we were asked to fetch. |
| 277 | virtual const GURL& GetOriginalURL() const = 0; |
| 278 | |
| 279 | // Return the URL that this fetcher is processing. |
| 280 | virtual const GURL& GetURL() const = 0; |
| 281 | |
| 282 | // The status of the URL fetch. |
| 283 | virtual const URLRequestStatus& GetStatus() const = 0; |
| 284 | |
| 285 | // The http response code received. Will return RESPONSE_CODE_INVALID |
| 286 | // if an error prevented any response from being received. |
| 287 | virtual int GetResponseCode() const = 0; |
| 288 | |
Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 289 | // Cookies received. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 290 | virtual const ResponseCookies& GetCookies() const = 0; |
| 291 | |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 292 | // Reports that the received content was malformed. |
| 293 | virtual void ReceivedContentWasMalformed() = 0; |
| 294 | |
| 295 | // Get the response as a string. Return false if the fetcher was not |
| 296 | // set to store the response as a string. |
| 297 | virtual bool GetResponseAsString(std::string* out_response_string) const = 0; |
| 298 | |
| 299 | // Get the path to the file containing the response body. Returns false |
| 300 | // if the response body was not saved to a file. If take_ownership is |
| 301 | // true, caller takes responsibility for the file, and it will not |
| 302 | // be removed once the URLFetcher is destroyed. User should not take |
| 303 | // ownership more than once, or call this method after taking ownership. |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 304 | virtual bool GetResponseAsFilePath( |
| 305 | bool take_ownership, |
| 306 | base::FilePath* out_response_path) const = 0; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 307 | }; |
| 308 | |
| 309 | } // namespace net |
| 310 | |
| 311 | #endif // NET_URL_REQUEST_URL_FETCHER_H_ |