Yes, I wrote FireBreath. A lot of others have contributed.

A different approach to learning NPAPI

Now that I have a good example already up and running, it seems pointless to keep trying to describe things with words and code snippets when I can simply walk you through what I have done — what is in use and works well. To that end, and in hopes that it will foster more capable NPAPI developers to help with FireBreath development (we still don’t support printing, for example), I have created a series of 5 minute screencasts providing a brief overview of FireBreath’s NPAPI framework.

I don’t expect that this is as comprehensive as it should be; I’m hoping that comments will help me see what future segments I should create.  I have posted these screencasts on youtube and will link to them from here. You can also find a more complete series that includes this one on the FireBreath website.

One of the least understood concepts in the Browser Plugin world is — browser plugins.  What they are, and even more: what they are not.  Probably at least once a week I answer a question somewhere on a forum or on the comments on this blog and say “You can’t do that with a plugin; you need an extension”.

Many people confuse plugins and extensions in the browser world. They sound like they should be the same thing, but in fact they are very different.

What you can do with a plugin

A plugin is, quite simply, a third party library that “plugs in” to the browser that can be embedded inside a web page using an <embed> tag or a <object> tag.  Many of them then draw pretty pictures or animations, though that’s not required.  Many allow you to talk to them through javascript, though that’s not required.  In short, a plugin affects only a specific page in which it is placed.

Examples of common plugins include:

• Macromedia Flash
• Microsoft Silverlight
• Apple Quicktime
• Adobe Reader (at least this includes a plugin in addition to the rest of the application)

Some plugins respond to a mime type and can run in place of the page, such as Adobe Reader, which allows you to view PDF files in your web browser.  Again, however, it affects only that page, and no others.  In Firefox, Chrome, Opera, and Safari, these plugins are usually called “NPAPI plugins”, since they are written using the NPAPI.  In Safari, you could also use a Webkit Plugin.  In Internet Explorer you would do this with an ActiveX Control.

What a plugin cannot do

Plugins have to either handle a mime type or be embedded into a web page.  They don’t get put there automatically. They don’t create toolbars.  They don’t affect browser menus.  They don’t know about tabs, or even about other pages in the same browser process.  They don’t make coffee, tea, or hot chocolate, though they could be written to control an external appliance to do so if you really wanted.  They don’t automatically process the content of every web page loaded.

“But wait!” I hear you all cry.  “We have seen these magical things done! (well, except the hot chocolate machine)”

“Yes,” I reply.  “Those are extensions.”

Extensions

Extensions, or “add-ons”, can often do these magical things.  They can add onto the browser UI, process pages that the browser loads.  They do all sorts of things.  However, they are not the same thing as plugins; they affect the web browser itself, not really the page.  They may affect a page as well, of course.  In fact, you can even put a plugin inside an extension, at least in Firefox.  However, if you write an extension for Firefox, you’ll probably have to write it again for Chrome, Safari, and IE… one for each.  Perhaps there is a framework out there for writing portable extensions, though.  It’s not really my area of expertise, so I don’t know.

Examples of extensions / add-ons:

• DownThemAll for Firefox
• Firebug for Firefox
• Google Voice extension for Chrome
• Let there be Comic Sans for Safari

And many, many, many more.  Extensions can be written in different languages depending on the browser.  In Firefox you can write them in C++ or javascript, and on Internet Explorer you write them as special ActiveX controls called Browser Helper Objects, or BHOs.

An extension could contain a plugin, but a plugin can’t contain an extension

One very common way to install a plugin in Firefox is to use a .xpi file.  This is an extension.  It may have a NPAPI plugin inside of it, but it is still an extension.  It will not work on other web browsers, even though your NPAPI plugin may work perfectly fine on Chrome and Safari if installed in another way.

Conversely, a plugin by nature does not include an extension.

FireBreath

Nearly a year ago now I began a project called FireBreath, which is a cross-platform browser plugin architecture.  FireBreath is, frankly, awesome. You can literally get a plugin up and going in under 10 minutes if you already have everything installed.  That means you can spend your time doing other more important things, like actually developing your functionality, rather than spending all your time figuring out how to deal with the plugin APIs.

That said, FireBreath is a cross-platform browser PLUGIN framework.  It does not create extensions.  It will never be able to create extensions.  If you need an extension, you need something else.

When not to use a plugin

Finally, and this is a topic that people seem to think is a little strange coming from me, there are many cases when it is not a good idea to use a browser plugin.  In fact, a good rule of thumb is that if you can do what you need to do without one, don’t use one.

Why?

• There are no really good ways to install browser plugins that will work 100% of the time
  • XPI install only works on one profile in firefox
  • CAB install only works in Internet Explorer and is sometimes a little unreliable
  • ClickOnce works only in Windows and only if .Net is installed
  • Java installers only work reliably and consistently on Mac OS
  • MSI or EXE installers while being the best method IMHO require a little more work on the part of the user, and the average user is… less savvy than you are, shall we say.
• Plugins have to take into account a large range of hardware types
  • If you use graphics libraries such as OpenGL or DirectX keep in mind that every graphics card works a little differently with these technologies.  You will run into weird cases where your plugin doesn’t work on someone’s computer.  If your luck is like mine, that computer will belong to an executive at a fortune 500 company (yes, that happened to me.  no, it wasn’t fun)
• Plugins don’t work until they have been installed
  • This is a major limiting factor to uptake of your site.  Many users don’t want to install yet another plugin on their machine, and many get lost in the incredibly complicated task of downloading and running the installer.

Moving on

If all of those things haven’t convinced you that what you want isn’t actually a browser plugin — great!  That’s why I’m still posting about this stuff.  Despite all the reasons not to use a plugin, there are also a lot of cases where it’s a good idea. Browesr plugin development can be a lot of fun!  Good luck!

Firefox 3.6 has removed support for XPCOM plugins.

This means that if you use XPCOM for your javascript interface (i.e. you have an IDL file on your npapi plugin, you us nsScriptablePeer, etc) your plugin will no longer be able to communicate with javascript in Firefox 3.6.

Thus I repeat advice that I have given in the past: Never, never, *never*, *ever* use XPCOM for your javascript interface in your plugin.

There might conceivably be reasons to use other aspects of XPCOM in a plugin, that might even work in other browsers. At present, I don’t know of them. Please enlighten me if there are (cookies?).

Oh, yeah, and FireBreath now has linux and mac support (experimental) as well as windows support (stable). Come join the fun. http://firebreath.googlecode.com

Thank you. :-P

I’ll be up-front about something here; I don’t particularly like ActiveX.  I understand a lot of the reasons for creating it, and I won’t go so far as to claim that it shouldn’t exist or anything like that; in fact, it does very well for certain types of things.  The main thing I don’t like about it is the complexity; it’s not something that you just pick up and start using one day.  You have to do a lot of research to understand what is happening, and though I’ve been working on ActiveX Controls hosted in Internet Explorer for over a year now, there is still a lot I don’t understand about what is really happening under the covers.

Because of this, I am a big fan of NPAPI.  I think it’s a great technology.  It’s simple.  It’s straightforward.  It provides an interface for one purpose, and that is to allow 3rd party developers to write browser plugins.  It’s great.  But, there is a problem: in my world, you can’t just say “I like Firefox better than IE, so I’m not going to support IE.”  Why?  I will make no claims here about security, usability, viability, or even disability of any browsers.  I will simply refer to one statistic: according to the w3schools browser statistics, Internet Explorer accounted for over 25% of the total web traffic every month last year.

So we find the classic challenge of all browser plugin developers: Internet Explorer only supports ActiveX controls, other browsers support NPAPI, and a plugin written for one isn’t neccesarily going to be easy to just port to the other.  Thus was born FireBreath, in an attempt to solve this issue.  Today, however, I want to address only one piece of the solution that we use in FireBreath:  How to create a scripting interface that will be “write once, run anywhere” on web browsers.

Common Scripting Interface

When I first began working on plugins, I worked on a project that had 3 seperate defintions of the javascript interface to the plugin.  One was for Mac, one for Internet Explorer on Windows, and one for Firefox on Windows.  The IE version was defined in an ActiveX .idl file and implemented in an ActiveX object.  The Firefox/win one was defined in an “XPCOM” .idl file and implemented in a nsScriptablePeer object (copied from a sample plugin from the mozilla source), and the Mac one was defined using NPRuntime and wrapped the XPCOM class.

This was, in short, a nightmare.

The problem I was initially trying to solve is that we had some APIs that had to be used differently on Mac and Windows, and they differed in less noticeable ways between Firefox and IE on Windows.  Don’t get me wrong — it all worked just fine.  However, from a maintenance point of view, this was certainly not optimal.  I could give a lot of meaningless history here, but eventually I came up with an idea that I dubbed (at that company) the Common Scripting Interface — a class that contained all the aspects that a good javascript object would need, but was not specific to any one browser.

Down with the IDL

Okay, this is where I’m going to start raising a lot of eyebrows.  I respectfully submit that using an IDL, as it is defined by Internet Explorer, is generally a bad idea on a control intended to be used from Javascript.  Why?  Simply put, Javascript is a dynamic language; when you pass parameters around, they are not type constrained.  Most javascript functions don’t care if you give them an integer, a string, a bool, or something else; they just use the parameters they are given.  Of course it’s a bit more complicated than that, but Javascript inherently is dynamic.  Thus, it can be important to have the ability to use a dynamic interface on a plugin that interfaces with it.

I hasten to remind you at this point that making an interface dynamic just for the sake of it being dynamic is a bad idea.  However, there are many use cases where you may have members (particularly properties that expose other javascript objects) that may only be named and become accessible at runtime; it’s too late to add something to the IDL.  I believe this is part of the reason that we have settled on NPRuntime on Gecko-based browsers, and Microsoft created an IDispatchEx interface to better support it on ActiveX.  Thus, we have all the tools we need to create a dynamic interface, and I have loosely patterned it after the NPAPI/NPRuntime interface, which I consider to be a fairly good interface for browser plugins.

What is JSAPI?

If you have looked at all at the FireBreath project that I have been working on for the last several months, you may have looked at or seen reference to the JSAPI class.  JSAPI stands for Javascript API.  JSAPI is intended to be a Javascript compatible object written in C++.  It relies heavily on the FB::variant class, which essentially is a class that you can put any datatype in.  If there is enough interest, I can blog more about that type later, but suffice it to say it’s very similar to boost::any but with data conversion tools built in.  A JSAPI object (an object that extends FB::JSAPI) provides all functionality that a Javascript object should, whether it is used or not.

What does a Javascript object do?

Let’s take a big step backwards now.  Forget anything you know about Browser Plugins or ActiveX Controls.  Forget anything you even know about C++, Java, C#, Logo, or any other language, even, except Javascript, HTML, DHTML, and CSS.  Those are the tools of the browser.  When we design the interface for a Browser Plugin, we shouldn’t be thinking like a C++ developer.  We should be looking at it the way we would if we were writing an object in Javascript; we should provide the interfaces that we would expect to find, and use the tools and syntax that we would expect to find in Javascript.

So, let’s look at what a Javascript object can do:

• Javascript objects can have methods that accept parameters and return a value

  • var coolData = plugin.doSomething(1, 1, 2, 3, 5, "right now");

• Javascript objects can expose properties that a caller can get or set:

  • var oldName = plugin.name;

  • plugin.name = "Some cool name";

• Javascript objects can provide events, to which a caller can attach an event handler in the syntax of their browser:

  • plugin.addEventHandler("click", function() { alert("The user clicked on me! Ouch!"); }, false);

  • plugin.attachEvent("onclick", function() { alert("The user clicked on me! Ouch!"); });

When you write it out like this, it doesn’t seem like much; remember, though, that a property of a javascript object could return any primitive datatype, an array, or even another javascript object, itself containing methods, properties, and events.

The JSAPI Interface

One additional thing to remember about a Javascript Object (now taking into account what we know about C++ as well) is that we don’t control the lifecycle of a javascript object.  What that means is that your plugin may go away before Javascript is done with the object that you gave it.  So, if that object uses any references to your plugin, (And what plugin javascript object wouldn’t? It’s the interface to the page, right?) you need to have a way to deal with not only cleaning up your object even after the plugin goes away, but making sure that the javascript object somehow finds out that the object it depends on is gone and invalidates itself in some way.  One way to do that is by using Shared pointers and Weak pointers, but that’s a topic for another day.

Like the NPObject and IDispatch types that provide its interface with the browser, JSAPI is reference counted, so that it will get destroyed whenever the browser.  Here are the method prototypes from JSAPI.h to satisfy the requirements mentioned above.  You can also look at the full source of JSAPI.h if you want.

Methods

// ...
    virtual bool HasMethod(std::string methodName) = 0;
    virtual variant Invoke(std::string methodName, std::vector<variant>& args) = 0;
// ...

Not much is required; one call to find out if the method exists, one to invoke the method.  Notice that the arguments is passed in a STL vector of type variant; you can pass any datatypes in here, but that will be limited by the Browser-level wrapper that converts the arguments from the browser datatype (VARIANT on IE, NPVariant on firefox) to the JSAPI variant datatype.  I’ll discuss this in more detail in a later post.

Properties

// ...
    virtual bool HasProperty(std::string propertyName) = 0;
    virtual bool HasProperty(int idx) = 0;
 
    virtual variant GetProperty(std::string propertyName) = 0;
    virtual variant GetProperty(int idx) = 0;
    virtual void SetProperty(std::string propertyName, const variant value) = 0;
    virtual void SetProperty(int idx, const variant value) = 0;
// ...

You’ll notice one strange thing right off the bat here; there are two of each method.  One takes a std::string for the first parameter, one takes an int.  Any thoughts on why?

Imagine the following code:

for (var i = 0; i < plugin.files.length; i++) {
    alert(plugin.files[i]);
}

This is a pretty standard piece of javascript code, right?  Array access notation is pretty common in Javascript.  Javascript, however, treats everything as an object of one kind or another. An array to javascript is really just an object with numeric properties.  Similarly, we need to be able to support numeric properties for array style access.  That is why we have extra property methods for a property identified by an “int”.

Events

// ...
    virtual void registerEventMethod(std::string name, BrowserObjectAPI *event);
    virtual void unregisterEventMethod(std::string name, BrowserObjectAPI *event);
    virtual void registerEventInterface(BrowserObjectAPI *event);
    virtual void unregisterEventInterface(BrowserObjectAPI *event);
    virtual BrowserObjectAPI *getDefaultEventMethod(std::string name);
    virtual void setDefaultEventMethod(std::string name, BrowserObjectAPI *event);
 
protected:
    // Used to fire an event to the listeners attached to this JSAPI
    virtual void FireEvent(std::string eventName, std::vector<variant>&);
// ...

Events are by far the most difficult piece of this whole class; we have to make allowances for multiple methods of registering events and multiple browsers’ methods for keeping track of the handlers. The BrowserObjectAPI type that you see used here is also a JSAPI object, but one that wraps a browser object (an NPObject or a IDispatch object, depending on the browser).

There are three different ways an event can be registered (at this point in time):

1. Through a “user-defined” event registering method implemented by our browser scripting object wrapper (this is used by all objects on firefox and all but the root object on IE).
   • The BrowserObjectAPI object will essentially be a method that we can invoke by calling InvokeAsync with empty string (“”) as the method name
2. Through the Connection Point interface on an ActiveX Control (obviously used on the root object in IE)
   • The BrowserObjectAPI object will be an object on which we can invoke a method of the same name as the event it is attached to
3. Through a property of the same name as the event (old-style javascript events, as in “document.onload = ….”
   1. The BrowserObjectAPI object will essentially be a method that we can invoke by calling InvokeAsync with empty string (“”) as the method name

These three types are the reason that we have three different register/unregister methods on the browser for events.  When FireEvent is called by the JSAPI child object (that you write), it iterates through all possible event handlers and invokes them asynchronously.  (Events have to be invoked on the main UI thread of the plugin, so the InvokeAsync call on BrowserObjectAPI automatically makes sure that is where it gets called; hence it’s async).

Next time

We have discussed and looked at the basic needs of the JSAPI object.  Part two will discuss the COMJavascriptObject class and the JSAPI_IDispatch helper class that constitute the interface between ActiveX and our JSAPI interfaces.  Part three will cover the NPJavascriptObject that provides the interface between NPRuntime and JSAPI.  Feel free to read ahead in the source =]

In the mean time, if you like where this is going and want to play with FireBreath and see JSAPI in action for yourself, there are some really easy getting started instructions on the FireBreath project page.

Ever since I started this series of posts on NPAPI and plugins, I have started receiving occasional emails requesting additional help with aspects of NPAPI that are particularly confusing.  With full-time work, FireBreath development, and a 6 month old baby to take care of, I often don’t have as much time as I’d like to give these questions the attention that they deserve.  One that I got today struck me as being a particularly confusing bit for many people, and one that I hope I can answer briefly, so I’m going to give it a shot.  I’m still kinda hoping to get to the point that I can explain smaller bits with shorter posts, which will make it easier for me to post new material more often.

NPObject and NPVariant

In general, there are two datatypes that are used by the browser to pass information.  NPObjects are, for those who haven’t read my previous post on NPAPI, the basic datatype for anything that is scriptable — that is, javascript objects and objects that can talk to javascript.  NPVariant is the datatype that is used to pass parameters and values to and from NPObjects.

As a general rule of thumb: Any time the browser gives you something as a return value, you need to release it using browser API calls.  Any time you return something to the browser as a return value, assume that the browser will release it using browser API calls.

NPObject

struct NPObject {
  NPClass *_class;
  uint32_t referenceCount;
  /*
   * Additional space may be allocated here by types of NPObjects
   */
};

There are three important NPN_ (browser API) functions that you need to understand when using a NPObject:

• NPN_CreateObject – Creates an NPObject and returns a reference to it (see part three of Building a firefox Plugin); sets referenceCount to 1
• NPN_RetainObject – Increments referenceCount
• NPN_ReleaseObject – Decrements referenceCount and destroys the object if referenceCount hits 0

NPObject creation

It is important to understand that NPN_CreateObject will initialize referenceCount to 1 before returning it.  Thus, if you only plan for it to be used once, you do not need to call NPN_RetainObject on the newly created NPObject.  To do so anyway could prevent the object from ever being released (which could be bad).  A question was ask about the npruntime sample in the gecko source code, and why it calls NPN_RetainObject after NPN_CreateObject.  Here is the function in question:

(from mozilla_central/modules/plugin/sdk/samples/npruntime/plugin.cpp):

NPObject *
CPlugin::GetScriptableObject()
{
    if (!m_pScriptableObject) {
        m_pScriptableObject = NPN_CreateObject(m_pNPInstance, GET_NPOBJECT_CLASS(ScriptablePluginObject));
    }
 
    if (m_pScriptableObject) {
        NPN_RetainObject(m_pScriptableObject);
    }
 
    return m_pScriptableObject;
}

It’s easy to see how you could get confused here.  Why should we call Retain on it if the referenceCount has already been set to 1?  Simply put, the initial referenceCount is to account for the fact that we’re storing the NPObject in this->m_pScriptableObject — we’ll need to call NPN_ReleaseObject in the destructor to release it.  Why do we call Retain, then?  Because we’re returning an NPObject to the browser (in this case, it is only called in response to a NPP_GetValue with NPPVpluginScriptableNPObject as the NPPVariable), and the browser will expect it to have been properly initialized and will call NPN_ReleaseObject when it’s done with it.

Remember the rule of thumb mentioned above:  Any time you return a NPObject as a return value to the browser, the browser will release it when it’s done.  This means it has to have been retained first!  If you weren’t going to keep a copy of the NPObject, then you wouldn’t need to call retain again; just create it and return it each time.  This makes it a little trickier to keep state, unless you have another object that gives the NPObject it’s brains, like is used in FireBreath.

(Firebreath’s NPObject code is in NPJavascriptObject.cpp and NPJavascriptObject.h, and the object it wraps extends JSAPI, with the implementation here.  The JSAPI provides a platform independent abstraction for providing a scriptable object; in other words, you implement your methods and properties in JSAPI and it works everywhere.  There is a good example of a JSAPI object in FBTestPluginAPI.h and FBTestPluginAPI.cpp)

NPVariants

typedef struct _NPVariant {
  NPVariantType type;
  union {
    bool boolValue;
    int32_t intValue;
    double_t doubleValue;
    NPString stringValue;
    NPObject *objectValue;
  } value;
} NPVariant;

The next step in dealing with memory management is to understand how NPVariants work, are allocated, and are released.  NPVariants are used as parameters and return values on NPObject methods.  As you can see from the NPVariant structure above, most NPVariant types are primitives, and thus don’t need any special memory management.  The two types you need to worry about are the NPString and the NPObject.

There are three important NPN_ (browser API) functions that relate to NPStrings:

• NPN_MemAlloc – Allocates a chunk of memory controlled by the browser and returns a pointer to it (compare to malloc)
• NPN_MemFree – Frees a chunk of memory controlled by the browser (compare to free)
• NPN_ReleaseVariantValue – Frees the value in a variant; if the VariantType is NPVariantType_String, calls NPN_MemFree; if it’s NPVariantType_Object, calls NPN_ReleaseObject

Many may wonder, like I did, why we would need to call browser APIs to allocate and free memory, when malloc and free are standard on all C compilers.  The reason is that on many platforms (windows included) each DLL or EXE could have its own memory management routines and its own heap.  Thus if you allocate memory in your plugin DLL and then the browser frees it, or vise versa, you have a problem.

Now, remember our rule of thumb: if it’s returned as a return value, it will be released by the caller using the browser APIs.  When you need to return a string, you allocate it using NPN_MemAlloc, as in the following code snippet from FireBreath:

// We have:
// std::string str as the string to store
// NPVariant *dst as the destination NPVariant
char *outStr = (char*)this->MemAlloc(str.size() + 1);
memcpy(outStr, str.c_str(), str.size() + 1);
dst->type = NPVariantType_String;
dst->value.stringValue.utf8characters = outStr;
dst->value.stringValue.utf8length = str.size();

Then when the browser (triggered by javascript) calls NPN_Invoke, and we use that method to store a NPString in the final parameter (NPVariant *result), the browser will be able to release the memory when it’s done with it.  Similarly, if you call NPN_Invoke, you need to call NPN_ReleaseVariantValue on the returned NPVariant when you’re done.  Also, you are responsible for both creating and releasing the NPVariant array that you pass into NPN_Invoke as arguments.  The same holds true for the NPVariant used in NPN_SetProperty.

The only time you are not responsible for freeing memory is when it is passed in such a way that you don’t have control of it when your function closes.  Similarly, if you have data that is still available after the function that created it is gone, you need to release it.

Conclusion

Well, the biggest thing that I can conclude from this is that I’m not yet capable of keeping things short.  My hope is that this may help someone; I’ve found links to my NPAPI blog posts in a lot of surprising places.  If you know another documentation site that should have a link to this post, please link it!  Also, if you know of another site that explains or illustrates things that need to be clarified from these posts, please post them in the comments!  The primary goal of this blog is to help link together and clarify information that is difficult to find for those getting started in new areas.

Thanks to all who read!

Update: See what is happening with FireBreath a year later

It’s been awhile since my last post!  Rest assured, that isn’t because I have lost interest, or because there was nothing to write about; rather, I was occupied with what I considered to be more important things.  If you’re reading this, you likely have already read my previous post, “Call for plugin Developers.”  If you haven’t, you might want to glance over it so that you know what I’m talking about =]

Firebreath has been sponsored by PacketPass, Inc.  I don’t have a web address for them, but I’ll post one later if they want me to do so.  The good news about that is that it means that unlike the vast majority of new open source projects, development of Firebreath is not going to halt before there is at least some sort of a usable project.

Who is working on it?

As you might guess, despite a lot of readers and comments on my last post, relatively few people have joined our mailing list and started helping.  I want to make particular mention of Georg Fritzsche of Germany who has been invaluable to me as a sounding board, as well as come up with some really cool ideas for improving Firebreath even more.  Aside from Georg, there are several others (Don, Jarom, Ben, … ya’ll know who you are) on the mailing list who have been a bit quieter, but nonetheless have been assisting with the brainstorming, planning, and in some small ways development of the project.  This may not sound like a lot, but for a special interest project such as this, I think it’s pretty good.  Of course, we can always use more help =]

Where we’re at:

While I’m not ready to release a “beta” version of Firebreath yet, we are getting really close.  In fact, it’s close enough that anyone feeling a little adventuresome shouldn’t have any trouble setting up a test plugin and testing the limits.  We only support Windows so far (sorry guys, it’s the platform I know best, and it’s the one my client needed first), but we support both Internet Explorer and NPAPI (Firefox, probably Chrome and Safari as well).

A brief list of supported features:

• NPAPI (Firefox, Chrome, Safari) support
• ActiveX/IE support
• Unified scripting API (define your objects for javascript use in one place, they work on all browsers)
• Easy manipulation of the DOM
• Event firing from the plugin into Javascript
• System event handling (mouse events wired, keyboard events can be easily)
• Basic framework for getting the HWND so you can do your drawing (needs to be fleshed out, but usable)
• Easy configuration of all plugin properties (such as Mime type, description, GUIDs, etc)

How to create a plugin with Firebreath

If you want to play with it (and please, please, please play with it and tell us what you think), it’s not too hard to get started.  On the firebreath google code page we have instructions on how to build it, including downloading of the source.  You can find it here: http://code.google.com/p/firebreath/wiki/BuildingFireBreath

Basic steps to build:

• Use Mercurial to download the source
• Use CMake to generate the project for either VS2005 or VS2008 (prep2005.cmd or prep2008.cmd)
• Open the generated solution file (build/Firebreath.sln) in Visual Studio and build it
• Run regsvr32.exe on the generated .dll (build/bin/Debug/)
• open build/projects/PluginTemplate/gen/FBControl.htm and play with it with firebug or jash

Basic steps to create your own Plugin:

• Copy projects/PluginTemplate to projects/YourPlugin
• Update pluginConfig.cmake — REPLACE ALL 6 GUIDs WITH YOUR OWN! — and set the mime type, plugin name, etc
• Rename TemplatePlugin.cpp and .h however you want and update the files so that it is your plugin
• Update factoryMain.cpp to create your plugin instead of TemplatePlugin
• Update your “PluginCore” implementation (TemplatePlugin extends PluginCore) to return the correct API type by editing createJSAPI() and copying MathAPI.h and .cpp to whatever you like.
• Update your JSAPI object (copied from MathAPI.h/.cpp) to have the methods, properties, and optionally events that you want
• Update CMakeLists.txt to make sure it includes any files that you need
• run prep200(?).cmd to regenerate the solution and project files
• build your plugin, run regsvr32.exe on it, and use build/projects/YourPlugin/gen/FBControl.h for testing

How to get more involved

We can use all the help we can get!  The porting effort to linux and mac shouldn’t be astronomical, but currently we have nobody to put on it at least until after 1.0 is out (RC1 planned for end of the year 2009, 1.0 planned for end of January, 2010).  There are a lot of little things that can be done by developers without a lot of plugin experience, as well as some real complex bugs and challenges that will require a bit more experience.

If you are interested in helping, even if just by making suggestions, asking questions, and making comments, please join the development list:

http://groups.google.com/group/firebreath-dev

Update: See what is happening with FireBreath a year later

I hereby issue a “Call for Plugin Developers” to the readers of the site. I know we are as of yet few, but I hope that some of you may be willing to help me.

I am quickly realizing that I need a plugin project from which I can quote source code; one that does the things that I am attempting to explain, and one that is not made up of code that is owned by a specific company or project.

Thus, I introduce to you all: FireBreath.

FireBreath

FireBreath is intended to be a cross platform browser plugin.  Currently, I plant to license this under the new BSD license.  This way, it can be used for commercial projects.  The targetted browsers are:

On windows:

• Microsoft Internet Explorer
• Mozilla Firefox (3 and up; we may add support for 2.x as well)
• Google Chrome
• Opera
• Apple Safari

On mac:

• Mozilla Firefox (see above note on versions)
• Google Chrome (when it is released)
• Apple Safari (3.x and up, intel only for now)

On linux:

• Anything that supports NPAPI plugins and Gecko SDK 1.9 or above (no firefox 2 for now)

What needs to be done

This is an ambitious project; I can help with development, and I can coordinate tasks.  I don’t have time to do it all myself, however, unless a company sponsers me; there is one that has shown interest so far, but nothing is certain.  Even if that happens, and a company wants this project enough to pay me to develop it, it will be far more successful if there are other contributors — you see, I don’t know everything.

In particular, I could really use a “strong right hand” who would be willing to head up the linux-specific part of the development, which despite 10+ years of linux experience is still my weakest point.  If there are others who wish to take ownership of other parts, that would also be great; for now, I will retain the final say on what goes in, because, well, I can.

If you look, you’ll find that there is no code up on the repository as of yet (at least, as of the time of this writing.)  I just started an ActiveX control this evening with the intent to implement FBControl, the ActiveX control portion of FireBreath.  As soon as I have a rough skeleton ActiveX control project done (which will happen sooner if I get a lot of developers wanting to help), I will start on the NPAPI portion of the DLL.  Even before I have that done, there are several small, relatively simple tasks that I could use help with.  In particular, I will not be using any code directly from the mozilla source tree and the plugin samples, so I need someone to write from scratch the NPN_ wrappers for all of the browser functions.

How you can help

For this project to succeed, we need all the help we can get.  If you would like to help, please send me an email at taxilian@gmail.com and introduce yourself.  Tell me:

• Who you are
• What you consider your strengths in this area are
• What interests you most about this project
• How you want to use FireBreath yourself (if at all)
• How much time you may be able to put in

I’ll take nearly anyone right now, though I will be carefully monitoring the code submissions to start out with; my project goals are:

• Reusable and modular
• Cross-platform (both in the browser sense and the operating system sense)
• Cleanly written
• Free and useful

I by no means want to be a dictator on this; I welcome help and suggestions from everyone.

Thanks!

Getting help: For a better place to ask NPAPI-related questions, check out the FireBreath Forums. Yes, there is a forum there for NPAPI plugins that don’t use FireBreath as well.

Previous posts

The purpose of this post is to cover the basics of providing an interface by which javascript can interface with an NPAPI plugin in a cross platform manner.  The primary focus of this post will be on npruntime, which is recommended by the Mozilla development team (or at least seems to be from the meager and confusing documentation available from Mozilla).  More importantly, of course, it is the framework that I recommend, which is all-important, since I’m the one writing this post. =]

Previous posts

If you are new to NPAPI plugins, you may want to go back and read part one and part two of this series, which cover the basic architecture and lifecycle of an NPAPI plugin.

What is npruntime?

I’m so glad you ask.  This confused the daylights out of me when I first got into building browser plugins; there are references to XPCOM and references to LiveConnect and references to NPRuntime, which I never did quite get straightened out until I ran into a Wikipedia article on NPAPI.  I recommend that you read it if you want further background information.

Beyond the simple question of “what is recommended?” is the consideration of practical needs.  For me, the primary considerations that led me to decide that NPRuntimeis the only mechanism that should be used on any new plugin are:

• NPRuntime allows dynamic interfaces — more on this, and why it is useful, later
• NPRuntime is the plugin scripting standard supported by Mac Plugins, Safari (even on windows), Chrome, and Opera.  My goal is always to make things as cross-platform as possible.
• Firefox 3.6 drops support for XPCOM plugins (e.g. xpt file scripting interfaces aren’t recognized)

Getting Started

Throughout this post, I will be referring to Scriptable Objects a lot.  A Scriptable Object is simply an object that can be “scripted”, or accessed and used by javascript.  In firefox, a Scriptable Object is always a NPObject:

struct NPObject {
  NPClass *_class;
  uint32_t referenceCount;
  /*
   * Additional space may be allocated here by types of NPObjects
   */
};

As you can see, a NPObject is nothing more than a reference counted object with a pointer to a NPClass.  As of the latest (as of this writing) Gecko SDK, 1.9, NPClass is defined as follows:

struct NPClass
{
  uint32_t structVersion; // Version of the structure (to determine which features may be missing)
  NPAllocateFunctionPtr allocate; // Called to create a new instance of this object
  NPDeallocateFunctionPtr deallocate; // Called to free the instance of this object
  NPInvalidateFunctionPtr invalidate; // Called on live objects that belong to a plugin instance that is being destroyed. This call is always followed by a call to the <code>deallocate</code> function, or <code>free()</code>. Any attempt to use an invalidated object will result in undefined behavior.
  NPHasMethodFunctionPtr hasMethod; // Called to query if a method exists on the NPObject
  NPInvokeFunctionPtr invoke; // Used to invoke a method on the NPObject
  NPInvokeDefaultFunctionPtr invokeDefault; // Used to invoke the NPObject as a function
  NPHasPropertyFunctionPtr hasProperty; // Called to query if a property exists on the NPObject
  NPGetPropertyFunctionPtr getProperty; // Called to get the value of a property on the NPObject
  NPSetPropertyFunctionPtr setProperty; // Called to set the value of a property on the NPObject
  NPRemovePropertyFunctionPtr removeProperty; // Called to remove/delete a property on the NPObject
  NPEnumerationFunctionPtr enumerate; // Used to get a list of properties and methods that exist on the NPObject (new in FF 3, Gecko SDK 1.9)
  NPConstructFunctionPtr construct; // Used when the new keyword is called in javascript to create a new instance of the NPObject (new in FF 3, Gecko SDK 1.9)
};

Making it Object Oriented

The Gecko SDK is intentionally written to use structs instead of objects; this allows it to work across many platforms, with many different types of compilers, and never worry about binary compatibility.  If you haven’t figured it out yet, the NPClass structure contains a list of function pointers that should be called by the browser (or anyone else) to talk to the NPObject.  These should never be called explicitly, but rather they should be called through the NPN_ functions that I briefly mentioned towards the end of part one.  When one wishes to create a new instance of an NPObject, you call the NPN_CreateObject function and give it the class that should be used.

Fortunately, since all the browser cares about is the NPClass, its function pointers, and the reference count, any class that inherits from NPObject can easily satisfy that requirement; that means that it is not difficult to make a smart NPObject; simply create static methods for each of the pointers in the NPClass struct, dereference the NPObject* that they pass in, and call a member function.

Simple class definition and implementation:

#include "npapi.h"
#include "npupp.h"
 
class MyScriptableNPObject : public NPObject
{
protected:
    // Class member functions that do the real work
    void Deallocate();
    void Invalidate();
    bool HasMethod(NPIdentifier name);
    bool Invoke(NPIdentifier name, const NPVariant *args, uint32_t argCount, NPVariant *result);
    bool InvokeDefault(const NPVariant *args, uint32_t argCount, NPVariant *result);
    bool HasProperty(NPIdentifier name);
    bool GetProperty(NPIdentifier name, NPVariant *result);
    bool SetProperty(NPIdentifier name, const NPVariant *value);
    bool RemoveProperty(NPIdentifier name);
    bool Enumerate(NPIdentifier **identifier, uint32_t *count);
    bool Construct(const NPVariant *args, uint32_t argCount, NPVariant *result);
public:
    // This is the method used to create the NPObject
    // This method should not be called explicitly
    // Instead, use NPN_CreateObject
    static NPObject* Allocate(NPP npp, NPClass *aClass) {
        return (NPObject *)new MyScriptableNPObject(npp);
    }
 
    /////////////////////////////
    // Static NPObject methods //
    /////////////////////////////
    static void _Deallocate(NPObject *npobj);
    static void _Invalidate(NPObject *npobj);
    static bool _HasMethod(NPObject *npobj, NPIdentifier name);
    static bool _Invoke(NPObject *npobj, NPIdentifier name, const NPVariant *args, uint32_t argCount, NPVariant *result);
    static bool _InvokeDefault(NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
    static bool _HasProperty(NPObject * npobj, NPIdentifier name);
    static bool _GetProperty(NPObject *npobj, NPIdentifier name, NPVariant *result);
    static bool _SetProperty(NPObject *npobj, NPIdentifier name, const NPVariant *value);
    static bool _RemoveProperty(NPObject *npobj, NPIdentifier name);
    static bool _Enumerate(NPObject *npobj, NPIdentifier **identifier, uint32_t *count);
    static bool _Construct(NPObject *npobj, const NPVariant *args, uint32_t argCount, NPVariant *result);
 
    static NPClass _npclass;
 
protected:
    NPP m_Instance;
};

Due to code ownership issues, I’m not able to give you the actual code that I’m using, but if there are any compiler errors I’m sure they’ll be simple to straighten out.  The implementation for these static members will be pretty straightforward:

// static
void MyScriptableNPObject::_Invalidate(NPObject *obj) {
    ((MyScriptableNPObject*)obj)->Invalidate();
}
void MyScriptableNPObject::Invalidate() {
    // Invalidate the control however you wish
}
 
// static
void MyScriptableNPObject::_Deallocate(NPObject *obj) {
    ((MyScriptableNPObject*)obj)->Deallocate();
    delete ((MyScriptableNPObject*)obj);
}
void MyScriptableNPObject::Deallocate() {
    // Do any cleanup needed
}

For brevity, I’m not going to include all of the methods here; I will go into more detail on them later.  For now, suffice it to say that after you have implemented the rest of these functions, all that is left is to define the NPClass itself:

NPClass MyScriptableNPObject::_npclass = {
    NP_CLASS_STRUCT_VERSION,
    MyScriptableNPObject::Allocate,
    MyScriptableNPObject::_Deallocate,
    MyScriptableNPObject::_Invalidate,
    MyScriptableNPObject::_HasMethod,
    MyScriptableNPObject::_Invoke,
    MyScriptableNPObject::_InvokeDefault,
    MyScriptableNPObject::_HasProperty,
    MyScriptableNPObject::_GetProperty,
    MyScriptableNPObject::_SetProperty,
    MyScriptableNPObject::_RemoveProperty,
    MyScriptableNPObject::_Enumerate,
    MyScriptableNPObject::_Construct
};

Creating the NPObject

Once you have your custom NPObject created and your NPClass defined, we can cover the basics of the NPObject lifecycle.  Creating an NPObject is pretty straightforward:

NPObject *newObj = NPN_CreateObject(m_Instance, &MyScriptableNPObject::_npclass);
NPN_RetainObject(newObj);

As you can see, all that is needed is the NPP instance handler (see part two) and a pointer to the class.  Since the class is very specific to a specific NPObject, I like to create a static function to instantiate the object, like so:

static MyScriptableNPObject* NewObject(NPP npp) {
    MyScriptableNPObject* newObj = (MyScriptableNPObject*)NPN_CreateObject(npp, &_npclass);
    return newObj;
}

This is completely voluntary, of course, but it also allows you some additional control of the creation process; for example, you may want to pass in additional parameters and have them set on the object as soon as it is created.

NPObject lifecycle

As you might guess, NPN_RetainObject increments the reference count on a given NPObject.  Similarly, NPN_ReleaseObject decrements the reference count.  When the reference count hits zero, the object will be destroyed by calling the specified Deallocate function, just like the Allocate function is called by NPN_CreateObject to create the object.

When code in one DLL allocates something and it is deallocated by a different DLL, heap corruption can (and often does) occur.  For this reason, all things that belong to you will ultimately get created and destroyed in your code.  All things that belong to the browser will get created and freed in browser code.  This way everyone stays happy =]  Make sure you keep track of your Retains and Releases; just like any reference counting, this can cause you a lot of hard to track problems.

Another important thing to keep in mind about the lifecycle of a NPObject is that you don’t know exactly when it will go away; the browser will release it whenever it chooses to do so.  Therefore, you need to be able to handle things gracefully even if things are destroyed in a different order than you expect.

Giving the correct NPObject to the browser

Now that you know what an NPObject is and rougly what it does, you need to know how the browser finds out about it.  If you’ll refer back to part two and look at the plugin lifecycle, you’ll see on entry #5 that “Plugin creates a scriptable NPObject and returns a pointer to it (after calling NPN_RetainObject on it.)”  Simply put, at that point in the initialization sequence (or somewhere in there; the spec is ambiguous about the order), the Browser will call GetValue on the plugin and ask for a NPObject.  If our plugin supports NPObjects, it simply needs to create one, call NPN_RetainObject on it, and return it as a void pointer.  *NOTE: Make sure that you typecast it as a NPObject* before assigning it to the void pointer; I made that mistake once and spent a week trying to figure out why the wrong functions were getting called.

Here is an example implementation of GetValue:

NPError PluginInstance::NpapiGetValue(NPPVariable variable, void *value)
{
   NPError rv = NPERR_NO_ERROR;
   switch(variable)
   {
      case NPPVpluginNameString:
          value = *((char **)value) = STRINGS_PRODUCTNAME;
          break;
      case NPPVpluginDescriptionString:    // Plugin description
          *((char **)value) = STRINGS_FILEDESCRIPTION;
          break;
      case NPPVpluginScriptableNPObject:// Scriptable plugin interface (for accessing from javascript)
          *(NPObject **)value = this->getScriptableObject();
          break;
      case NPPVpluginWindowBool:
          *((PRBool *)value) = this->isWindowed;
          break;
      default:
          rv = NPERR_GENERIC_ERROR;
  }
  return rv;
}
 
NPObject *PluginInstance::getScriptableObject()
{
   NPObject *retval;
   if (this->npobj != NULL)
      retval = (NPObject *)this->npobj;
   else
      retval = (NPObject *)MyScriptableNPObject::NewObject(this->npp);
 
   NPN_RetainObject(retval);
 
   return retval;
}

HasMethod and HasProperty

On to the meat of the article: Say you have a javascript function like so:

var objTag = document.getElementById("myObjectTag");
alert(objTag.doSomeCoolFunction);

You may think that this looks a little strange, since “doSomeCoolFunction” sounds like a function call, but it is clearly accessed like a parameter here.  In Javascript, this is legal even if that is a function, because it can be used to determine if a function exists without calling it.  Therefore, you cannot have a method and a property on the same object with the same name.

When this call is made, the browser will call two functions on the NPObject:

1. HasMethod(NPIdentifier name);
2. HasProperty(NPIdentifier name);

The purpose of these two calls is to ascertain whether or not a property or method exists on the NPObject (as you might have guessed).  So, what is with this NPIdentifier thing?  Well, a NPIdentifier can map to either an integer or a string.  a NPIdentifier can be converted to a string (if it is a string identifier) with NPN_UTF8FromIdentifier.  To find out if it is a string identifier, use NPN_IdentifierIsString.  If it is an integer, you can use NPN_IntFromIdentifier.

Now, the purpose of integer identifiers may not be immediately apparent to everyone; it wasn’t to me at first.  Once I figured it out, however, I was thrilled.  If you are familiar with javascript, you are doubtlessly familiar with the concept that everything in javascript is an object; arrays are actually just objects with integer keys.  So, to allow array-style access, simply handle integer identifiers!

Once you have converted the identifier into something you can deal with, decide if your object has that property or method (I’ll let you figure out which goes in which function) and return true or false.

Oh, and after you get a string wtih NPN_UTF8FromIdentifier, don’t forget to release the memory with NPN_MemFree().

NPVariant

Before I go any further, I need to spend a brief paragraph or two on the NPVariant structure.

typedef struct _NPVariant {
  NPVariantType type;
  union {
    bool boolValue;
    int32_t intValue;
    double_t doubleValue;
    NPString stringValue;
    NPObject *objectValue;
  } value;
} NPVariant;

NPVariant is the datatype used by the browser to pass variables into and out of NPObjects.  From the MDC docs, the following types are valid:

Since it’s getting late and I’ve already put too much in this post (I’m over 2000 words), I’ll leave it as an excercise to the reader to read up on the macros and such for using this structure.

Properties

At this point, you should be getting a pretty good idea of how everything works.  Getting and setting properties is fairly straightforward:

    bool GetProperty(NPIdentifier name, NPVariant *result);
    bool SetProperty(NPIdentifier name, const NPVariant *value);

To get a property, simply check the name to see what you’re going to be doing and store the value to return in *result.  If the operation succeeds, you should return true.  If not, false.

To set a property, again check the name to see which property you’re working with and save the value of the NPVariant parameter however you wish.  Again, return true if success, false if failure.

Methods

Methods aren’t much more difficult.  The only real difference is that now you have parameters to worry about.  No problem!  Parameters are passed in as an array of NPVariants:

    bool Invoke(NPIdentifier name, const NPVariant *args, uint32_t argCount, NPVariant *result);
    bool InvokeDefault(const NPVariant *args, uint32_t argCount, NPVariant *result);

The difference between Invoke and InvokeDefault is that InvokeDefault does not ever have an identifier.  If you call “objTag.funcName()” Invoke gets called; if you call “objTag()”, then InvokeDefault gets called.

As with properties, store the return value in the pointer given in the last argument and handle the other arguments however you wish.

Wrapping it up

Alright, I know I haven’t covered everything, but this is already too long.  If you have specific questions, ask them in the comments and I’ll do my best to answer; the comments may determine the direction of my next post.

Since dealing with the NPIdentifiers can get to be such a pain, I recommend using a map or hashtable to store structures with function pointers to map a string name to functions to handle it; that way you don’t end up with giant if/then or case statements, and everything ends up being much cleaner.

Another idea for the adventuresome: abstract the actual logic (properties and methods) into another object that can be wrapped with your NPObject class, and then make another wrapper class that implements IDispatch so that your scriptable objects are cross platform (IDispatch objects are scriptable on Internet Explorer).

Good luck!

Building a firefox plugin – part one

Building a firefox plugin – part two

Building a firefox plugin – part three

Building a firefox plugin – part four

Getting more help

Update May 14, 2011: Many people have been asking questions in the comments; while I don’t mind that, it would probably be more useful if you ask your question on the FireBreath forums. There is a forum there for those just using NPAPI as well!

Getting help: For a better place to ask NPAPI-related questions, check out the FireBreath Forums. Yes, there is a forum there for NPAPI plugins that don’t use FireBreath as well.

Recap

Last time, I talked about the fundamentals of implementing a NPAPI plugin.  Today, I’m going to go into a little more detail on how to use the strange callback architecture that firefox exposes.

The NPAPI uses a rather unique (in my experience) methodology for providing an interface between the plugin and browser, but it does have some rather significant advantages.  Instead of providing binaries to be linked against, the browser simply expects you to implement the entry point NP_Initialize in your dll that the browser will call and tell you where the methods that you will be using are located.  In order for the browser to interface with you, it calls NP_GetEntryPoints with a pointer to a structure for your plugin to fill out with function pointers that the browser will be calling on your plugin.

This removes the need for a large number of include and library files in your project.  In fact, in practice I found that I only actually needed 12 include files from the Gecko SDK:

• jni.h
• jni_md.h
• jri.h
• jritypes.h
• jri_md.h
• npapi.h
• npruntime.h
• nptypes.h
• npupp.h
• obsolete/protypes.h
• prcpucfg.h
• prtypes.h

Edit (Sep 16, 2010): Now over a year later there is a better way to do this.  There is a Google Code project called npapi-headers that has just the header files you need — and they actually work on all browsers, all platforms (unlike the ones from the gecko SDK sometimes).

Basic Lifecycle of a plugin:

Jean-Lou Dupont has an excelent visual diagram of this on his blog, which you can find here: http://jldupont.blogspot.com/2009/11/notes-on-npapi-based-plugins.html

The lifecycle of a plugin is actually pretty simple, once you figure it out.  The initial entrypoints NP_Initialize and NP_GetEntryPoints could, according to the documentation, get called in any order; however, in practice, NP_GetEntryPoints seems to get called first on Windows.  With that in mind, here is the order of calls for basic windowed plugin initialization on Windows:

1. NP_GetEntryPoints – Plugin fills out a function table with the addresses of NPP_New, NPP_Destroy, NPP_SetWindow, etc
2. NP_Initialize – Plugin stores a copy of a function table with the addresses of NPN_CreateObject, NPN_MemAlloc, etc
3. NPP_New – Plugin creates a new instance of itself and initializes it
4. *NPP_SetWindow – This is called multiple times for each instance — each time the instance’s window is created, resized, or otherwise changed
5. NPP_GetValue (Variable = NPPVpluginScriptableNPObject) – Plugin creates a scriptable NPObject and returns a pointer to it (after calling NPN_RetainObject on it)
6. — Standard Plugin Activity —
7. NPP_Destroy – Plugin instance is destroyed
8. NP_Shutdown – All remaining plugin resources are destroyed

It is worth our time to investigate a few of these calls in more detail.

NPError NPP_New(NPMIMEType pluginType, NPP npp, uint16 mode, int16 argc, char* argn[], char* argv[], NPSavedData* saved)

/*
 *  NPP is a plug-in's opaque instance handle
 */
typedef struct _NPP
{
  void*pdata;      /* plug-in private data */
  void*ndata;      /* netscape private data */
} NPP_t;
 
typedef NPP_t*  NPP;

This structure is normally seen as NPP and serves as the handle of a plugin instance. As you can see, there is private data for the plugin and private data for the browser.  When NPP_New is called, you should:

1. Create some sort of data structure to uniquely identify this instance of the plugin
2. Assign a pointer to that data structure to npp->pdata

What I like to do is to create a PluginInstance class and use that as my “pdata”.  Then my NPP_New function looks like this:

// Called by the browser to create a new instance of the plugin
 
NPError NPP_New(NPMIMEType pluginType,
            NPP npp,
            uint16 mode,
            int16 argc,
            char* argn[],
            char* argv[],
            NPSavedData* saved)
{
    if (npp == NULL)
        return NPERR_INVALID_INSTANCE_ERROR;
 
    NPError rv = NPERR_NO_ERROR;
    PluginInstance* pPluginObj = new PluginInstance(npp);
 
    if (pPluginObj == NULL)
        return NPERR_OUT_OF_MEMORY_ERROR;
 
    npp->pdata = pPluginObj;
    return pPluginObj->NpapiNew(pluginType, mode, argc, argn, argv, saved);
}

In this way I can have a PluginInstance class that handles the entire lifecycle of a given instance of a plugin, and I simply create stub static functions to dereference the pdata pointer and call the correct function.

NPP_SetWindow (NPP npp, NPWindow* pNPWindow)

For many, this will be where the real fun starts — this function is called to tell the plugin which window they are in.  From the Gecko SDK (npapi.h):

typedef struct _NPWindow
{
  void* window;  /* Platform specific window handle */
                 /* OS/2: x - Position of bottom left corner  */
                 /* OS/2: y - relative to visible netscape window */
  int32 x;       /* Position of top left corner relative */
  int32 y;       /* to a netscape page.					*/
  uint32 width;  /* Maximum window size */
  uint32 height;
  NPRect clipRect; /* Clipping rectangle in port coordinates */
                   /* Used by MAC only.			  */
  void * ws_info; /* Platform-dependent additonal data, linux specific */
  NPWindowType type; /* Is this a window or a drawable? */
} NPWindow;

A pointer to this structure is passed in with each call.  On windows, the “void* window” will dereference to an HWND. On other platforms, it will likewise be dereferenced as an appropriate type.

Notice that again NPP npp is the first parameter.  This will be the case on all NPP functions except NPP_New, where the mimetype is also passed in.  Since we created a PluginInstance object and assigned it to npp->pdata in NPP_New, we need to create a small stub function to forward our NPP_New to a method on that object, like so:

// Called by browser whenever the window is changed, including to set up or destroy
NPErrorNPP_SetWindow (NPP npp, NPWindow* pNPWindow)
{
    if (npp == NULL)
        return NPERR_INVALID_INSTANCE_ERROR;
    else if (npp->pdata == NULL)
        return NPERR_GENERIC_ERROR;
 
    PluginInstance *inst = (PluginInstance *)npp->pdata;
    return inst->NpapiSetWindow(pNPWindow);
}

On windows, when SetWindow is called we need to save the HWND and subclass the window so that we can get our own window event proc.

NPError PluginInstance::NpapiSetWindow (NPWindow* pNPWindow)
{
    NPError rv = NPERR_NO_ERROR;
 
    if(pNPWindow == NULL)
        return NPERR_GENERIC_ERROR;
 
    // window just created; in initWindow, set initialized to true
    if(!this->initialized) {
        if(!this->initWindow(pNPWindow)) {
            return NPERR_MODULE_LOAD_FAILED_ERROR;
        }
    }
 
    // Window was already created; just pass on the updates
    this->updateWindow(pNPWindow);
 
    return rv;
}

With these functions, we get notified in one function when the window is first set, and another is called each time an update is made.

NPP_Destroy (NPP npp, NPSavedData** save)

When the Browser is ready to shut down a given plugin instance (the user leaves the page or the object tag is removed from the DOM), the browser calls NPP_Destroy.  This call is responsible to free any memory being used by that plugin instance.

// Called by browser to destroy an instance of the plugin
NPError NPP_Destroy (NPP npp, NPSavedData** save)
{
    if (npp == NULL)
        return NPERR_INVALID_INSTANCE_ERROR;
    else if (npp->pdata == NULL)
        return NPERR_GENERIC_ERROR;
 
    PluginInstance *inst = (PluginInstance *)npp->pdata;
    NPError rv = inst->NpapiDestroy(save);
 
    delete getPluginObject(npp);
    npp->pdata = NULL;
 
    return rv;
}

Next Time

That’s all the time I have today.  Next time I will discuss NPObjects and how they are used to provide an interface by which Javascript can interact with your plugin.

Building a firefox plugin – part one

Building a firefox plugin – part two

Building a firefox plugin – part three

Building a firefox plugin – part four

Getting more help

Update May 14, 2011: Many people have been asking questions in the comments; while I don’t mind that, it would probably be more useful if you ask your question on the FireBreath forums. There is a forum there for those just using NPAPI as well!

Getting help: For a better place to ask NPAPI-related questions, check out the FireBreath Forums. Yes, there is a forum there for NPAPI plugins that don’t use FireBreath as well.

Introduction

I have now been researching and working on a cross-platform browser plugin for several months.  By far my greatest frustration throughout this process has been the significant lack of documentation on the subject.  So, with the creation of this site, I wish to create a small series that will hopefully provide assistance to other poor developers who are trying to break into this strangely secretive field =]

I’m not going to be able to cover everything in one post (for time reasons if nothing else).  How fast I get the rest of the posts done may depend in large part on whether or not anyone seems to be reading them and what requests are made in the comments =]

Plugin architecture

In these articles I plan to focus on the basic requirements for creating an NPAPI (Netscape Plugin) style plugin, which is used by most (if not all) plugin-supporting open browsers, including: Apple Internet Plugins on Mac (Firefox, Safari, probably others); Firefox (and all other gecko-based browsers), Opera, Safari, and Chrome on windows, and at least firefox on linux.  I haven’t yet implemented a plugin on linux, but most of the same principles should apply.

Because of the minor differences between platforms, I will first cover the architecture as it is used in Windows, and then in a later post I will cover the differences between windows and other platforms, such as Mac and Linux.

Plugin API vs Scripting API

When I first began developing browser plugins, I failed to understand the difference between the scripting API and the plugin API.  They are closely related, of course, but they serve different purposes.

The Scripting API is used to provide methods callable from javascript, while the Browser API provides the interface for hosting the plugin itself in the browser.

NPAPI

You can find the Mozilla documentation for plugins here:

https://developer.mozilla.org/en/Gecko_Plugin_API_Reference

For history of the NPAPI (Netscape Plugin API), see the Wikipedia page: http://en.wikipedia.org/wiki/NPAPI

What makes up an NPAPI browser plugin?

A NPAPI browser plugin is, at it’s core, simply a DLL with a few specific entry points.  Each of these entry points is only called once by the browser for all instances of your plugin on a given page.  They are listed here in the order they should be called:

• NP_GetEntryPoints – Called immediately after the plugin is loaded and is used by the browser (no longer just netscape) to get pointers to all of the API functions that the browser might need to call.
• NP_Initialize – Provides global initialization of your plugin.
• NP_Shutdown – Provides global deinitialization of your plug-in.

It is important to note that since these entrypoints are specific to NPAPI, there is no reason you can’t have a NPAPI plugin inside a DLL that also provides other services (like, for example, an ActiveX plugin).

Since these three entrypoints provide the core of the NPAPI architecture, it is worth our time to look at them a little more closely.

NP_GetEntryPoints

NPError WINAPI NP_GetEntryPoints(NPPluginFuncs* pFuncs)

This is undoubtedly the most important of the three to understand.  Because of this, it shocks me that the only actual useful documentation I have found for this method so far is found in an old, but still mostly accurate web-book written who-knows-when by Zan Oliphant.

While not as straightforward as the other two entrypoint functions, NP_GetEntryPoints is nonetheless relatively straightforward.  As you can see from the above function prototype, NP_GetEntryPoints takes a pointer to the NPPluginFuncs structure:

typedef struct _NPPluginFuncs {
    uint16 size;
    uint16 version;
    NPP_NewUPP newp;
    NPP_DestroyUPP destroy;
    NPP_SetWindowUPP setwindow;
    NPP_NewStreamUPP newstream;
    NPP_DestroyStreamUPP destroystream;
    NPP_StreamAsFileUPP asfile;
    NPP_WriteReadyUPP writeready;
    NPP_WriteUPP write;
    NPP_PrintUPP print;
    NPP_HandleEventUPP event;
    NPP_URLNotifyUPP urlnotify;
    JRIGlobalRef javaClass;
    NPP_GetValueUPP getvalue;
    NPP_SetValueUPP setvalue;
} NPPluginFuncs;

UPP in each of these type names stands for “Universal Proc Pointer”, which is essentially just a function pointer that the Gecko SDK uses in conjunction with a CallUniversalProc macro for all of its function pointer needs.  For more information, grep the Gecko SDK.

These function pointers basically tell the browser how to interact with your plugin.  Notice the naming convention here: NPP_* for all plugin functions.  There are also NPN_* functions that we will see later, and these are functions that the plugin can call on the browser.  They will be given to us in the NP_Initialize call.

So, the primary purpose of the NP_GetEntryPoints function is to give the browser pointers to all of the functions that it needs to call when creating or interacting with your plugin.

Here is a quick overview of the NPP plugin functions that your plugin must provide (and give addresses to when NP_GetEntryPoints is called).  This table is copied from Zan Oliphant’s book and updated to reflect the current practices and Gecko SDK 1.8:

We will talk more about the specifics of how each of these functions works later.

NP_Initialize

NPError WINAPI NP_Initialize(NPNetscapeFuncs *aNPNFuncs) // Windows
// -or-
NPError NP_Initialize(NPNetscapeFuncs *aNPNFuncs, NPPluginFuncs *aNPPFuncs) // Linux

As noted in the documentation, NP_Initialize provides global initialization for a plug-in.  The API reference is a little confusing in that it claims that NP_Initialize is actually the first function called by the browser.  The reason for this is that on linux, there aparently is no NP_GetEntryPoints call; instead, the NPPluginFuncs struct is passed into the NP_Initialize function to be filled out.

Since this isn’t confusing enough, on Mac they have replaced both of these functions with a single “main” function that not only gets passed both function pointer structures (one with the browser functions and one to be filled out with plugin functions) but also is given a shutdown function pointer to be filled out with the address to the NP_Shutdown function.

Because of these discrepancies, I recommend that you write a separate function for filling out the NPPluginFuncs structure so that it can be called from any of the various init functions.

The NPNetscapeFuncs structure that is passed in is the complement to the NPPluginFuncs structure that we have discussed previously.  As might be guessed from the name, the NPNetscapeFuncs structure contains pointers to browser functions that can be called by the plugin.  There are a lot more of these, and we will discuss more about how to use them next time.

For now, take a look at the structure to get a general idea of what is there.  I’ve added comments on some of the more common function calls.

typedef struct _NPNetscapeFuncs {
    uint16 size;
    uint16 version; // Newer versions may have additional fields added to the end
    NPN_GetURLUPP geturl; // Make a GET request for a URL either to the window or another stream
    NPN_PostURLUPP posturl; // Make a POST request for a URL either to the window or another stream
    NPN_RequestReadUPP requestread;
    NPN_NewStreamUPP newstream;
    NPN_WriteUPP write;
    NPN_DestroyStreamUPP destroystream;
    NPN_StatusUPP status;
    NPN_UserAgentUPP uagent;
    NPN_MemAllocUPP memalloc; // Allocates memory from the browser's memory space
    NPN_MemFreeUPP memfree; // Frees memory from the browser's memory space
    NPN_MemFlushUPP memflush;
    NPN_ReloadPluginsUPP reloadplugins;
    NPN_GetJavaEnvUPP getJavaEnv;
    NPN_GetJavaPeerUPP getJavaPeer;
    NPN_GetURLNotifyUPP geturlnotify; // Async call to get a URL
    NPN_PostURLNotifyUPP posturlnotify; // Async call to post a URL
    NPN_GetValueUPP getvalue; // Get information from the browser
    NPN_SetValueUPP setvalue; // Set information about the plugin that the browser controls
    NPN_InvalidateRectUPP invalidaterect;
    NPN_InvalidateRegionUPP invalidateregion;
    NPN_ForceRedrawUPP forceredraw;
    NPN_GetStringIdentifierUPP getstringidentifier; // Get a NPIdentifier for a given string
    NPN_GetStringIdentifiersUPP getstringidentifiers;
    NPN_GetIntIdentifierUPP getintidentifier;
    NPN_IdentifierIsStringUPP identifierisstring;
    NPN_UTF8FromIdentifierUPP utf8fromidentifier; // Get a string from a NPIdentifier
    NPN_IntFromIdentifierUPP intfromidentifier;
    NPN_CreateObjectUPP createobject; // Create an instance of a NPObject
    NPN_RetainObjectUPP retainobject; // Increment the reference count of a NPObject
    NPN_ReleaseObjectUPP releaseobject; // Decrement the reference count of a NPObject
    NPN_InvokeUPP invoke; // Invoke a method on a NPObject
    NPN_InvokeDefaultUPP invokeDefault; // Invoke the default method on a NPObject
    NPN_EvaluateUPP evaluate; // Evaluate javascript in the scope of a NPObject
    NPN_GetPropertyUPP getproperty; // Get a property on a NPObject
    NPN_SetPropertyUPP setproperty; // Set a property on a NPObject
    NPN_RemovePropertyUPP removeproperty; // Remove a property from a NPObject
    NPN_HasPropertyUPP hasproperty; // Returns true if the given NPObject has the given property
    NPN_HasMethodUPP hasmethod; // Returns true if the given NPObject has the given Method
    NPN_ReleaseVariantValueUPP releasevariantvalue; // Release a MNVariant (free memory)
    NPN_SetExceptionUPP setexception;
    NPN_PushPopupsEnabledStateUPP pushpopupsenabledstate;
    NPN_PopPopupsEnabledStateUPP poppopupsenabledstate;
} NPNetscapeFuncs;

In addition to saving the function pointers given so that browser calls can be made, any memory that is to be shared by all instances of your browser plugin should be initialized here.

NP_Shutdown

This is the simplest of the three entrypoints.  Free any shared memory and release any shared resources.  This is called when the browser has already destroyed all instances of your plugin (by calling NPP_Destroy) and does not expect to create any more in the near future.

Next Time

Next time we will go into greater detail on implementing the NPP functions and also cover some of the most commonly used NPN functions.

Building a firefox plugin – part one

Building a firefox plugin – part two

Building a firefox plugin – part three

Building a firefox plugin – part four

Getting more help

Update May 14, 2011: Many people have been asking questions in the comments; while I don’t mind that, it would probably be more useful if you ask your question on the FireBreath forums. There is a forum there for those just using NPAPI as well!