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