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
3 // found in the LICENSE file.
5 #ifndef NET_URL_REQUEST_URL_REQUEST_JOB_H_
6 #define NET_URL_REQUEST_URL_REQUEST_JOB_H_
12 #include "base/memory/ref_counted.h"
13 #include "base/memory/scoped_ptr.h"
14 #include "base/string16.h"
15 #include "base/system_monitor/system_monitor.h"
16 #include "base/task.h"
17 #include "base/time.h"
18 #include "googleurl/src/gurl.h"
19 #include "net/base/filter.h"
20 #include "net/base/host_port_pair.h"
21 #include "net/base/load_states.h"
22 #include "net/base/net_export.h"
26 class AuthChallengeInfo
;
29 class HttpRequestHeaders
;
30 class HttpResponseInfo
;
32 class SSLCertRequestInfo
;
35 class URLRequestStatus
;
36 class X509Certificate
;
38 class NET_EXPORT URLRequestJob
: public base::RefCounted
<URLRequestJob
>,
39 public base::SystemMonitor::PowerObserver
{
41 explicit URLRequestJob(URLRequest
* request
);
43 // Returns the request that owns this job. THIS POINTER MAY BE NULL if the
44 // request was destroyed.
45 URLRequest
* request() const {
49 // Sets the upload data, most requests have no upload data, so this is a NOP.
50 // Job types supporting upload data will override this.
51 virtual void SetUpload(UploadData
* upload
);
53 // Sets extra request headers for Job types that support request headers.
54 virtual void SetExtraRequestHeaders(const HttpRequestHeaders
& headers
);
56 // If any error occurs while starting the Job, NotifyStartError should be
58 // This helps ensure that all errors follow more similar notification code
59 // paths, which should simplify testing.
60 virtual void Start() = 0;
62 // This function MUST somehow call NotifyDone/NotifyCanceled or some requests
63 // will get leaked. Certain callers use that message to know when they can
64 // delete their URLRequest object, even when doing a cancel. The default
65 // Kill implementation calls NotifyCanceled, so it is recommended that
66 // subclasses call URLRequestJob::Kill() after doing any additional work.
68 // The job should endeavor to stop working as soon as is convenient, but must
69 // not send and complete notifications from inside this function. Instead,
70 // complete notifications (including "canceled") should be sent from a
71 // callback run from the message loop.
73 // The job is not obliged to immediately stop sending data in response to
74 // this call, nor is it obliged to fail with "canceled" unless not all data
75 // was sent as a result. A typical case would be where the job is almost
76 // complete and can succeed before the canceled notification can be
77 // dispatched (from the message loop).
79 // The job should be prepared to receive multiple calls to kill it, but only
80 // one notification must be issued.
83 // Called to detach the request from this Job. Results in the Job being
84 // killed off eventually. The job must not use the request pointer any more.
87 // Called to read post-filtered data from this Job, returning the number of
88 // bytes read, 0 when there is no more data, or -1 if there was an error.
89 // This is just the backend for URLRequest::Read, see that function for
91 bool Read(IOBuffer
* buf
, int buf_size
, int* bytes_read
);
93 // Stops further caching of this request, if any. For more info, see
94 // URLRequest::StopCaching().
95 virtual void StopCaching();
97 // Called to fetch the current load state for the job.
98 virtual LoadState
GetLoadState() const;
100 // Called to get the upload progress in bytes.
101 virtual uint64
GetUploadProgress() const;
103 // Called to fetch the charset for this request. Only makes sense for some
104 // types of requests. Returns true on success. Calling this on a type that
105 // doesn't have a charset will return false.
106 virtual bool GetCharset(std::string
* charset
);
108 // Called to get response info.
109 virtual void GetResponseInfo(HttpResponseInfo
* info
);
111 // Returns the cookie values included in the response, if applicable.
112 // Returns true if applicable.
113 // NOTE: This removes the cookies from the job, so it will only return
114 // useful results once per job.
115 virtual bool GetResponseCookies(std::vector
<std::string
>* cookies
);
117 // Called to setup a stream filter for this request. An example of filter is
118 // content encoding/decoding.
119 // Subclasses should return the appropriate Filter, or NULL for no Filter.
120 // This class takes ownership of the returned Filter.
122 // The default implementation returns NULL.
123 virtual Filter
* SetupFilter() const;
125 // Called to determine if this response is a redirect. Only makes sense
126 // for some types of requests. This method returns true if the response
127 // is a redirect, and fills in the location param with the URL of the
128 // redirect. The HTTP status code (e.g., 302) is filled into
129 // |*http_status_code| to signify the type of redirect.
131 // The caller is responsible for following the redirect by setting up an
132 // appropriate replacement Job. Note that the redirected location may be
133 // invalid, the caller should be sure it can handle this.
135 // The default implementation inspects the response_info_.
136 virtual bool IsRedirectResponse(GURL
* location
, int* http_status_code
);
138 // Called to determine if it is okay to redirect this job to the specified
139 // location. This may be used to implement protocol-specific restrictions.
140 // If this function returns false, then the URLRequest will fail
141 // reporting ERR_UNSAFE_REDIRECT.
142 virtual bool IsSafeRedirect(const GURL
& location
);
144 // Called to determine if this response is asking for authentication. Only
145 // makes sense for some types of requests. The caller is responsible for
146 // obtaining the credentials passing them to SetAuth.
147 virtual bool NeedsAuth();
149 // Fills the authentication info with the server's response.
150 virtual void GetAuthChallengeInfo(
151 scoped_refptr
<AuthChallengeInfo
>* auth_info
);
153 // Resend the request with authentication credentials.
154 virtual void SetAuth(const string16
& username
,
155 const string16
& password
);
157 // Display the error page without asking for credentials again.
158 virtual void CancelAuth();
160 virtual void ContinueWithCertificate(X509Certificate
* client_cert
);
162 // Continue processing the request ignoring the last error.
163 virtual void ContinueDespiteLastError();
165 void FollowDeferredRedirect();
167 // Returns true if the Job is done producing response data and has called
168 // NotifyDone on the request.
169 bool is_done() const { return done_
; }
171 // Get/Set expected content size
172 int64
expected_content_size() const { return expected_content_size_
; }
173 void set_expected_content_size(const int64
& size
) {
174 expected_content_size_
= size
;
177 // Whether we have processed the response for that request yet.
178 bool has_response_started() const { return has_handled_response_
; }
180 // These methods are not applicable to all connections.
181 virtual bool GetMimeType(std::string
* mime_type
) const;
182 virtual int GetResponseCode() const;
184 // Returns the socket address for the connection.
185 // See url_request.h for details.
186 virtual HostPortPair
GetSocketAddress() const;
188 // base::SystemMonitor::PowerObserver methods:
189 // We invoke URLRequestJob::Kill on suspend (crbug.com/4606).
190 virtual void OnSuspend();
193 friend class base::RefCounted
<URLRequestJob
>;
194 virtual ~URLRequestJob();
196 // Notifies the job that a certificate is requested.
197 void NotifyCertificateRequested(SSLCertRequestInfo
* cert_request_info
);
199 // Notifies the job about an SSL certificate error.
200 void NotifySSLCertificateError(int cert_error
, X509Certificate
* cert
);
202 // Delegates to URLRequest::Delegate.
203 bool CanGetCookies(const CookieList
& cookie_list
) const;
205 // Delegates to URLRequest::Delegate.
206 bool CanSetCookie(const std::string
& cookie_line
,
207 CookieOptions
* options
) const;
209 // Notifies the job that headers have been received.
210 void NotifyHeadersComplete();
212 // Notifies the request that the job has completed a Read operation.
213 void NotifyReadComplete(int bytes_read
);
215 // Notifies the request that a start error has occurred.
216 void NotifyStartError(const URLRequestStatus
& status
);
218 // NotifyDone marks when we are done with a request. It is really
219 // a glorified set_status, but also does internal state checking and
220 // job tracking. It should be called once per request, when the job is
221 // finished doing all IO.
222 void NotifyDone(const URLRequestStatus
& status
);
224 // Some work performed by NotifyDone must be completed on a separate task
225 // so as to avoid re-entering the delegate. This method exists to perform
227 void CompleteNotifyDone();
229 // Used as an asynchronous callback for Kill to notify the URLRequest
230 // that we were canceled.
231 void NotifyCanceled();
233 // Notifies the job the request should be restarted.
234 // Should only be called if the job has not started a resposne.
235 void NotifyRestartRequired();
237 // Called when the delegate blocks or unblocks this request when intercepting
239 void SetBlockedOnDelegate();
240 void SetUnblockedOnDelegate();
242 // Called to read raw (pre-filtered) data from this Job.
243 // If returning true, data was read from the job. buf will contain
244 // the data, and bytes_read will receive the number of bytes read.
245 // If returning true, and bytes_read is returned as 0, there is no
246 // additional data to be read.
247 // If returning false, an error occurred or an async IO is now pending.
248 // If async IO is pending, the status of the request will be
249 // URLRequestStatus::IO_PENDING, and buf must remain available until the
250 // operation is completed. See comments on URLRequest::Read for more
252 virtual bool ReadRawData(IOBuffer
* buf
, int buf_size
, int *bytes_read
);
254 // Called to tell the job that a filter has successfully reached the end of
256 virtual void DoneReading();
258 // Informs the filter that data has been read into its buffer
259 void FilteredDataRead(int bytes_read
);
261 // Reads filtered data from the request. Returns true if successful,
262 // false otherwise. Note, if there is not enough data received to
263 // return data, this call can issue a new async IO request under
265 bool ReadFilteredData(int *bytes_read
);
267 // Whether the response is being filtered in this job.
268 // Only valid after NotifyHeadersComplete() has been called.
269 bool HasFilter() { return filter_
!= NULL
; }
271 // At or near destruction time, a derived class may request that the filters
272 // be destroyed so that statistics can be gathered while the derived class is
273 // still present to assist in calculations. This is used by URLRequestHttpJob
274 // to get SDCH to emit stats.
275 void DestroyFilters() { filter_
.reset(); }
277 // The status of the job.
278 const URLRequestStatus
GetStatus();
280 // Set the status of the job.
281 void SetStatus(const URLRequestStatus
& status
);
283 // The number of bytes read before passing to the filter.
284 int prefilter_bytes_read() const { return prefilter_bytes_read_
; }
286 // The number of bytes read after passing through the filter.
287 int postfilter_bytes_read() const { return postfilter_bytes_read_
; }
289 // Total number of bytes read from network (or cache) and typically handed
290 // to filter to process. Used to histogram compression ratios, and error
291 // recovery scenarios in filters.
292 int64
filter_input_byte_count() const { return filter_input_byte_count_
; }
294 // The request that initiated this job. This value MAY BE NULL if the
295 // request was released by DetachRequest().
296 URLRequest
* request_
;
299 // When data filtering is enabled, this function is used to read data
300 // for the filter. Returns true if raw data was read. Returns false if
301 // an error occurred (or we are waiting for IO to complete).
302 bool ReadRawDataForFilter(int *bytes_read
);
304 // Invokes ReadRawData and records bytes read if the read completes
306 bool ReadRawDataHelper(IOBuffer
* buf
, int buf_size
, int* bytes_read
);
308 // Called in response to a redirect that was not canceled to follow the
309 // redirect. The current job will be replaced with a new job loading the
310 // given redirect destination.
311 void FollowRedirect(const GURL
& location
, int http_status_code
);
313 // Called after every raw read. If |bytes_read| is > 0, this indicates
314 // a successful read of |bytes_read| unfiltered bytes. If |bytes_read|
315 // is 0, this indicates that there is no additional data to read. If
316 // |bytes_read| is < 0, an error occurred and no bytes were read.
317 void OnRawReadComplete(int bytes_read
);
319 // Updates the profiling info and notifies observers that an additional
320 // |bytes_read| unfiltered bytes have been read for this job.
321 void RecordBytesRead(int bytes_read
);
323 // Called to query whether there is data available in the filter to be read
325 bool FilterHasData();
327 // Subclasses may implement this method to record packet arrival times.
328 // The default implementation does nothing.
329 virtual void UpdatePacketReadTimes();
331 // Indicates that the job is done producing data, either it has completed
332 // all the data or an error has been encountered. Set exclusively by
333 // NotifyDone so that it is kept in sync with the request.
336 int prefilter_bytes_read_
;
337 int postfilter_bytes_read_
;
338 int64 filter_input_byte_count_
;
340 // The data stream filter which is enabled on demand.
341 scoped_ptr
<Filter
> filter_
;
343 // If the filter filled its output buffer, then there is a change that it
344 // still has internal data to emit, and this flag is set.
345 bool filter_needs_more_output_space_
;
347 // When we filter data, we receive data into the filter buffers. After
348 // processing the filtered data, we return the data in the caller's buffer.
349 // While the async IO is in progress, we save the user buffer here, and
350 // when the IO completes, we fill this in.
351 scoped_refptr
<IOBuffer
> filtered_read_buffer_
;
352 int filtered_read_buffer_len_
;
354 // We keep a pointer to the read buffer while asynchronous reads are
355 // in progress, so we are able to pass those bytes to job observers.
356 scoped_refptr
<IOBuffer
> raw_read_buffer_
;
358 // Used by HandleResponseIfNecessary to track whether we've sent the
359 // OnResponseStarted callback and potentially redirect callbacks as well.
360 bool has_handled_response_
;
362 // Expected content size
363 int64 expected_content_size_
;
365 // Set when a redirect is deferred.
366 GURL deferred_redirect_url_
;
367 int deferred_redirect_status_code_
;
369 ScopedRunnableMethodFactory
<URLRequestJob
> method_factory_
;
371 DISALLOW_COPY_AND_ASSIGN(URLRequestJob
);
376 #endif // NET_URL_REQUEST_URL_REQUEST_JOB_H_