Home | History | Annotate | Download | only in plugin 
      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