OLD | NEW |
---|---|
1 // Copyright (c) 2011 The Chromium Authors. All rights reserved. | 1 // Copyright (c) 2011 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 // This file contains URLFetcher, a wrapper around net::URLRequest that handles | 5 // This file contains URLFetcher, a wrapper around net::URLRequest that handles |
6 // low-level details like thread safety, ref counting, and incremental buffer | 6 // low-level details like thread safety, ref counting, and incremental buffer |
7 // reading. This is useful for callers who simply want to get the data from a | 7 // reading. This is useful for callers who simply want to get the data from a |
8 // URL and don't care about all the nitty-gritty details. | 8 // URL and don't care about all the nitty-gritty details. |
9 // | 9 // |
10 // NOTE(willchan): Only one "IO" thread is supported for URLFetcher. This is a | 10 // NOTE(willchan): Only one "IO" thread is supported for URLFetcher. This is a |
11 // temporary situation. We will work on allowing support for multiple "io" | 11 // temporary situation. We will work on allowing support for multiple "io" |
12 // threads per process. | 12 // threads per process. |
13 | 13 |
14 #ifndef CHROME_COMMON_NET_URL_FETCHER_H_ | 14 #ifndef CHROME_COMMON_NET_URL_FETCHER_H_ |
15 #define CHROME_COMMON_NET_URL_FETCHER_H_ | 15 #define CHROME_COMMON_NET_URL_FETCHER_H_ |
16 #pragma once | 16 #pragma once |
17 | 17 |
18 #include <string> | 18 #include <string> |
19 #include <vector> | 19 #include <vector> |
20 | 20 |
21 #include "base/memory/ref_counted.h" | 21 #include "base/memory/ref_counted.h" |
22 #include "base/message_loop.h" | 22 #include "base/message_loop.h" |
23 #include "base/platform_file.h" | |
23 #include "base/time.h" | 24 #include "base/time.h" |
24 | 25 |
26 class FilePath; | |
25 class GURL; | 27 class GURL; |
26 | 28 |
29 namespace base { | |
30 class MessageLoopProxy; | |
31 } // namespace base | |
32 | |
27 namespace net { | 33 namespace net { |
28 class HostPortPair; | 34 class HostPortPair; |
29 class HttpResponseHeaders; | 35 class HttpResponseHeaders; |
30 class URLRequestContextGetter; | 36 class URLRequestContextGetter; |
31 class URLRequestStatus; | 37 class URLRequestStatus; |
32 typedef std::vector<std::string> ResponseCookies; | 38 typedef std::vector<std::string> ResponseCookies; |
33 } // namespace net | 39 } // namespace net |
34 | 40 |
35 // To use this class, create an instance with the desired URL and a pointer to | 41 // To use this class, create an instance with the desired URL and a pointer to |
36 // the object to be notified when the URL has been loaded: | 42 // the object to be notified when the URL has been loaded: |
37 // URLFetcher* fetcher = new URLFetcher("http://www.google.com", | 43 // URLFetcher* fetcher = new URLFetcher("http://www.google.com", |
38 // URLFetcher::GET, this); | 44 // URLFetcher::GET, this); |
39 // | 45 // |
40 // Then, optionally set properties on this object, like the request context or | 46 // Then, optionally set properties on this object, like the request context or |
41 // extra headers: | 47 // extra headers: |
42 // fetcher->SetExtraRequestHeaders("X-Foo: bar"); | 48 // fetcher->SetExtraRequestHeaders("X-Foo: bar"); |
43 // | 49 // |
44 // Finally, start the request: | 50 // Finally, start the request: |
45 // fetcher->Start(); | 51 // fetcher->Start(); |
46 // | 52 // |
53 // | |
47 // The object you supply as a delegate must inherit from URLFetcher::Delegate; | 54 // The object you supply as a delegate must inherit from URLFetcher::Delegate; |
48 // when the fetch is completed, OnURLFetchComplete() will be called with the | 55 // when the fetch is completed, OnURLFetchComplete() will be called with a |
49 // resulting status and (if applicable) HTTP response code. From that point | 56 // pointer to the URLFetcher. From that point until the original URLFetcher |
50 // until the original URLFetcher instance is destroyed, you may examine the | 57 // instance is destroyed, you may use accessor methods to see the result of |
51 // provided status and data for the URL. (You should copy these objects if you | 58 // the fetch. You should copy these objects if you need them to live longer |
52 // need them to live longer than the URLFetcher instance.) If the URLFetcher | 59 // than the URLFetcher instance. If the URLFetcher instance is destroyed |
53 // instance is destroyed before the callback happens, the fetch will be | 60 // before the callback happens, the fetch will be canceled and no callback |
54 // canceled and no callback will occur. | 61 // will occur. |
55 // | 62 // |
56 // You may create the URLFetcher instance on any thread; OnURLFetchComplete() | 63 // You may create the URLFetcher instance on any thread; OnURLFetchComplete() |
57 // will be called back on the same thread you use to create the instance. | 64 // will be called back on the same thread you use to create the instance. |
58 // | 65 // |
59 // | 66 // |
60 // NOTE: By default URLFetcher requests are NOT intercepted, except when | 67 // NOTE: By default URLFetcher requests are NOT intercepted, except when |
61 // interception is explicitly enabled in tests. | 68 // interception is explicitly enabled in tests. |
62 | 69 |
63 class URLFetcher { | 70 class URLFetcher { |
64 public: | 71 public: |
65 enum RequestType { | 72 enum RequestType { |
66 GET, | 73 GET, |
67 POST, | 74 POST, |
68 HEAD, | 75 HEAD, |
69 }; | 76 }; |
70 | 77 |
78 // Imposible http response code. Used to signal that no http response code | |
79 // was received. | |
80 static const int kInvalidHttpResponseCode; | |
81 | |
71 class Delegate { | 82 class Delegate { |
72 public: | 83 public: |
73 // This will be called when the URL has been fetched, successfully or not. | 84 // TODO(skerner): This will be removed in favor of the |source|-only |
74 // |response_code| is the HTTP response code (200, 404, etc.) if | 85 // version below. Leaving this for now to make the initial code review |
75 // applicable. |url|, |status| and |data| are all valid until the | 86 // easy to read. |
76 // URLFetcher instance is destroyed. | |
77 virtual void OnURLFetchComplete(const URLFetcher* source, | 87 virtual void OnURLFetchComplete(const URLFetcher* source, |
78 const GURL& url, | 88 const GURL& url, |
79 const net::URLRequestStatus& status, | 89 const net::URLRequestStatus& status, |
80 int response_code, | 90 int response_code, |
81 const net::ResponseCookies& cookies, | 91 const net::ResponseCookies& cookies, |
82 const std::string& data) = 0; | 92 const std::string& data); |
93 | |
94 // This will be called when the URL has been fetched, successfully or not. | |
95 // Use accessor methods on |source| to get the results. | |
96 virtual void OnURLFetchComplete(const URLFetcher* source); | |
83 | 97 |
84 protected: | 98 protected: |
85 virtual ~Delegate() {} | 99 virtual ~Delegate() {} |
86 }; | 100 }; |
87 | 101 |
88 // URLFetcher::Create uses the currently registered Factory to create the | 102 // URLFetcher::Create uses the currently registered Factory to create the |
89 // URLFetcher. Factory is intended for testing. | 103 // URLFetcher. Factory is intended for testing. |
90 class Factory { | 104 class Factory { |
91 public: | 105 public: |
92 virtual URLFetcher* CreateURLFetcher(int id, | 106 virtual URLFetcher* CreateURLFetcher(int id, |
(...skipping 83 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
176 // when a 5xx response was received. | 190 // when a 5xx response was received. |
177 base::TimeDelta backoff_delay() const { return backoff_delay_; } | 191 base::TimeDelta backoff_delay() const { return backoff_delay_; } |
178 | 192 |
179 // Sets the back-off delay, allowing to mock 5xx requests in unit-tests. | 193 // Sets the back-off delay, allowing to mock 5xx requests in unit-tests. |
180 #if defined(UNIT_TEST) | 194 #if defined(UNIT_TEST) |
181 void set_backoff_delay(base::TimeDelta backoff_delay) { | 195 void set_backoff_delay(base::TimeDelta backoff_delay) { |
182 backoff_delay_ = backoff_delay; | 196 backoff_delay_ = backoff_delay; |
183 } | 197 } |
184 #endif // defined(UNIT_TEST) | 198 #endif // defined(UNIT_TEST) |
185 | 199 |
200 // By default, the response is saved in a string. Call this method to save the | |
201 // response to a temporary file instead. Must be called before Start(). | |
202 // User must also call set_file_message_loop_proxy() to give the thread on | |
203 // which file operations may be done. | |
204 void SaveResponseToTemporaryFile(); | |
asargent_no_longer_on_chrome
2011/05/18 19:00:49
Here's a thought for future cleanup along the line
Sam Kerner (Chrome)
2011/05/18 23:45:57
A good idea, but more than I can chew in this CL.
| |
205 | |
206 // Set the message loop proxy for file operations. Used to write the | |
asargent_no_longer_on_chrome
2011/05/18 19:00:49
Are there other file operations that this would ap
Sam Kerner (Chrome)
2011/05/18 23:45:57
Done.
| |
207 // response to a file. | |
208 void set_file_message_loop_proxy( | |
209 scoped_refptr<base::MessageLoopProxy> file_message_loop_proxy); | |
210 | |
186 // Retrieve the response headers from the request. Must only be called after | 211 // Retrieve the response headers from the request. Must only be called after |
187 // the OnURLFetchComplete callback has run. | 212 // the OnURLFetchComplete callback has run. |
188 virtual net::HttpResponseHeaders* response_headers() const; | 213 virtual net::HttpResponseHeaders* response_headers() const; |
189 | 214 |
190 // Retrieve the remote socket address from the request. Must only | 215 // Retrieve the remote socket address from the request. Must only |
191 // be called after the OnURLFetchComplete callback has run and if | 216 // be called after the OnURLFetchComplete callback has run and if |
192 // the request has not failed. | 217 // the request has not failed. |
193 net::HostPortPair socket_address() const; | 218 net::HostPortPair socket_address() const; |
194 | 219 |
195 // Returns true if the request was delivered through a proxy. Must only | 220 // Returns true if the request was delivered through a proxy. Must only |
196 // be called after the OnURLFetchComplete callback has run and the request | 221 // be called after the OnURLFetchComplete callback has run and the request |
197 // has not failed. | 222 // has not failed. |
198 bool was_fetched_via_proxy() const; | 223 bool was_fetched_via_proxy() const; |
199 | 224 |
200 // Start the request. After this is called, you may not change any other | 225 // Start the request. After this is called, you may not change any other |
201 // settings. | 226 // settings. |
202 virtual void Start(); | 227 virtual void Start(); |
203 | 228 |
204 // Return the URL that this fetcher is processing. | 229 // Return the URL that this fetcher is processing. |
205 const GURL& url() const; | 230 virtual const GURL& url() const; |
231 | |
232 // The status of the URL fetch. | |
233 virtual const net::URLRequestStatus& status() const; | |
234 | |
235 // The http response code received. Will return | |
236 // URLFetcher::kInvalidHttpResponseCode if an error prevented any response | |
237 // from being received. | |
238 virtual int response_code() const; | |
239 | |
240 // Cookies recieved. | |
241 virtual const net::ResponseCookies& cookies() const; | |
242 | |
243 // Return true if any file system operation failed. If so, set |error_code| | |
244 // to the error code. File system errors are only possible if user called | |
245 // SaveResponseToTemporaryFile(). | |
246 virtual bool FileErrorOccurred(base::PlatformFileError* out_error_code) const; | |
206 | 247 |
207 // Reports that the received content was malformed. | 248 // Reports that the received content was malformed. |
208 void ReceivedContentWasMalformed(); | 249 void ReceivedContentWasMalformed(); |
209 | 250 |
251 // Get the response as a string. Return false if the fetcher was not | |
252 // set to store the response as a string. | |
253 virtual bool GetResponseAsString(std::string* out_response_string) const; | |
254 | |
255 // Get the path to the file containing the response body. Returns false | |
256 // if the response body was not saved to a file. If take_ownership is | |
257 // true, caller takes responsibility for the temp file, and it will not | |
258 // be removed once the URLFetcher is destroyed. | |
259 virtual bool GetResponseAsFilePath(bool take_ownership, | |
260 FilePath* out_response_path) const; | |
261 | |
210 // Cancels all existing URLFetchers. Will notify the URLFetcher::Delegates. | 262 // Cancels all existing URLFetchers. Will notify the URLFetcher::Delegates. |
211 // Note that any new URLFetchers created while this is running will not be | 263 // Note that any new URLFetchers created while this is running will not be |
212 // cancelled. Typically, one would call this in the CleanUp() method of an IO | 264 // cancelled. Typically, one would call this in the CleanUp() method of an IO |
213 // thread, so that no new URLRequests would be able to start on the IO thread | 265 // thread, so that no new URLRequests would be able to start on the IO thread |
214 // anyway. This doesn't prevent new URLFetchers from trying to post to the IO | 266 // anyway. This doesn't prevent new URLFetchers from trying to post to the IO |
215 // thread though, even though the task won't ever run. | 267 // thread though, even though the task won't ever run. |
216 static void CancelAll(); | 268 static void CancelAll(); |
217 | 269 |
218 protected: | 270 protected: |
219 // Returns the delegate. | 271 // Returns the delegate. |
220 Delegate* delegate() const; | 272 Delegate* delegate() const; |
221 | 273 |
222 // Used by tests. | 274 // Used by tests. |
223 const std::string& upload_data() const; | 275 const std::string& upload_data() const; |
224 | 276 |
225 private: | 277 private: |
226 friend class URLFetcherTest; | 278 friend class URLFetcherTest; |
279 friend class TestURLFetcher; | |
280 | |
281 // How should the response be stored? | |
282 enum ResponseDestinationType { | |
283 STRING, // Default: In a std::string | |
284 TEMP_FILE // Write to a temp file | |
285 }; | |
227 | 286 |
228 // Only used by URLFetcherTest, returns the number of URLFetcher::Core objects | 287 // Only used by URLFetcherTest, returns the number of URLFetcher::Core objects |
229 // actively running. | 288 // actively running. |
230 static int GetNumFetcherCores(); | 289 static int GetNumFetcherCores(); |
231 | 290 |
232 class Core; | 291 class Core; |
233 | |
234 scoped_refptr<Core> core_; | 292 scoped_refptr<Core> core_; |
235 | 293 |
236 static Factory* factory_; | 294 static Factory* factory_; |
237 | 295 |
238 // If |automatically_retry_on_5xx_| is false, 5xx responses will be | 296 // If |automatically_retry_on_5xx_| is false, 5xx responses will be |
239 // propagated to the observer, if it is true URLFetcher will automatically | 297 // propagated to the observer, if it is true URLFetcher will automatically |
240 // re-execute the request, after the back-off delay has expired. | 298 // re-execute the request, after the back-off delay has expired. |
241 // true by default. | 299 // true by default. |
242 bool automatically_retry_on_5xx_; | 300 bool automatically_retry_on_5xx_; |
243 // Back-off time delay. 0 by default. | 301 // Back-off time delay. 0 by default. |
244 base::TimeDelta backoff_delay_; | 302 base::TimeDelta backoff_delay_; |
245 // Maximum retries allowed. | 303 // Maximum retries allowed. |
246 int max_retries_; | 304 int max_retries_; |
247 | 305 |
306 // Where should responses be saved? | |
307 ResponseDestinationType response_destination_; | |
308 | |
248 static bool g_interception_enabled; | 309 static bool g_interception_enabled; |
249 | 310 |
250 DISALLOW_COPY_AND_ASSIGN(URLFetcher); | 311 DISALLOW_COPY_AND_ASSIGN(URLFetcher); |
251 }; | 312 }; |
252 | 313 |
253 #endif // CHROME_COMMON_NET_URL_FETCHER_H_ | 314 #endif // CHROME_COMMON_NET_URL_FETCHER_H_ |
OLD | NEW |