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 #ifndef CONTENT_RENDERER_PEPPER_PLUGIN_MODULE_H_
6 #define CONTENT_RENDERER_PEPPER_PLUGIN_MODULE_H_
12 #include "base/basictypes.h"
13 #include "base/files/file_path.h"
14 #include "base/memory/ref_counted.h"
15 #include "base/memory/scoped_ptr.h"
16 #include "base/memory/weak_ptr.h"
17 #include "base/native_library.h"
18 #include "base/process/process.h"
19 #include "content/common/content_export.h"
20 #include "content/public/common/pepper_plugin_info.h"
21 #include "ppapi/c/pp_bool.h"
22 #include "ppapi/c/pp_instance.h"
23 #include "ppapi/c/ppb_core.h"
24 #include "ppapi/c/private/ppb_instance_private.h"
25 #include "ppapi/shared_impl/ppapi_permissions.h"
27 typedef void* NPIdentifier;
36 class CallbackTracker;
37 class WebKitForwarding;
45 class WebPluginContainer;
49 class HostDispatcherWrapper;
50 class PepperPluginInstanceImpl;
52 class RendererPpapiHostImpl;
53 class RenderFrameImpl;
56 // Represents one plugin library loaded into one renderer. This library may
57 // have multiple instances.
59 // Note: to get from a PP_Instance to a PepperPluginInstance*, use the
61 class CONTENT_EXPORT PluginModule : public base::RefCounted<PluginModule>,
62 public base::SupportsWeakPtr<PluginModule> {
64 typedef std::set<PepperPluginInstanceImpl*> PluginInstanceSet;
66 // You must call one of the Init functions after the constructor to create a
67 // module of the type you desire.
69 // The module lifetime delegate is a non-owning pointer that must outlive
70 // all plugin modules. In practice it will be a global singleton that
71 // tracks which modules are alive.
72 PluginModule(const std::string& name,
73 const base::FilePath& path,
74 const ppapi::PpapiPermissions& perms);
76 // Sets the given class as being associated with this module. It will be
77 // deleted when the module is destroyed. You can only set it once, subsequent
79 void SetRendererPpapiHost(scoped_ptr<RendererPpapiHostImpl> host);
81 // Initializes this module as an internal plugin with the given entrypoints.
82 // This is used for "plugins" compiled into Chrome. Returns true on success.
83 // False means that the plugin can not be used.
84 bool InitAsInternalPlugin(const PepperPluginInfo::EntryPoints& entry_points);
86 // Initializes this module using the given library path as the plugin.
87 // Returns true on success. False means that the plugin can not be used.
88 bool InitAsLibrary(const base::FilePath& path);
90 // Initializes this module for the given out of process proxy. This takes
91 // ownership of the given pointer, even in the failure case.
92 void InitAsProxied(HostDispatcherWrapper* host_dispatcher_wrapper);
94 // Creates a new module for an external plugin instance that will be using the
95 // IPC proxy. We can't use the existing module, or new instances of the plugin
97 scoped_refptr<PluginModule> CreateModuleForExternalPluginInstance();
99 // Initializes the external plugin module for the out of process proxy.
100 // InitAsProxied must be called before calling InitAsProxiedExternalPlugin.
101 // Returns a result code indicating whether the proxy started successfully or
102 // there was an error.
103 PP_ExternalPluginResult InitAsProxiedExternalPlugin(
104 PepperPluginInstanceImpl* instance);
106 bool IsProxied() const;
108 // Returns the peer process ID if the plugin is running out of process;
109 // returns |base::kNullProcessId| otherwise.
110 base::ProcessId GetPeerProcessId();
112 // Returns the plugin child process ID if the plugin is running out of
113 // process. Returns 0 otherwise. This is the ID that the browser process uses
114 // to idetify the child process for the plugin. This isn't directly useful
115 // from our process (the renderer) except in messages to the browser to
116 // disambiguate plugins.
117 int GetPluginChildId();
119 static const PPB_Core* GetCore();
121 // Returns whether an interface is supported. This method can be called from
122 // the browser process and used for interface matching before plugin
124 // NOTE: those custom interfaces provided by ContentRendererClient will not be
125 // considered when called on the browser process.
126 static bool SupportsInterface(const char* name);
128 RendererPpapiHostImpl* renderer_ppapi_host() {
129 return renderer_ppapi_host_.get();
132 // Returns the module handle. This may be used before Init() is called (the
133 // proxy needs this information to set itself up properly).
134 PP_Module pp_module() const { return pp_module_; }
136 const std::string& name() const { return name_; }
137 const base::FilePath& path() const { return path_; }
138 const ppapi::PpapiPermissions& permissions() const { return permissions_; }
140 PepperPluginInstanceImpl* CreateInstance(RenderFrameImpl* render_frame,
141 blink::WebPluginContainer* container,
142 const GURL& plugin_url);
144 // Returns "some" plugin instance associated with this module. This is not
145 // guaranteed to be any one in particular. This is normally used to execute
146 // callbacks up to the browser layer that are not inherently per-instance,
147 // but the helper lives only on the plugin instance so we need one of them.
148 PepperPluginInstanceImpl* GetSomeInstance() const;
150 const PluginInstanceSet& GetAllInstances() const { return instances_; }
152 // Calls the plugin's GetInterface and returns the given interface pointer,
153 // which could be NULL.
154 const void* GetPluginInterface(const char* name) const;
156 // This module is associated with a set of instances. The PluginInstance
157 // object declares its association with this module in its destructor and
158 // releases us in its destructor.
159 void InstanceCreated(PepperPluginInstanceImpl* instance);
160 void InstanceDeleted(PepperPluginInstanceImpl* instance);
162 scoped_refptr<ppapi::CallbackTracker> GetCallbackTracker();
164 // Called when running out of process and the plugin crashed. This will
165 // release relevant resources and update all affected instances.
166 void PluginCrashed();
168 bool is_in_destructor() const { return is_in_destructor_; }
169 bool is_crashed() const { return is_crashed_; }
171 // Reserves the given instance is unique within the plugin, checking for
172 // collisions. See PPB_Proxy_Private for more information.
174 // The setter will set the callback which is set up when the proxy
175 // initializes. The Reserve function will call the previously set callback if
176 // it exists to validate the ID. If the callback has not been set (such as
177 // for in-process plugins), the Reserve function will assume that the ID is
178 // usable and will return true.
179 void SetReserveInstanceIDCallback(PP_Bool (*reserve)(PP_Module, PP_Instance));
180 bool ReserveInstanceID(PP_Instance instance);
182 // These should only be called from the main thread.
183 void SetBroker(PepperBroker* broker);
184 PepperBroker* GetBroker();
186 // Create a new HostDispatcher for proxying, hook it to the PluginModule,
187 // and perform other common initialization.
188 RendererPpapiHostImpl* CreateOutOfProcessModule(
189 RenderFrameImpl* render_frame,
190 const base::FilePath& path,
191 ppapi::PpapiPermissions permissions,
192 const IPC::ChannelHandle& channel_handle,
193 base::ProcessId plugin_pid,
197 // In production we purposely leak the HostGlobals object but in unittest
198 // code, this can interfere with subsequent tests. This deletes the
199 // existing HostGlobals. A new one will be constructed when a PluginModule is
201 static void ResetHostGlobalsForTest();
203 // Attempts to create a PPAPI plugin for the given filepath. On success, it
204 // will return the newly-created module.
206 // There are two reasons for failure. The first is that the plugin isn't
207 // a PPAPI plugin. In this case, |*pepper_plugin_was_registered| will be set
208 // to false and the caller may want to fall back on creating an NPAPI plugin.
209 // the second is that the plugin failed to initialize. In this case,
210 // |*pepper_plugin_was_registered| will be set to true and the caller should
211 // not fall back on any other plugin types.
212 static scoped_refptr<PluginModule> Create(RenderFrameImpl* render_frame,
213 const WebPluginInfo& webplugin_info,
214 bool* pepper_plugin_was_registered);
217 friend class base::RefCounted<PluginModule>;
219 // Calls the InitializeModule entrypoint. The entrypoint must have been
220 // set and the plugin must not be out of process (we don't maintain
221 // entrypoints in that case).
222 bool InitializeModule(const PepperPluginInfo::EntryPoints& entry_points);
224 scoped_ptr<RendererPpapiHostImpl> renderer_ppapi_host_;
226 // Tracker for completion callbacks, used mainly to ensure that all callbacks
227 // are properly aborted on module shutdown.
228 scoped_refptr<ppapi::CallbackTracker> callback_tracker_;
230 PP_Module pp_module_;
232 // True when we're running in the destructor. This allows us to write some
234 bool is_in_destructor_;
236 // True if the plugin is running out-of-process and has crashed.
239 // Manages the out of process proxy interface. The presence of this
240 // pointer indicates that the plugin is running out of process and that the
241 // entry_points_ aren't valid.
242 scoped_ptr<HostDispatcherWrapper> host_dispatcher_wrapper_;
244 // Non-owning pointer to the broker for this plugin module, if one exists.
245 // It is populated and cleared in the main thread.
246 PepperBroker* broker_;
248 // Holds a reference to the base::NativeLibrary handle if this PluginModule
249 // instance wraps functions loaded from a library. Can be NULL. If
250 // |library_| is non-NULL, PluginModule will attempt to unload the library
251 // during destruction.
252 base::NativeLibrary library_;
254 // Contains pointers to the entry points of the actual plugin implementation.
255 // These will be NULL for out-of-process plugins, which is indicated by the
256 // presence of the host_dispatcher_wrapper_ value.
257 PepperPluginInfo::EntryPoints entry_points_;
259 // The name and file location of the module.
260 const std::string name_;
261 const base::FilePath path_;
263 ppapi::PpapiPermissions permissions_;
265 // Non-owning pointers to all instances associated with this module. When
266 // there are no more instances, this object should be deleted.
267 PluginInstanceSet instances_;
269 PP_Bool (*reserve_instance_id_)(PP_Module, PP_Instance);
271 DISALLOW_COPY_AND_ASSIGN(PluginModule);
274 } // namespace content
276 #endif // CONTENT_RENDERER_PEPPER_PLUGIN_MODULE_H_