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 // The intent of this file is to provide a type-neutral abstraction between
6 // Chrome and WebKit for resource loading. This pure-virtual interface is
7 // implemented by the embedder.
9 // One of these objects will be created by WebKit for each request. WebKit
10 // will own the pointer to the bridge, and will delete it when the request is
13 // In turn, the bridge's owner on the WebKit end will implement the Peer
14 // interface, which we will use to communicate notifications back.
16 #ifndef WEBKIT_CHILD_RESOURCE_LOADER_BRIDGE_H_
17 #define WEBKIT_CHILD_RESOURCE_LOADER_BRIDGE_H_
21 #include "build/build_config.h"
23 #include "base/file_descriptor_posix.h"
25 #include "base/memory/ref_counted.h"
26 #include "base/platform_file.h"
27 #include "base/values.h"
28 #include "net/base/request_priority.h"
29 #include "third_party/WebKit/public/platform/WebReferrerPolicy.h"
30 #include "third_party/WebKit/public/platform/WebURLRequest.h"
32 #include "webkit/child/webkit_child_export.h"
33 #include "webkit/common/resource_response_info.h"
34 #include "webkit/common/resource_type.h"
36 namespace webkit_glue {
37 class ResourceRequestBody;
39 class ResourceLoaderBridge {
41 // Structure used when calling
42 // WebKitPlatformSupportImpl::CreateResourceLoader().
43 struct WEBKIT_CHILD_EXPORT RequestInfo {
47 // HTTP-style method name (e.g., "GET" or "POST").
50 // Absolute URL encoded in ASCII per the rules of RFC-2396.
53 // URL of the document in the top-level window, which may be checked by the
54 // third-party cookie blocking policy.
55 GURL first_party_for_cookies;
57 // Optional parameter, a URL with similar constraints in how it must be
58 // encoded as the url member.
61 // The referrer policy that applies to the referrer.
62 WebKit::WebReferrerPolicy referrer_policy;
64 // For HTTP(S) requests, the headers parameter can be a \r\n-delimited and
65 // \r\n-terminated list of MIME headers. They should be ASCII-encoded using
66 // the standard MIME header encoding rules. The headers parameter can also
67 // be null if no extra request headers need to be set.
70 // Composed of the values defined in url_request_load_flags.h.
73 // Process id of the process making the request.
76 // Indicates if the current request is the main frame load, a sub-frame
77 // load, or a sub objects load.
78 ResourceType::Type request_type;
80 // Indicates the priority of this request, as determined by WebKit.
81 net::RequestPriority priority;
83 // Used for plugin to browser requests.
84 uint32 request_context;
86 // Identifies what appcache host this request is associated with.
89 // Used to associated the bridge with a frame's network context.
92 // If true, then the response body will be downloaded to a file and the
93 // path to that file will be provided in ResponseInfo::download_file_path.
94 bool download_to_file;
96 // True if the request was user initiated.
97 bool has_user_gesture;
99 // Extra data associated with this request. We do not own this pointer.
100 WebKit::WebURLRequest::ExtraData* extra_data;
103 DISALLOW_COPY_AND_ASSIGN(RequestInfo);
106 // See the SyncLoad method declared below. (The name of this struct is not
107 // suffixed with "Info" because it also contains the response data.)
108 struct SyncLoadResponse : ResourceResponseInfo {
109 WEBKIT_CHILD_EXPORT SyncLoadResponse();
110 WEBKIT_CHILD_EXPORT ~SyncLoadResponse();
112 // The response error code.
115 // The final URL of the response. This may differ from the request URL in
116 // the case of a server redirect.
119 // The response data.
123 // Generated by the bridge. This is implemented by our custom resource loader
124 // within webkit. The Peer and it's bridge should have identical lifetimes
125 // as they represent each end of a communication channel.
127 // These callbacks mirror net::URLRequest::Delegate and the order and
128 // conditions in which they will be called are identical. See url_request.h
129 // for more information.
130 class WEBKIT_CHILD_EXPORT Peer {
132 // Called as upload progress is made.
133 // note: only for requests with LOAD_ENABLE_UPLOAD_PROGRESS set
134 virtual void OnUploadProgress(uint64 position, uint64 size) = 0;
136 // Called when a redirect occurs. The implementation may return false to
137 // suppress the redirect. The given ResponseInfo provides complete
138 // information about the redirect, and new_url is the URL that will be
139 // loaded if this method returns true. If this method returns true, the
140 // output parameter *has_new_first_party_for_cookies indicates whether the
141 // output parameter *new_first_party_for_cookies contains the new URL that
142 // should be consulted for the third-party cookie blocking policy.
143 virtual bool OnReceivedRedirect(const GURL& new_url,
144 const ResourceResponseInfo& info,
145 bool* has_new_first_party_for_cookies,
146 GURL* new_first_party_for_cookies) = 0;
148 // Called when response headers are available (after all redirects have
150 virtual void OnReceivedResponse(const ResourceResponseInfo& info) = 0;
152 // Called when a chunk of response data is downloaded. This method may be
153 // called multiple times or not at all if an error occurs. This method is
154 // only called if RequestInfo::download_to_file was set to true, and in
155 // that case, OnReceivedData will not be called.
156 // The encoded_data_length is the length of the encoded data transferred
157 // over the network, which could be different from data length (e.g. for
158 // gzipped content), or -1 if unknown. It is only valid while devtools are
159 // attached. Otherwise it becomes -1.
160 virtual void OnDownloadedData(int len, int encoded_data_length) = 0;
162 // Called when a chunk of response data is available. This method may
163 // be called multiple times or not at all if an error occurs.
164 // The encoded_data_length is the length of the encoded data transferred
165 // over the network, which could be different from data length (e.g. for
166 // gzipped content), or -1 if unknown. It is only valid while devtools are
167 // attached. Otherwise it becomes -1.
168 virtual void OnReceivedData(const char* data,
170 int encoded_data_length) = 0;
172 // Called when metadata generated by the renderer is retrieved from the
173 // cache. This method may be called zero or one times.
174 virtual void OnReceivedCachedMetadata(const char* data, int len) { }
176 // Called when the response is complete. This method signals completion of
177 // the resource load.
178 virtual void OnCompletedRequest(
180 bool was_ignored_by_handler,
181 const std::string& security_info,
182 const base::TimeTicks& completion_time) = 0;
188 // use WebKitPlatformSupportImpl::CreateResourceLoader() for construction, but
189 // anybody can delete at any time, INCLUDING during processing of callbacks.
190 WEBKIT_CHILD_EXPORT virtual ~ResourceLoaderBridge();
192 // Call this method before calling Start() to set the request body.
193 // May only be used with HTTP(S) POST requests.
194 virtual void SetRequestBody(ResourceRequestBody* request_body) = 0;
196 // Call this method to initiate the request. If this method succeeds, then
197 // the peer's methods will be called asynchronously to report various events.
198 virtual bool Start(Peer* peer) = 0;
200 // Call this method to cancel a request that is in progress. This method
201 // causes the request to immediately transition into the 'done' state. The
202 // OnCompletedRequest method will be called asynchronously; this assumes
203 // the peer is still valid.
204 virtual void Cancel() = 0;
206 // Call this method to suspend or resume a load that is in progress. This
207 // method may only be called after a successful call to the Start method.
208 virtual void SetDefersLoading(bool value) = 0;
210 // Call this method when the priority of the requested resource changes after
211 // Start() has been called. This method may only be called after a successful
212 // call to the Start method.
213 virtual void DidChangePriority(net::RequestPriority new_priority) = 0;
215 // Call this method to load the resource synchronously (i.e., in one shot).
216 // This is an alternative to the Start method. Be warned that this method
217 // will block the calling thread until the resource is fully downloaded or an
218 // error occurs. It could block the calling thread for a long time, so only
219 // use this if you really need it! There is also no way for the caller to
220 // interrupt this method. Errors are reported via the status field of the
221 // response parameter.
222 virtual void SyncLoad(SyncLoadResponse* response) = 0;
225 // Construction must go through
226 // WebKitPlatformSupportImpl::CreateResourceLoader()
227 // For HTTP(S) POST requests, the AppendDataToUpload and AppendFileToUpload
228 // methods may be called to construct the body of the request.
229 WEBKIT_CHILD_EXPORT ResourceLoaderBridge();
232 DISALLOW_COPY_AND_ASSIGN(ResourceLoaderBridge);
235 } // namespace webkit_glue
237 #endif // WEBKIT_CHILD_RESOURCE_LOADER_BRIDGE_H_