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// This is the browser side of the resource dispatcher, it receives requests
6// from the RenderProcessHosts, and dispatches them to URLRequests. It then
7// fowards the messages from the URLRequests back to the correct process for
8// handling.
9//
10// See http://dev.chromium.org/developers/design-documents/multi-process-resource-loading
11
12#ifndef CONTENT_BROWSER_LOADER_RESOURCE_HANDLER_H_
13#define CONTENT_BROWSER_LOADER_RESOURCE_HANDLER_H_
14
15#include <string>
16
17#include "base/memory/ref_counted.h"
18#include "base/sequenced_task_runner_helpers.h"
19#include "base/threading/non_thread_safe.h"
20#include "content/common/content_export.h"
21
22class GURL;
23
24namespace net {
25class IOBuffer;
26class URLRequest;
27class URLRequestStatus;
28struct RedirectInfo;
29}  // namespace net
30
31namespace content {
32class ResourceController;
33class ResourceMessageFilter;
34class ResourceRequestInfoImpl;
35struct ResourceResponse;
36
37// The resource dispatcher host uses this interface to process network events
38// for an URLRequest instance.  A ResourceHandler's lifetime is bound to its
39// associated URLRequest.
40class CONTENT_EXPORT ResourceHandler
41    : public NON_EXPORTED_BASE(base::NonThreadSafe) {
42 public:
43  virtual ~ResourceHandler() {}
44
45  // Sets the controller for this handler.
46  virtual void SetController(ResourceController* controller);
47
48  // Called as upload progress is made.  The return value is ignored.
49  virtual bool OnUploadProgress(uint64 position, uint64 size) = 0;
50
51  // The request was redirected to a new URL.  |*defer| has an initial value of
52  // false.  Set |*defer| to true to defer the redirect.  The redirect may be
53  // followed later on via ResourceDispatcherHost::FollowDeferredRedirect.  If
54  // the handler returns false, then the request is cancelled.
55  virtual bool OnRequestRedirected(const net::RedirectInfo& redirect_info,
56                                   ResourceResponse* response,
57                                   bool* defer) = 0;
58
59  // Response headers and meta data are available.  If the handler returns
60  // false, then the request is cancelled.  Set |*defer| to true to defer
61  // processing of the response.  Call ResourceDispatcherHostImpl::
62  // ResumeDeferredRequest to continue processing the response.
63  virtual bool OnResponseStarted(ResourceResponse* response, bool* defer) = 0;
64
65  // Called before the net::URLRequest (whose url is |url|) is to be started.
66  // If the handler returns false, then the request is cancelled.  Otherwise if
67  // the return value is true, the ResourceHandler can delay the request from
68  // starting by setting |*defer = true|.  A deferred request will not have
69  // called net::URLRequest::Start(), and will not resume until someone calls
70  // ResourceDispatcherHost::StartDeferredRequest().
71  virtual bool OnWillStart(const GURL& url, bool* defer) = 0;
72
73  // Called before the net::URLRequest (whose url is |url|} uses the network for
74  // the first time to load the resource. If the handler returns false, then the
75  // request is cancelled. Otherwise if the return value is true, the
76  // ResourceHandler can delay the request from starting by setting |*defer =
77  // true|. Call controller()->Resume() to continue if deferred.
78  virtual bool OnBeforeNetworkStart(const GURL& url, bool* defer) = 0;
79
80  // Data will be read for the response.  Upon success, this method places the
81  // size and address of the buffer where the data is to be written in its
82  // out-params.  This call will be followed by either OnReadCompleted (on
83  // successful read or EOF) or OnResponseCompleted (on error).  If
84  // OnReadCompleted is called, the buffer may be recycled.  Otherwise, it may
85  // not be recycled and may potentially outlive the handler.  If |min_size| is
86  // not -1, it is the minimum size of the returned buffer.
87  //
88  // If the handler returns false, then the request is cancelled.  Otherwise,
89  // once data is available, OnReadCompleted will be called.
90  virtual bool OnWillRead(scoped_refptr<net::IOBuffer>* buf,
91                          int* buf_size,
92                          int min_size) = 0;
93
94  // Data (*bytes_read bytes) was written into the buffer provided by
95  // OnWillRead.  A return value of false cancels the request, true continues
96  // reading data.  Set |*defer| to true to defer reading more response data.
97  // Call controller()->Resume() to continue reading response data.  A zero
98  // |bytes_read| signals that no further data is available.
99  virtual bool OnReadCompleted(int bytes_read, bool* defer) = 0;
100
101  // The response is complete.  The final response status is given.  Set
102  // |*defer| to true to defer destruction to a later time.  Otherwise, the
103  // request will be destroyed upon return.
104  virtual void OnResponseCompleted(const net::URLRequestStatus& status,
105                                   const std::string& security_info,
106                                   bool* defer) = 0;
107
108  // This notification is synthesized by the RedirectToFileResourceHandler
109  // to indicate progress of 'download_to_file' requests. OnReadCompleted
110  // calls are consumed by the RedirectToFileResourceHandler and replaced
111  // with OnDataDownloaded calls.
112  virtual void OnDataDownloaded(int bytes_downloaded) = 0;
113
114 protected:
115  ResourceHandler(net::URLRequest* request);
116
117  ResourceController* controller() const { return controller_; }
118  net::URLRequest* request() const { return request_; }
119
120  // Convenience functions.
121  ResourceRequestInfoImpl* GetRequestInfo() const;
122  int GetRequestID() const;
123  ResourceMessageFilter* GetFilter() const;
124
125 private:
126  ResourceController* controller_;
127  net::URLRequest* request_;
128};
129
130}  // namespace content
131
132#endif  // CONTENT_BROWSER_LOADER_RESOURCE_HANDLER_H_
133