Added documentation to web_view.js/web_view_experimental.js regarding the webview...
[chromium-blink-merge.git] / ppapi / shared_impl / resource.h
blob8c6e7d6fdd0d3b97c6a0ef31f1d5205a894ad107
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 PPAPI_SHARED_IMPL_RESOURCE_H_
6 #define PPAPI_SHARED_IMPL_RESOURCE_H_
8 #include <stddef.h> // For NULL.
10 #include <string>
12 #include "base/basictypes.h"
13 #include "base/memory/ref_counted.h"
14 #include "ppapi/c/pp_instance.h"
15 #include "ppapi/c/pp_resource.h"
16 #include "ppapi/c/ppb_console.h"
17 #include "ppapi/shared_impl/host_resource.h"
19 // All resource types should be added here. This implements our hand-rolled
20 // RTTI system since we don't compile with "real" RTTI.
21 #define FOR_ALL_PPAPI_RESOURCE_APIS(F) \
22 F(ExtensionsCommon_API) \
23 F(PPB_Audio_API) \
24 F(PPB_AudioConfig_API) \
25 F(PPB_AudioFrame_API) \
26 F(PPB_AudioInput_API) \
27 F(PPB_AudioTrusted_API) \
28 F(PPB_Broker_API) \
29 F(PPB_Broker_Instance_API) \
30 F(PPB_BrowserFont_Singleton_API) \
31 F(PPB_BrowserFont_Trusted_API) \
32 F(PPB_Buffer_API) \
33 F(PPB_DeviceRef_API) \
34 F(PPB_Ext_CrxFileSystem_Private_API) \
35 F(PPB_FileChooser_API) \
36 F(PPB_FileIO_API) \
37 F(PPB_FileRef_API) \
38 F(PPB_FileSystem_API) \
39 F(PPB_Find_API) \
40 F(PPB_Flash_Clipboard_API) \
41 F(PPB_Flash_DRM_API) \
42 F(PPB_Flash_File_API) \
43 F(PPB_Flash_FontFile_API) \
44 F(PPB_Flash_Fullscreen_API) \
45 F(PPB_Flash_Functions_API) \
46 F(PPB_Flash_Menu_API) \
47 F(PPB_Flash_MessageLoop_API) \
48 F(PPB_Gamepad_API) \
49 F(PPB_Graphics2D_API) \
50 F(PPB_Graphics3D_API) \
51 F(PPB_HostResolver_API) \
52 F(PPB_HostResolver_Private_API) \
53 F(PPB_ImageData_API) \
54 F(PPB_InputEvent_API) \
55 F(PPB_IsolatedFileSystem_Private_API) \
56 F(PPB_LayerCompositor_API) \
57 F(PPB_MediaStreamAudioTrack_API) \
58 F(PPB_MediaStreamVideoTrack_API) \
59 F(PPB_MessageLoop_API) \
60 F(PPB_NetAddress_API) \
61 F(PPB_NetworkList_API) \
62 F(PPB_NetworkMonitor_API) \
63 F(PPB_NetworkProxy_API) \
64 F(PPB_OutputProtection_API) \
65 F(PPB_PDF_API) \
66 F(PPB_PlatformVerification_API) \
67 F(PPB_Printing_API) \
68 F(PPB_Scrollbar_API) \
69 F(PPB_Talk_Private_API) \
70 F(PPB_TrueTypeFont_API) \
71 F(PPB_TrueTypeFont_Singleton_API) \
72 F(PPB_TCPServerSocket_Private_API) \
73 F(PPB_TCPSocket_API) \
74 F(PPB_TCPSocket_Private_API) \
75 F(PPB_UDPSocket_API) \
76 F(PPB_UDPSocket_Private_API) \
77 F(PPB_URLLoader_API) \
78 F(PPB_URLRequestInfo_API) \
79 F(PPB_URLResponseInfo_API) \
80 F(PPB_VideoCapture_API) \
81 F(PPB_VideoDecoder_API) \
82 F(PPB_VideoDestination_Private_API) \
83 F(PPB_VideoFrame_API) \
84 F(PPB_VideoLayer_API) \
85 F(PPB_VideoSource_Private_API) \
86 F(PPB_View_API) \
87 F(PPB_WebSocket_API) \
88 F(PPB_Widget_API) \
89 F(PPB_X509Certificate_Private_API)
91 namespace IPC {
92 class Message;
95 namespace ppapi {
97 // Normally we shouldn't reply on proxy here, but this is to support
98 // OnReplyReceived. See that comment.
99 namespace proxy {
100 class ResourceMessageReplyParams;
103 // Forward declare all the resource APIs.
104 namespace thunk {
105 #define DECLARE_RESOURCE_CLASS(RESOURCE) class RESOURCE;
106 FOR_ALL_PPAPI_RESOURCE_APIS(DECLARE_RESOURCE_CLASS)
107 #undef DECLARE_RESOURCE_CLASS
108 } // namespace thunk
110 // Resources have slightly different registration behaviors when the're an
111 // in-process ("impl") resource in the host (renderer) process, or when they're
112 // a proxied resource in the plugin process. This enum differentiates those
113 // cases.
114 enum ResourceObjectType {
115 OBJECT_IS_IMPL,
116 OBJECT_IS_PROXY
119 class PPAPI_SHARED_EXPORT Resource : public base::RefCounted<Resource> {
120 public:
121 // Constructor for impl and non-proxied, instance-only objects.
123 // For constructing "impl" (non-proxied) objects, this just takes the
124 // associated instance, and generates a new resource ID. The host resource
125 // will be the same as the newly-generated resource ID. For all objects in
126 // the renderer (host) process, you'll use this constructor and call it with
127 // OBJECT_IS_IMPL.
129 // For proxied objects, this will create an "instance-only" object which
130 // lives only in the plugin and doesn't have a corresponding object in the
131 // host. If you have a host resource ID, use the constructor below which
132 // takes that HostResource value.
133 Resource(ResourceObjectType type, PP_Instance instance);
135 // For constructing given a host resource.
137 // For OBJECT_IS_PROXY objects, this takes the resource generated in the host
138 // side, stores it, and allocates a "local" resource ID for use in the
139 // current process.
141 // For OBJECT_IS_IMPL, the host resource ID must be 0, since there should be
142 // no host resource generated (impl objects should generate their own). The
143 // reason for supporting this constructor at all for the IMPL case is that
144 // some shared objects use a host resource for both modes to keep things the
145 // same.
146 Resource(ResourceObjectType type, const HostResource& host_resource);
148 // Constructor for untracked objects. These have no associated instance. Use
149 // this with care, as the object is likely to persist for the lifetime of the
150 // plugin module. This is appropriate in some rare cases, like the
151 // PPB_MessageLoop resource for the main thread.
152 struct Untracked {};
153 explicit Resource(Untracked);
155 virtual ~Resource();
157 PP_Instance pp_instance() const { return host_resource_.instance(); }
159 // Returns the resource ID for this object in the current process without
160 // adjusting the refcount. See also GetReference().
161 PP_Resource pp_resource() const { return pp_resource_; }
163 // Returns the host resource which identifies the resource in the host side
164 // of the process in the case of proxied objects. For in-process objects,
165 // this just identifies the in-process resource ID & instance.
166 const HostResource& host_resource() { return host_resource_; }
168 // Adds a ref on behalf of the plugin and returns the resource ID. This is
169 // normally used when returning a resource to the plugin, where it's
170 // expecting the returned resource to have ownership of a ref passed.
171 // See also pp_resource() to avoid the AddRef.
172 PP_Resource GetReference();
174 // Called by the resource tracker when the last reference from the plugin
175 // was released. For a few types of resources, the resource could still
176 // stay alive if there are other references held by the PPAPI implementation
177 // (possibly for callbacks and things).
179 // Note that subclasses except PluginResource should override
180 // LastPluginRefWasDeleted() to be notified.
181 virtual void NotifyLastPluginRefWasDeleted();
183 // Called by the resource tracker when the instance is going away but the
184 // object is still alive (this is not the common case, since it requires
185 // something in the implementation to be keeping a ref that keeps the
186 // resource alive.
188 // You will want to override this if your resource does some kind of
189 // background processing (like maybe network loads) on behalf of the plugin
190 // and you want to stop that when the plugin is deleted.
192 // Note that subclasses except PluginResource should override
193 // InstanceWasDeleted() to be notified.
194 virtual void NotifyInstanceWasDeleted();
196 // Dynamic casting for this object. Returns the pointer to the given type if
197 // it's supported. Derived classes override the functions they support to
198 // return the interface.
199 #define DEFINE_TYPE_GETTER(RESOURCE) \
200 virtual thunk::RESOURCE* As##RESOURCE();
201 FOR_ALL_PPAPI_RESOURCE_APIS(DEFINE_TYPE_GETTER)
202 #undef DEFINE_TYPE_GETTER
204 // Template-based dynamic casting. See specializations below. This is
205 // unimplemented for the default case. This way, for anything that's not a
206 // resource (or if a developer forgets to add the resource to the list in
207 // this file), the result is a linker error.
208 template <typename T> T* GetAs();
210 // Called when a PpapiPluginMsg_ResourceReply reply is received for a
211 // previous CallRenderer. The message is the nested reply message, which may
212 // be an empty message (depending on what the host sends).
214 // The default implementation will assert (if you send a request, you should
215 // override this function).
217 // (This function would make more conceptual sense on PluginResource but we
218 // need to call this function from general code that doesn't know how to
219 // distinguish the classes.)
220 virtual void OnReplyReceived(const proxy::ResourceMessageReplyParams& params,
221 const IPC::Message& msg);
223 protected:
224 // Logs a message to the console from this resource.
225 void Log(PP_LogLevel level, const std::string& message);
227 // Removes the resource from the ResourceTracker's tables. This normally
228 // happens as part of Resource destruction, but if a subclass destructor
229 // has a risk of re-entering destruction via the ResourceTracker, it can
230 // call this explicitly to get rid of the table entry before continuing
231 // with the destruction. If the resource is not in the ResourceTracker's
232 // tables, silently does nothing. See http://crbug.com/159429.
233 void RemoveFromResourceTracker();
235 // Notifications for subclasses.
236 virtual void LastPluginRefWasDeleted() {}
237 virtual void InstanceWasDeleted() {}
239 private:
240 // See the getters above.
241 PP_Resource pp_resource_;
242 HostResource host_resource_;
244 DISALLOW_IMPLICIT_CONSTRUCTORS(Resource);
247 // Template-based dynamic casting. These specializations forward to the
248 // AsXXX virtual functions to return whether the given type is supported.
249 #define DEFINE_RESOURCE_CAST(RESOURCE) \
250 template<> inline thunk::RESOURCE* Resource::GetAs() { \
251 return As##RESOURCE(); \
253 FOR_ALL_PPAPI_RESOURCE_APIS(DEFINE_RESOURCE_CAST)
254 #undef DEFINE_RESOURCE_CAST
256 } // namespace ppapi
258 #endif // PPAPI_SHARED_IMPL_RESOURCE_H_