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