src/webkit/child/resource_loader_bridge.h

   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     blink::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     blink::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 WEBKIT_CHILD_EXPORT 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     // 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).
 159     virtual void OnDownloadedData(int len, int encoded_data_length) = 0;
 160
 161     // Called when a chunk of response data is available. This method may
 162     // be called multiple times or not at all if an error occurs.
 163     // The encoded_data_length is the length of the encoded data transferred
 164     // over the network, which could be different from data length (e.g. for
 165     // gzipped content).
 166     virtual void OnReceivedData(const char* data,
 167                                 int data_length,
 168                                 int encoded_data_length) = 0;
 169
 170     // Called when metadata generated by the renderer is retrieved from the
 171     // cache. This method may be called zero or one times.
 172     virtual void OnReceivedCachedMetadata(const char* data, int len) { }
 173
 174     // Called when the response is complete.  This method signals completion of
 175     // the resource load.
 176     virtual void OnCompletedRequest(
 177         int error_code,
 178         bool was_ignored_by_handler,
 179         bool stale_copy_in_cache,
 180         const std::string& security_info,
 181         const base::TimeTicks& completion_time,
 182         int64 total_transfer_size) = 0;
 183
 184    protected:
 185     virtual ~Peer() {}
 186   };
 187
 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();
 191
 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;
 195
 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;
 199
 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;
 205
 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;
 209
 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;
 214
 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;
 223
 224  protected:
 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();
 230
 231  private:
 232   DISALLOW_COPY_AND_ASSIGN(ResourceLoaderBridge);
 233 };
 234
 235 }  // namespace webkit_glue
 236
 237 #endif  // WEBKIT_CHILD_RESOURCE_LOADER_BRIDGE_H_