ppapi/native_client/src/trusted/plugin/scriptable_plugin.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 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_