content/public/renderer/renderer_ppapi_host.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 #ifndef CONTENT_PUBLIC_RENDERER_RENDERER_PPAPI_HOST_H_
   6 #define CONTENT_PUBLIC_RENDERER_RENDERER_PPAPI_HOST_H_
   7
   8 #include <vector>
   9
  10 #include "base/callback_forward.h"
  11 #include "base/files/file.h"
  12 #include "base/memory/ref_counted.h"
  13 #include "base/process/process.h"
  14 #include "content/common/content_export.h"
  15 #include "ipc/ipc_platform_file.h"
  16 #include "ppapi/c/pp_instance.h"
  17 #include "url/gurl.h"
  18
  19 namespace base {
  20 class FilePath;
  21 }
  22
  23 namespace gfx {
  24 class Point;
  25 }
  26
  27 namespace IPC {
  28 class Message;
  29 }
  30
  31 namespace ppapi {
  32 namespace host {
  33 class PpapiHost;
  34 }
  35 }
  36
  37 namespace blink {
  38 class WebPluginContainer;
  39 }
  40
  41 namespace content {
  42 class PepperPluginInstance;
  43 class RenderFrame;
  44 class RenderView;
  45
  46 // Interface that allows components in the embedder app to talk to the
  47 // PpapiHost in the renderer process.
  48 //
  49 // There will be one of these objects in the renderer per plugin module.
  50 class RendererPpapiHost {
  51  public:
  52   // Returns the RendererPpapiHost associated with the given PP_Instance,
  53   // or NULL if the instance is invalid.
  54   //
  55   // Do NOT use this when dealing with an "external plugin" that serves as a
  56   // bootstrap to load a second plugin. This is because the two will share a
  57   // PP_Instance, and the RendererPpapiHost* for the second plugin will be
  58   // returned after we switch the proxy on.
  59   CONTENT_EXPORT static RendererPpapiHost* GetForPPInstance(
  60       PP_Instance instance);
  61
  62   // Returns the PpapiHost object.
  63   virtual ppapi::host::PpapiHost* GetPpapiHost() = 0;
  64
  65   // Returns true if the given PP_Instance is valid and belongs to the
  66   // plugin associated with this host.
  67   virtual bool IsValidInstance(PP_Instance instance) const = 0;
  68
  69   // Returns the PluginInstance for the given PP_Instance, or NULL if the
  70   // PP_Instance is invalid (the common case this will be invalid is during
  71   // plugin teardown when resource hosts are being force-freed).
  72   virtual PepperPluginInstance* GetPluginInstance(
  73       PP_Instance instance) const = 0;
  74
  75   // Returns the RenderFrame for the given plugin instance, or NULL if the
  76   // instance is invalid.
  77   virtual RenderFrame* GetRenderFrameForInstance(
  78       PP_Instance instance) const = 0;
  79
  80   // Returns the RenderView for the given plugin instance, or NULL if the
  81   // instance is invalid.
  82   virtual RenderView* GetRenderViewForInstance(PP_Instance instance) const = 0;
  83
  84   // Returns the WebPluginContainer for the given plugin instance, or NULL if
  85   // the instance is invalid.
  86   virtual blink::WebPluginContainer* GetContainerForInstance(
  87       PP_Instance instance) const = 0;
  88
  89   // Returns the PID of the child process containing the plugin. If running
  90   // in-process, this returns base::kNullProcessId.
  91   virtual base::ProcessId GetPluginPID() const = 0;
  92
  93   // Returns true if the given instance is considered to be currently
  94   // processing a user gesture or the plugin module has the "override user
  95   // gesture" flag set (in which case it can always do things normally
  96   // restricted by user gestures). Returns false if the instance is invalid or
  97   // if there is no current user gesture.
  98   virtual bool HasUserGesture(PP_Instance instance) const = 0;
  99
 100   // Returns the routing ID for the render widget containing the given
 101   // instance. This will take into account the current Flash fullscreen state,
 102   // so if there is a Flash fullscreen instance active, this will return the
 103   // routing ID of the fullscreen widget. Returns 0 on failure.
 104   virtual int GetRoutingIDForWidget(PP_Instance instance) const = 0;
 105
 106   // Converts the given plugin coordinate to the containing RenderFrame. This
 107   // will take into account the current Flash fullscreen state so will use
 108   // the fullscreen widget if it's displayed.
 109   virtual gfx::Point PluginPointToRenderFrame(
 110       PP_Instance instance,
 111       const gfx::Point& pt) const = 0;
 112
 113   // Shares a file handle (HANDLE / file descriptor) with the remote side. It
 114   // returns a handle that should be sent in exactly one IPC message. Upon
 115   // receipt, the remote side then owns that handle. Note: if sending the
 116   // message fails, the returned handle is properly closed by the IPC system. If
 117   // |should_close_source| is set to true, the original handle is closed by this
 118   // operation and should not be used again.
 119   virtual IPC::PlatformFileForTransit ShareHandleWithRemote(
 120       base::PlatformFile handle,
 121       bool should_close_source) = 0;
 122
 123   // Returns true if the plugin is running in process.
 124   virtual bool IsRunningInProcess() const = 0;
 125
 126   virtual std::string GetPluginName() const = 0;
 127
 128   // Used by the embedder to inform this RendererPpapiHost that the associated
 129   // plugin module is a host for "external plugins."
 130   //
 131   // An embedder may, at the time a plugin module is created, configure it to
 132   // be a host for external plugins. Instances of such plugins go through two
 133   // two stages of initialization; the first stage initializes a host plugin
 134   // instance, which then loads and initializes a child plugin which takes
 135   // over control. These are treated as one Pepper Instance, because despite the
 136   // two-stage initialization process, the host and child appear to blink as
 137   // one plugin instance.
 138   //
 139   // The host plugin appears as an in-process plugin, while we interact with the
 140   // child plugin via the Pepper proxy.
 141   virtual void SetToExternalPluginHost() = 0;
 142
 143   // There are times when the renderer needs to create a ResourceHost in the
 144   // browser. This function does so asynchronously. |nested_msgs| is a list of
 145   // resource host creation messages and |instance| is the PP_Instance which
 146   // the resource will belong to. |callback| will be called asynchronously with
 147   // the pending host IDs when the ResourceHosts have been created. This can be
 148   // passed back to the plugin to attach to the ResourceHosts. Pending IDs of 0
 149   // will be passed to the callback if a ResourceHost fails to be created.
 150   virtual void CreateBrowserResourceHosts(
 151       PP_Instance instance,
 152       const std::vector<IPC::Message>& nested_msgs,
 153       const base::Callback<void(const std::vector<int>&)>& callback) const = 0;
 154
 155   // Gets the URL of the document containing the given PP_Instance.
 156   // Returns an empty URL if the instance is invalid.
 157   // TODO(yzshen): Some methods such as this one don't need to be pure virtual.
 158   // Instead, they could be directly implemented using other methods in this
 159   // interface. Consider changing them to static helpers.
 160   virtual GURL GetDocumentURL(PP_Instance instance) const = 0;
 161
 162  protected:
 163   virtual ~RendererPpapiHost() {}
 164 };
 165
 166 }  // namespace content
 167
 168 #endif  // CONTENT_PUBLIC_RENDERER_RENDERER_PPAPI_HOST_H_