Home | History | Annotate | Download | only in cpp 
      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 #ifndef PPAPI_CPP_MODULE_H_
      6 #define PPAPI_CPP_MODULE_H_
      7 
      8 #include <map>
      9 #include <string>
     10 
     11 #include "ppapi/c/pp_instance.h"
     12 #include "ppapi/c/pp_module.h"
     13 #include "ppapi/c/pp_stdint.h"
     14 #include "ppapi/c/ppb.h"
     15 #include "ppapi/c/ppb_core.h"
     16 #include "ppapi/cpp/core.h"
     17 
     18 
     19 /// @file
     20 /// This file defines a Module class.
     21 namespace pp {
     22 
     23 class Instance;
     24 
     25 /// The Module class.  The browser calls CreateInstance() to create
     26 /// an instance of your module on the web page.  The browser creates a new
     27 /// instance for each <code>\<embed></code> tag with
     28 /// <code>type="application/x-nacl"</code>
     29 class Module {
     30  public:
     31   typedef std::map<PP_Instance, Instance*> InstanceMap;
     32 
     33   // You may not call any other PP functions from the constructor, put them
     34   // in Init instead. Various things will not be set up until the constructor
     35   // completes.
     36   Module();
     37   virtual ~Module();
     38 
     39   /// Get() returns the global instance of this module object, or NULL if the
     40   /// module is not initialized yet.
     41   ///
     42   /// @return The global instance of the module object.
     43   static Module* Get();
     44 
     45   /// Init() is automatically called after the object is created. This is where
     46   /// you can put functions that rely on other parts of the API, now that the
     47   /// module has been created.
     48   ///
     49   /// @return true if successful, otherwise false.
     50   virtual bool Init();
     51 
     52   /// The pp_module() function returns the internal module handle.
     53   ///
     54   /// @return A <code>PP_Module</code> internal module handle.
     55   PP_Module pp_module() const { return pp_module_; }
     56 
     57   /// The get_browser_interface() function returns the internal
     58   /// <code>get_browser_interface</code> pointer.
     59   ///
     60   /// @return A <code>PPB_GetInterface</code> internal pointer.
     61   // TODO(sehr): This should be removed once the NaCl browser plugin no longer
     62   // needs it.
     63   PPB_GetInterface get_browser_interface() const {
     64     return get_browser_interface_;
     65   }
     66 
     67   /// The core() function returns the core interface for doing basic
     68   /// global operations. The return value is guaranteed to be non-NULL once the
     69   /// module has successfully initialized and during the Init() call.
     70   ///
     71   /// It will be NULL before Init() has been called.
     72   ///
     73   /// @return The core interface for doing basic global operations.
     74   Core* core() { return core_; }
     75 
     76   /// GetPluginInterface() implements <code>GetInterface</code> for the browser
     77   /// to get module interfaces. If you need to provide your own implementations
     78   /// of new interfaces, use AddPluginInterface() which this function will use.
     79   ///
     80   /// @param[in] interface_name The module interface for the browser to get.
     81   const void* GetPluginInterface(const char* interface_name);
     82 
     83   /// GetBrowserInterface() returns interfaces which the browser implements
     84   /// (i.e. PPB interfaces).
     85   /// @param[in] interface_name The browser interface for the module to get.
     86   const void* GetBrowserInterface(const char* interface_name);
     87 
     88   /// InstanceForPPInstance() returns the object associated with this
     89   /// <code>PP_Instance</code>, or NULL if one is not found. This should only
     90   /// be called from the main thread! This instance object may be destroyed at
     91   /// any time on the main thread, so using it on other threads may cause a
     92   /// crash.
     93   ///
     94   /// @param[in] instance This <code>PP_Instance</code>.
     95   ///
     96   /// @return The object associated with this <code>PP_Instance</code>,
     97   /// or NULL if one is not found.
     98   Instance* InstanceForPPInstance(PP_Instance instance);
     99 
    100   /// AddPluginInterface() adds a handler for a provided interface name. When
    101   /// the browser requests that interface name, the provided
    102   /// <code>vtable</code> will be returned.
    103   ///
    104   /// In general, modules will not need to call this directly. Instead, the
    105   /// C++ wrappers for each interface will register themselves with this
    106   /// function.
    107   ///
    108   /// This function may be called more than once with the same interface name
    109   /// and vtable with no effect. However, it may not be used to register a
    110   /// different vtable for an already-registered interface. It will assert for
    111   /// a different registration for an already-registered interface in debug
    112   /// mode, and just ignore the registration in release mode.
    113   ///
    114   /// @param[in] interface_name The interface name that will receive a handler.
    115   /// @param[in,out] vtable The vtable to return for
    116   /// <code>interface_name</code>.
    117   void AddPluginInterface(const std::string& interface_name,
    118                           const void* vtable);
    119 
    120   // InternalInit() sets the browser interface and calls the regular Init()
    121   /// function that can be overridden by the base classes.
    122   ///
    123   /// @param[in] mod A <code>PP_Module</code>.
    124   /// @param[in] get_browser_interface The browser interface to set.
    125   ///
    126   /// @return true if successful, otherwise false.
    127   // TODO(brettw) make this private when I can figure out how to make the
    128   // initialize function a friend.
    129   bool InternalInit(PP_Module mod,
    130                     PPB_GetInterface get_browser_interface);
    131 
    132   /// The current_instances() function allows iteration over the
    133   /// current instances in the module.
    134   ///
    135   /// @return An <code>InstanceMap</code> of all instances in the module.
    136   const InstanceMap& current_instances() const { return current_instances_; }
    137 
    138  protected:
    139   /// CreateInstance() should be overridden to create your own module type.
    140   ///
    141   /// @param[in] instance A <code>PP_Instance</code>.
    142   ///
    143   /// @return The resulting instance.
    144   virtual Instance* CreateInstance(PP_Instance instance) = 0;
    145 
    146  private:
    147   friend PP_Bool Instance_DidCreate(PP_Instance pp_instance,
    148                                     uint32_t argc,
    149                                     const char* argn[],
    150                                     const char* argv[]);
    151   friend void Instance_DidDestroy(PP_Instance instance);
    152 
    153   // Unimplemented (disallow copy and assign).
    154   Module(const Module&);
    155   Module& operator=(const Module&);
    156 
    157   // Instance tracking.
    158   InstanceMap current_instances_;
    159 
    160   PP_Module pp_module_;
    161   PPB_GetInterface get_browser_interface_;
    162 
    163   Core* core_;
    164 
    165   // All additional interfaces this plugin can handle as registered by
    166   // AddPluginInterface.
    167   typedef std::map<std::string, const void*> InterfaceMap;
    168   InterfaceMap additional_interfaces_;
    169 };
    170 
    171 }  // namespace pp
    172 
    173 #endif  // PPAPI_CPP_MODULE_H_
    174