Step 3: Scripting plug-in

3.1  Plug-in scriptability.

Plug-in scriptability is a feature allowing JavaScript code in a web page to interact with the plug-in. A plug-in that wishes to be scriptable needs to return the appropriate NPObject (which is created by calling NPN_CreateObject()) when the browser requests it by calling:


NPP_GetValue(npp, NPPVpluginScriptableNPObject, ...);

3.1.1  How to call plug-in native methods using HTML code:


<embed id="embed_id" type="application/your-plugin-mimetype"> </embed>
<script>
  var yourembed = document.getElementById('embed_id');
  yourembed.fun();       //Plug-in's Native Method
  alert(yourembed.prop);  //Plug-in's Native Property
  yourembed();           //Plug-in's Default Method
</script>

3.1.2  Implementation in plug-in code.

Note:TScriptablePluginObj indicates the instance of a scriptable plug-in object, it is inherited from NPObject.Below is the related data type.



class TScriptablePluginObj : public NPObject
{
public:

  TScriptablePluginObj(NPP pNPInstance);

  ~TScriptablePluginObj();

  ...
  
  virtual bool IsMethod(NPIdentifier npName);
  virtual bool IsProperty(NPIdentifier npName);
  virtual bool GetProperty(NPIdentifier npName, NPVariant *npResult);
  virtual bool Invoke(NPIdentifier npName,
                      const NPVariant *npArgs,
                      uint32_t npArgCount,
                      NPVariant *npResult);
  virtual bool InvokeDefault(const NPVariant *npArgs,
                             uint32_t npArgCount,
                             NPVariant *npResult);

  ...
};

And below is the Implementation.

3.2  Accessing browser objects from a plug-in.

A plug-in that wishes to access objects in the browser window that loaded the plug-in can do this by getting the NPObject for the browsers window object, or the DOM element that loaded the plug-in. This is done by using an extension to NPN_GetValue(). The extensions are two additions to the NPNVariables enumeration, the new enumerations are NPNVWindowNPObject and NPNVPluginElementNPObject. By calling NPN_GetValue() with either of those new enumerations will return an NPObject representing the browser object, and from there, the functions in this API can be used to get and set properties, and to call methods on those browser objects.

And as always when working with reference counted NPObjects, the caller is responsible for calling NPN_ReleaseObject() on the NPObject to drop the reference.

The new NPNVariable enumerations are defined in npapi.h as:

NPNVWindowNPObject = 15,
NPNVPluginElementNPObject = 16

Below are some simple code pieces:


static NPIdentifier npDoc_id;
static NPIdentifier npCreateTextNode_id;
static NPObject *npWinObj;

NPN_GetValue(m_pNPInstance, NPNVWindowNPObject, &npWinObj);//Get browser window object.

npDoc_id = NPN_GetStringIdentifier("document");
npCreateTextNode_id = NPN_GetStringIdentifier("createTextNode");

NPVariant npDocument;
NPN_GetProperty(mNpp, npWinObj, npDoc_id, &npDocument);

NPObject *doc = NPVARIANT_TO_OBJECT(npDocument);

NPVariant npStrv;

STRINGZ_TO_NPVARIANT("This is a plugin element!", npStrv);

NPVariant npTextv;
NPN_Invoke(mNpp, doc, npCreateTextNode_id, &npStrv, 1, &npTextv);//Add a text node to the browser window.

3.3  The The Plug-in APIs Introduction

The Plug-in Application Programming Interface (API) is made up of two groups of functions and a set of shared data structures.

Plug-in Side Plug-in APIs

This section is intended to briefly describe some important methods in the plug-in APIs that are available for the plug-in object.The names of all of these methods begin with NPP_ to indicate that they are implemented by the plug-in and called by the browser.

For all the plug-in APIs that are available for the plug-in object and all details, please refer to plug-in side APIs

Browser Side Plug-in APIs

This section is intended to briefly describe some important methods in the plug-in APIs that are available for the browser.The names of all of these methods begin with NPN_ to indicate that they are implemented by the browser and called by the plug-in.

For all the plug-in APIs that are available for the browser and all details, please refer to browser side APIs

Structures

This section is intended to briefly describe some important data structures that are used to represent the various objects in the plug-in API

For the details of all data structures, please refer to structures