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 browser scriptable container class. The methods on this class 6 // are defined in the specific API directories. 7 8 #ifndef NATIVE_CLIENT_SRC_TRUSTED_PLUGIN_SCRIPTABLE_PLUGIN_H_ 9 #define NATIVE_CLIENT_SRC_TRUSTED_PLUGIN_SCRIPTABLE_PLUGIN_H_ 10 11 #include <vector> 12 13 #include "native_client/src/include/nacl_macros.h" 14 #include "native_client/src/include/portability.h" 15 #include "ppapi/cpp/dev/scriptable_object_deprecated.h" 16 #include "ppapi/cpp/private/var_private.h" 17 #include "ppapi/native_client/src/trusted/plugin/utility.h" 18 19 namespace plugin { 20 21 // Forward declarations for externals. 22 class Plugin; 23 24 // ScriptablePlugin encapsulates plugins that are scriptable from the browser. 25 class ScriptablePlugin : public pp::deprecated::ScriptableObject { 26 public: 27 // Factory method. 28 static ScriptablePlugin* NewPlugin(Plugin* plugin); 29 30 // If not NULL, this var should be reused to pass this object to the browser. 31 pp::VarPrivate* var() { return var_; } 32 33 static void Unref(ScriptablePlugin** handle); 34 35 // Get the contained plugin object. NULL if this contains a descriptor. 36 Plugin* plugin() const { return plugin_; } 37 38 // This function is called when we are about to share the object owned by the 39 // plugin with the browser. Since reference counting on the browser side is 40 // handled via pp::Var's, we create the var() here if not created already. 41 ScriptablePlugin* AddRef(); 42 // Remove a browser reference to this object. 43 // Delete the object when the ref count becomes 0. 44 // If var() is set, we delete it. Otherwise, we delete the object itself. 45 // Therefore, this cannot be called more than once. 46 void Unref(); 47 48 // ------ Methods inherited from pp::deprecated::ScriptableObject: 49 50 // Returns true for preloaded NaCl Plugin properties. 51 // Does not set |exception|. 52 virtual bool HasProperty(const pp::Var& name, pp::Var* exception); 53 // Returns true for preloaded NaCl Plugin methods and SRPC methods exported 54 // from a NaCl module. Does not set |exception|. 55 virtual bool HasMethod(const pp::Var& name, pp::Var* exception); 56 57 // Gets the value of a preloaded NaCl Plugin property. 58 // Sets |exception| on failure. 59 virtual pp::Var GetProperty(const pp::Var& name, pp::Var* exception); 60 // Sets the value of a preloaded NaCl Plugin property. 61 // Does not add new properties. Sets |exception| of failure. 62 virtual void SetProperty(const pp::Var& name, const pp::Var& value, 63 pp::Var* exception); 64 // Set |exception| to indicate that property removal is not supported. 65 virtual void RemoveProperty(const pp::Var& name, pp::Var* exception); 66 // Returns a list of all preloaded NaCl Plugin |properties|. 67 // Does not set |exception|. 68 virtual void GetAllPropertyNames(std::vector<pp::Var>* properties, 69 pp::Var* exception); 70 71 // Calls preloaded NaCl Plugin methods or SRPC methods exported from 72 // a NaCl module. Sets |exception| on failure. 73 virtual pp::Var Call(const pp::Var& name, const std::vector<pp::Var>& args, 74 pp::Var* exception); 75 76 // Sets |exception| to indicate that constructor is not supported. 77 virtual pp::Var Construct(const std::vector<pp::Var>& args, 78 pp::Var* exception); 79 80 private: 81 NACL_DISALLOW_COPY_AND_ASSIGN(ScriptablePlugin); 82 // Prevent construction from outside the class: must use factory New() 83 // method instead. 84 explicit ScriptablePlugin(Plugin* plugin); 85 // This will be called when both the plugin and the browser clear all 86 // references to this object. 87 virtual ~ScriptablePlugin(); 88 89 // When we pass the object owned by the plugin to the browser, we need to wrap 90 // it in a pp::VarPrivate, which also registers the object with the browser 91 // for refcounting. It must be registered only once with all other var 92 // references being copies of the original one. Thus, we record the 93 // pp::VarPrivate here and reuse it when satisfiying additional browser 94 // requests. This way we also ensure that when the browser clears its 95 // references, this object does not get deallocated while we still hold ours. 96 // This is never set for objects that are not shared with the browser nor for 97 // objects created during SRPC calls as they are taken over by the browser on 98 // return. 99 pp::VarPrivate* var_; 100 101 // We should have no more than one internal plugin owner for this object, 102 // and only that owner should call Unref(). To CHECK for that keep a counter. 103 int num_unref_calls_; 104 105 // The contained plugin object. 106 Plugin* plugin_; 107 }; 108 109 } // namespace plugin 110 111 #endif // NATIVE_CLIENT_SRC_TRUSTED_PLUGIN_SCRIPTABLE_PLUGIN_H_ 112