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 // 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. 8 // 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 11 // no longer needed. 12 // 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. 15 16 #ifndef WEBKIT_CHILD_RESOURCE_LOADER_BRIDGE_H_ 17 #define WEBKIT_CHILD_RESOURCE_LOADER_BRIDGE_H_ 18 19 #include <utility> 20 21 #include "build/build_config.h" 22 #if defined(OS_POSIX) 23 #include "base/file_descriptor_posix.h" 24 #endif 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" 31 #include "url/gurl.h" 32 #include "webkit/child/webkit_child_export.h" 33 #include "webkit/common/resource_response_info.h" 34 #include "webkit/common/resource_type.h" 35 36 namespace webkit_glue { 37 class ResourceRequestBody; 38 39 class ResourceLoaderBridge { 40 public: 41 // Structure used when calling 42 // WebKitPlatformSupportImpl::CreateResourceLoader(). 43 struct WEBKIT_CHILD_EXPORT RequestInfo { 44 RequestInfo(); 45 ~RequestInfo(); 46 47 // HTTP-style method name (e.g., "GET" or "POST"). 48 std::string method; 49 50 // Absolute URL encoded in ASCII per the rules of RFC-2396. 51 GURL url; 52 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; 56 57 // Optional parameter, a URL with similar constraints in how it must be 58 // encoded as the url member. 59 GURL referrer; 60 61 // The referrer policy that applies to the referrer. 62 WebKit::WebReferrerPolicy referrer_policy; 63 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. 68 std::string headers; 69 70 // Composed of the values defined in url_request_load_flags.h. 71 int load_flags; 72 73 // Process id of the process making the request. 74 int requestor_pid; 75 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; 79 80 // Indicates the priority of this request, as determined by WebKit. 81 net::RequestPriority priority; 82 83 // Used for plugin to browser requests. 84 uint32 request_context; 85 86 // Identifies what appcache host this request is associated with. 87 int appcache_host_id; 88 89 // Used to associated the bridge with a frame's network context. 90 int routing_id; 91 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; 95 96 // True if the request was user initiated. 97 bool has_user_gesture; 98 99 // Extra data associated with this request. We do not own this pointer. 100 WebKit::WebURLRequest::ExtraData* extra_data; 101 102 private: 103 DISALLOW_COPY_AND_ASSIGN(RequestInfo); 104 }; 105 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(); 111 112 // The response error code. 113 int error_code; 114 115 // The final URL of the response. This may differ from the request URL in 116 // the case of a server redirect. 117 GURL url; 118 119 // The response data. 120 std::string data; 121 }; 122 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. 126 // 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 Peer { 131 public: 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; 135 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; 147 148 // Called when response headers are available (after all redirects have 149 // been followed). 150 virtual void OnReceivedResponse(const ResourceResponseInfo& info) = 0; 151 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 virtual void OnDownloadedData(int len) = 0; 157 158 // Called when a chunk of response data is available. This method may 159 // be called multiple times or not at all if an error occurs. 160 // The encoded_data_length is the length of the encoded data transferred 161 // over the network, which could be different from data length (e.g. for 162 // gzipped content), or -1 if if unknown. 163 virtual void OnReceivedData(const char* data, 164 int data_length, 165 int encoded_data_length) = 0; 166 167 // Called when metadata generated by the renderer is retrieved from the 168 // cache. This method may be called zero or one times. 169 virtual void OnReceivedCachedMetadata(const char* data, int len) { } 170 171 // Called when the response is complete. This method signals completion of 172 // the resource load. 173 virtual void OnCompletedRequest( 174 int error_code, 175 bool was_ignored_by_handler, 176 const std::string& security_info, 177 const base::TimeTicks& completion_time) = 0; 178 179 protected: 180 virtual ~Peer() {} 181 }; 182 183 // use WebKitPlatformSupportImpl::CreateResourceLoader() for construction, but 184 // anybody can delete at any time, INCLUDING during processing of callbacks. 185 WEBKIT_CHILD_EXPORT virtual ~ResourceLoaderBridge(); 186 187 // Call this method before calling Start() to set the request body. 188 // May only be used with HTTP(S) POST requests. 189 virtual void SetRequestBody(ResourceRequestBody* request_body) = 0; 190 191 // Call this method to initiate the request. If this method succeeds, then 192 // the peer's methods will be called asynchronously to report various events. 193 virtual bool Start(Peer* peer) = 0; 194 195 // Call this method to cancel a request that is in progress. This method 196 // causes the request to immediately transition into the 'done' state. The 197 // OnCompletedRequest method will be called asynchronously; this assumes 198 // the peer is still valid. 199 virtual void Cancel() = 0; 200 201 // Call this method to suspend or resume a load that is in progress. This 202 // method may only be called after a successful call to the Start method. 203 virtual void SetDefersLoading(bool value) = 0; 204 205 // Call this method when the priority of the requested resource changes after 206 // Start() has been called. This method may only be called after a successful 207 // call to the Start method. 208 virtual void DidChangePriority(net::RequestPriority new_priority) = 0; 209 210 // Call this method to load the resource synchronously (i.e., in one shot). 211 // This is an alternative to the Start method. Be warned that this method 212 // will block the calling thread until the resource is fully downloaded or an 213 // error occurs. It could block the calling thread for a long time, so only 214 // use this if you really need it! There is also no way for the caller to 215 // interrupt this method. Errors are reported via the status field of the 216 // response parameter. 217 virtual void SyncLoad(SyncLoadResponse* response) = 0; 218 219 protected: 220 // Construction must go through 221 // WebKitPlatformSupportImpl::CreateResourceLoader() 222 // For HTTP(S) POST requests, the AppendDataToUpload and AppendFileToUpload 223 // methods may be called to construct the body of the request. 224 WEBKIT_CHILD_EXPORT ResourceLoaderBridge(); 225 226 private: 227 DISALLOW_COPY_AND_ASSIGN(ResourceLoaderBridge); 228 }; 229 230 } // namespace webkit_glue 231 232 #endif // WEBKIT_CHILD_RESOURCE_LOADER_BRIDGE_H_ 233