[DevTools] Implement DevToolsManager::Observer which notifies about target updates.
[chromium-blink-merge.git] / net / url_request / url_request_job.h
blob2dcd67af878b0f814cc234bad787abb48a1b14cc
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_REQUEST_JOB_H_
6 #define NET_URL_REQUEST_URL_REQUEST_JOB_H_
8 #include <string>
9 #include <vector>
11 #include "base/memory/ref_counted.h"
12 #include "base/memory/scoped_ptr.h"
13 #include "base/memory/weak_ptr.h"
14 #include "base/message_loop/message_loop.h"
15 #include "base/power_monitor/power_observer.h"
16 #include "net/base/host_port_pair.h"
17 #include "net/base/load_states.h"
18 #include "net/base/net_export.h"
19 #include "net/base/request_priority.h"
20 #include "net/base/upload_progress.h"
21 #include "net/cookies/canonical_cookie.h"
22 #include "net/url_request/redirect_info.h"
23 #include "url/gurl.h"
25 namespace net {
27 class AuthChallengeInfo;
28 class AuthCredentials;
29 class CookieOptions;
30 class CookieStore;
31 class Filter;
32 class HttpRequestHeaders;
33 class HttpResponseInfo;
34 class IOBuffer;
35 struct LoadTimingInfo;
36 class NetworkDelegate;
37 class SSLCertRequestInfo;
38 class SSLInfo;
39 class URLRequest;
40 class UploadDataStream;
41 class URLRequestStatus;
42 class X509Certificate;
44 class NET_EXPORT URLRequestJob
45 : public base::RefCounted<URLRequestJob>,
46 public base::PowerObserver {
47 public:
48 explicit URLRequestJob(URLRequest* request,
49 NetworkDelegate* network_delegate);
51 // Returns the request that owns this job. THIS POINTER MAY BE NULL if the
52 // request was destroyed.
53 URLRequest* request() const {
54 return request_;
57 // Sets the upload data, most requests have no upload data, so this is a NOP.
58 // Job types supporting upload data will override this.
59 virtual void SetUpload(UploadDataStream* upload_data_stream);
61 // Sets extra request headers for Job types that support request
62 // headers. Called once before Start() is called.
63 virtual void SetExtraRequestHeaders(const HttpRequestHeaders& headers);
65 // Sets the priority of the job. Called once before Start() is
66 // called, but also when the priority of the parent request changes.
67 virtual void SetPriority(RequestPriority priority);
69 // If any error occurs while starting the Job, NotifyStartError should be
70 // called.
71 // This helps ensure that all errors follow more similar notification code
72 // paths, which should simplify testing.
73 virtual void Start() = 0;
75 // This function MUST somehow call NotifyDone/NotifyCanceled or some requests
76 // will get leaked. Certain callers use that message to know when they can
77 // delete their URLRequest object, even when doing a cancel. The default
78 // Kill implementation calls NotifyCanceled, so it is recommended that
79 // subclasses call URLRequestJob::Kill() after doing any additional work.
81 // The job should endeavor to stop working as soon as is convenient, but must
82 // not send and complete notifications from inside this function. Instead,
83 // complete notifications (including "canceled") should be sent from a
84 // callback run from the message loop.
86 // The job is not obliged to immediately stop sending data in response to
87 // this call, nor is it obliged to fail with "canceled" unless not all data
88 // was sent as a result. A typical case would be where the job is almost
89 // complete and can succeed before the canceled notification can be
90 // dispatched (from the message loop).
92 // The job should be prepared to receive multiple calls to kill it, but only
93 // one notification must be issued.
94 virtual void Kill();
96 // Called to detach the request from this Job. Results in the Job being
97 // killed off eventually. The job must not use the request pointer any more.
98 void DetachRequest();
100 // Called to read post-filtered data from this Job, returning the number of
101 // bytes read, 0 when there is no more data, or -1 if there was an error.
102 // This is just the backend for URLRequest::Read, see that function for
103 // more info.
104 bool Read(IOBuffer* buf, int buf_size, int* bytes_read);
106 // Stops further caching of this request, if any. For more info, see
107 // URLRequest::StopCaching().
108 virtual void StopCaching();
110 virtual bool GetFullRequestHeaders(HttpRequestHeaders* headers) const;
112 // Get the number of bytes received from network.
113 virtual int64 GetTotalReceivedBytes() const;
115 // Called to fetch the current load state for the job.
116 virtual LoadState GetLoadState() const;
118 // Called to get the upload progress in bytes.
119 virtual UploadProgress GetUploadProgress() const;
121 // Called to fetch the charset for this request. Only makes sense for some
122 // types of requests. Returns true on success. Calling this on a type that
123 // doesn't have a charset will return false.
124 virtual bool GetCharset(std::string* charset);
126 // Called to get response info.
127 virtual void GetResponseInfo(HttpResponseInfo* info);
129 // This returns the times when events actually occurred, rather than the time
130 // each event blocked the request. See FixupLoadTimingInfo in url_request.h
131 // for more information on the difference.
132 virtual void GetLoadTimingInfo(LoadTimingInfo* load_timing_info) const;
134 // Returns the cookie values included in the response, if applicable.
135 // Returns true if applicable.
136 // NOTE: This removes the cookies from the job, so it will only return
137 // useful results once per job.
138 virtual bool GetResponseCookies(std::vector<std::string>* cookies);
140 // Called to setup a stream filter for this request. An example of filter is
141 // content encoding/decoding.
142 // Subclasses should return the appropriate Filter, or NULL for no Filter.
143 // This class takes ownership of the returned Filter.
145 // The default implementation returns NULL.
146 virtual Filter* SetupFilter() const;
148 // Called to determine if this response is a redirect. Only makes sense
149 // for some types of requests. This method returns true if the response
150 // is a redirect, and fills in the location param with the URL of the
151 // redirect. The HTTP status code (e.g., 302) is filled into
152 // |*http_status_code| to signify the type of redirect.
154 // The caller is responsible for following the redirect by setting up an
155 // appropriate replacement Job. Note that the redirected location may be
156 // invalid, the caller should be sure it can handle this.
158 // The default implementation inspects the response_info_.
159 virtual bool IsRedirectResponse(GURL* location, int* http_status_code);
161 // Called to determine if it is okay to copy the reference fragment from the
162 // original URL (if existent) to the redirection target when the redirection
163 // target has no reference fragment.
165 // The default implementation returns true.
166 virtual bool CopyFragmentOnRedirect(const GURL& location) const;
168 // Called to determine if it is okay to redirect this job to the specified
169 // location. This may be used to implement protocol-specific restrictions.
170 // If this function returns false, then the URLRequest will fail
171 // reporting ERR_UNSAFE_REDIRECT.
172 virtual bool IsSafeRedirect(const GURL& location);
174 // Called to determine if this response is asking for authentication. Only
175 // makes sense for some types of requests. The caller is responsible for
176 // obtaining the credentials passing them to SetAuth.
177 virtual bool NeedsAuth();
179 // Fills the authentication info with the server's response.
180 virtual void GetAuthChallengeInfo(
181 scoped_refptr<AuthChallengeInfo>* auth_info);
183 // Resend the request with authentication credentials.
184 virtual void SetAuth(const AuthCredentials& credentials);
186 // Display the error page without asking for credentials again.
187 virtual void CancelAuth();
189 virtual void ContinueWithCertificate(X509Certificate* client_cert);
191 // Continue processing the request ignoring the last error.
192 virtual void ContinueDespiteLastError();
194 // Continue with the network request.
195 virtual void ResumeNetworkStart();
197 void FollowDeferredRedirect();
199 // Returns true if the Job is done producing response data and has called
200 // NotifyDone on the request.
201 bool is_done() const { return done_; }
203 // Get/Set expected content size
204 int64 expected_content_size() const { return expected_content_size_; }
205 void set_expected_content_size(const int64& size) {
206 expected_content_size_ = size;
209 // Whether we have processed the response for that request yet.
210 bool has_response_started() const { return has_handled_response_; }
212 // These methods are not applicable to all connections.
213 virtual bool GetMimeType(std::string* mime_type) const;
214 virtual int GetResponseCode() const;
216 // Returns the socket address for the connection.
217 // See url_request.h for details.
218 virtual HostPortPair GetSocketAddress() const;
220 // base::PowerObserver methods:
221 // We invoke URLRequestJob::Kill on suspend (crbug.com/4606).
222 virtual void OnSuspend() OVERRIDE;
224 // Called after a NetworkDelegate has been informed that the URLRequest
225 // will be destroyed. This is used to track that no pending callbacks
226 // exist at destruction time of the URLRequestJob, unless they have been
227 // canceled by an explicit NetworkDelegate::NotifyURLRequestDestroyed() call.
228 virtual void NotifyURLRequestDestroyed();
230 protected:
231 friend class base::RefCounted<URLRequestJob>;
232 virtual ~URLRequestJob();
234 // Notifies the job that a certificate is requested.
235 void NotifyCertificateRequested(SSLCertRequestInfo* cert_request_info);
237 // Notifies the job about an SSL certificate error.
238 void NotifySSLCertificateError(const SSLInfo& ssl_info, bool fatal);
240 // Delegates to URLRequest::Delegate.
241 bool CanGetCookies(const CookieList& cookie_list) const;
243 // Delegates to URLRequest::Delegate.
244 bool CanSetCookie(const std::string& cookie_line,
245 CookieOptions* options) const;
247 // Delegates to URLRequest::Delegate.
248 bool CanEnablePrivacyMode() const;
250 // Returns the cookie store to be used for the request.
251 CookieStore* GetCookieStore() const;
253 // Notifies the job that the network is about to be used.
254 void NotifyBeforeNetworkStart(bool* defer);
256 // Notifies the job that headers have been received.
257 void NotifyHeadersComplete();
259 // Notifies the request that the job has completed a Read operation.
260 void NotifyReadComplete(int bytes_read);
262 // Notifies the request that a start error has occurred.
263 void NotifyStartError(const URLRequestStatus& status);
265 // NotifyDone marks when we are done with a request. It is really
266 // a glorified set_status, but also does internal state checking and
267 // job tracking. It should be called once per request, when the job is
268 // finished doing all IO.
269 void NotifyDone(const URLRequestStatus& status);
271 // Some work performed by NotifyDone must be completed on a separate task
272 // so as to avoid re-entering the delegate. This method exists to perform
273 // that work.
274 void CompleteNotifyDone();
276 // Used as an asynchronous callback for Kill to notify the URLRequest
277 // that we were canceled.
278 void NotifyCanceled();
280 // Notifies the job the request should be restarted.
281 // Should only be called if the job has not started a response.
282 void NotifyRestartRequired();
284 // See corresponding functions in url_request.h.
285 void OnCallToDelegate();
286 void OnCallToDelegateComplete();
288 // Called to read raw (pre-filtered) data from this Job.
289 // If returning true, data was read from the job. buf will contain
290 // the data, and bytes_read will receive the number of bytes read.
291 // If returning true, and bytes_read is returned as 0, there is no
292 // additional data to be read.
293 // If returning false, an error occurred or an async IO is now pending.
294 // If async IO is pending, the status of the request will be
295 // URLRequestStatus::IO_PENDING, and buf must remain available until the
296 // operation is completed. See comments on URLRequest::Read for more
297 // info.
298 virtual bool ReadRawData(IOBuffer* buf, int buf_size, int *bytes_read);
300 // Called to tell the job that a filter has successfully reached the end of
301 // the stream.
302 virtual void DoneReading();
304 // Called to tell the job that the body won't be read because it's a redirect.
305 // This is needed so that redirect headers can be cached even though their
306 // bodies are never read.
307 virtual void DoneReadingRedirectResponse();
309 // Informs the filter that data has been read into its buffer
310 void FilteredDataRead(int bytes_read);
312 // Reads filtered data from the request. Returns true if successful,
313 // false otherwise. Note, if there is not enough data received to
314 // return data, this call can issue a new async IO request under
315 // the hood.
316 bool ReadFilteredData(int *bytes_read);
318 // Whether the response is being filtered in this job.
319 // Only valid after NotifyHeadersComplete() has been called.
320 bool HasFilter() { return filter_ != NULL; }
322 // At or near destruction time, a derived class may request that the filters
323 // be destroyed so that statistics can be gathered while the derived class is
324 // still present to assist in calculations. This is used by URLRequestHttpJob
325 // to get SDCH to emit stats.
326 void DestroyFilters();
328 // Provides derived classes with access to the request's network delegate.
329 NetworkDelegate* network_delegate() { return network_delegate_; }
331 // The status of the job.
332 const URLRequestStatus GetStatus();
334 // Set the status of the job.
335 void SetStatus(const URLRequestStatus& status);
337 // Set the proxy server that was used, if any.
338 void SetProxyServer(const HostPortPair& proxy_server);
340 // The number of bytes read before passing to the filter.
341 int prefilter_bytes_read() const { return prefilter_bytes_read_; }
343 // The number of bytes read after passing through the filter.
344 int postfilter_bytes_read() const { return postfilter_bytes_read_; }
346 // Total number of bytes read from network (or cache) and typically handed
347 // to filter to process. Used to histogram compression ratios, and error
348 // recovery scenarios in filters.
349 int64 filter_input_byte_count() const { return filter_input_byte_count_; }
351 // The request that initiated this job. This value MAY BE NULL if the
352 // request was released by DetachRequest().
353 URLRequest* request_;
355 private:
356 // When data filtering is enabled, this function is used to read data
357 // for the filter. Returns true if raw data was read. Returns false if
358 // an error occurred (or we are waiting for IO to complete).
359 bool ReadRawDataForFilter(int *bytes_read);
361 // Invokes ReadRawData and records bytes read if the read completes
362 // synchronously.
363 bool ReadRawDataHelper(IOBuffer* buf, int buf_size, int* bytes_read);
365 // Called in response to a redirect that was not canceled to follow the
366 // redirect. The current job will be replaced with a new job loading the
367 // given redirect destination.
368 void FollowRedirect(const RedirectInfo& redirect_info);
370 // Called after every raw read. If |bytes_read| is > 0, this indicates
371 // a successful read of |bytes_read| unfiltered bytes. If |bytes_read|
372 // is 0, this indicates that there is no additional data to read. If
373 // |bytes_read| is < 0, an error occurred and no bytes were read.
374 void OnRawReadComplete(int bytes_read);
376 // Updates the profiling info and notifies observers that an additional
377 // |bytes_read| unfiltered bytes have been read for this job.
378 void RecordBytesRead(int bytes_read);
380 // Called to query whether there is data available in the filter to be read
381 // out.
382 bool FilterHasData();
384 // Subclasses may implement this method to record packet arrival times.
385 // The default implementation does nothing.
386 virtual void UpdatePacketReadTimes();
388 // Computes a new RedirectInfo based on receiving a redirect response of
389 // |location| and |http_status_code|.
390 RedirectInfo ComputeRedirectInfo(const GURL& location, int http_status_code);
392 // Indicates that the job is done producing data, either it has completed
393 // all the data or an error has been encountered. Set exclusively by
394 // NotifyDone so that it is kept in sync with the request.
395 bool done_;
397 int prefilter_bytes_read_;
398 int postfilter_bytes_read_;
399 int64 filter_input_byte_count_;
401 // The data stream filter which is enabled on demand.
402 scoped_ptr<Filter> filter_;
404 // If the filter filled its output buffer, then there is a change that it
405 // still has internal data to emit, and this flag is set.
406 bool filter_needs_more_output_space_;
408 // When we filter data, we receive data into the filter buffers. After
409 // processing the filtered data, we return the data in the caller's buffer.
410 // While the async IO is in progress, we save the user buffer here, and
411 // when the IO completes, we fill this in.
412 scoped_refptr<IOBuffer> filtered_read_buffer_;
413 int filtered_read_buffer_len_;
415 // We keep a pointer to the read buffer while asynchronous reads are
416 // in progress, so we are able to pass those bytes to job observers.
417 scoped_refptr<IOBuffer> raw_read_buffer_;
419 // Used by HandleResponseIfNecessary to track whether we've sent the
420 // OnResponseStarted callback and potentially redirect callbacks as well.
421 bool has_handled_response_;
423 // Expected content size
424 int64 expected_content_size_;
426 // Set when a redirect is deferred.
427 RedirectInfo deferred_redirect_info_;
429 // The network delegate to use with this request, if any.
430 NetworkDelegate* network_delegate_;
432 base::WeakPtrFactory<URLRequestJob> weak_factory_;
434 DISALLOW_COPY_AND_ASSIGN(URLRequestJob);
437 } // namespace net
439 #endif // NET_URL_REQUEST_URL_REQUEST_JOB_H_