Netscape DevEdge

Skip to: [content] [navigation]




About This Guide

The Netscape GeckoTM Plug-in API Reference describes the application programming interfaces (APIs) for Netscape Gecko plug-ins and provides information about how to use these interfaces to create plug-ins for Netscape Gecko-based browsers such as Netscape 6.x, Netscape 7.0, and Mozilla.

The general introduction in "Plug-in Basics" and a chapter entitled "Plug-in Development Overview" begin the guide. A series of chapters on specific programming topics such as "Initialization and Destruction", "Streams", and "URLs" provide more detail about the technical aspects and techniques for creating and managing plug-ins.

The API reference in the second half of the guide is divided up into two main halves, "Plug-in Side Plug-in API" and "Browser Side Plug-in API", as well as additional reference material about "Structures" and "Constants".

The guide is structured so the developers new to Netscape Gecko plug-ins can familiarize themselves with the APIs and particular aspects of the development process (e.g., "Drawing and Event Handling"), but so that plug-in developers can quickly access the API reference material they need.

Who Should Read This Guide

The Netscape Gecko Plug-in API Reference is meant for plug-in developers. Though it provides a basic overview of plug-ins and how they work in the browser, the guide presumes that you understand how plug-ins work, how they handle and display media, and what the basic architecture of a browser is that supports the use of plug-in software.

The guide also presumes that you know how to use application programming interfaces, have experience developing browser software such as plug-ins, components, or add-ons, and are familiar with C/C++, the language(s) in which the libraries were actually created and in which all of the examples are given.

The Plug-in Software Development Kit

A Plug-in software development kit (SDK) is available for Netscape Gecko plug-in developers. This SDK is located in the Mozilla source under mozilla/modules/plugin/tools/sdk. You can use it within the Mozilla source tree, or you can build it there and then use it outside of tree if you'd rather. In either case, the Mozilla source tree is required to get started developing plug-ins. You can also view the plug-in SDK samples and source code using the web-based source viewer:

The SDK is based on the API developed originally for Netscape browsers starting with Netscape 2.x. Some additions were made when Netscape 3.x and Netscape 4.x were released. The present SDK reflects major changes related to Mozilla code base: LiveConnect for plugin scriptability is no longer supported, existing plugins should be modified slightly to become scriptable again; the browser services are now accessible from the plug-in through the access to the service manager.

The SDK is intended to help in creating full-blown plugins to work with the Mozilla code base without actually having the whole Mozilla source tree present and built.

The Common folder contains stub implementations of the NPAPI methods. There is no need to modify files in this folder, just include them into your project. This is not necessary though, some samples or plugin projects may use their own implementations, the files in this folder are just an illustration of one possible way to do that.

The Samples section at this point contains the following plug-in samples:

Basic plug-in

Shows the bare bones of the plugin DLL. It does not do anything more than a 'Hello, World' for plug-ins. The basic plug-in demonstrates how the plugin DLL is invoked and how NPAPI methods are called. It can be used as a starting template for writing your own plug-in.

Simple plug-in

This plugin example illustrates specific for Mozilla code base features. It is scriptable via JavaScript and uses services provided by the browser.

XPCOM interfaces are implemented in the simple plug-in so the Mozilla browser is aware of its capabilities. The plugin does not draw in the native window but rather uses JavaScript box to display the result of its work. Therefore, there are no separate projects for different platforms in this sample.

Scriptable plug-in

Yet another example of plug-in scriptability. The scriptable plug-in implements two native methods callable from the JavaScript, and it draws in a native window, so it uses different projects for the different major platforms.

Windowless plug-in

The windowless plug-in is an example of a plugin which does not use native window messaging mechanism and relies exclusively on NPP_HandleEvent to receive GUI messages for painting and other tasks. This plug-in simply draws a gray rectangle in the occupied area.

Scriptable plug-in samples require that you generate cross-platform type library (XPT) files and place them in the Mozilla Plugins directory along with the plug-in DLLs. (For backwards compatibility with pre-Mozilla 1.0 and Netscape 6.x browsers, you must put the type library file in the Components directory instead. For more information on type libraries and plug-in path information, see Plug-in Detection in the "Plug-in Basics" chapter.)

To verify that Mozilla is aware of new .xpt files, you can look in the generated file, xpti.dat, where type libraries are listed. If you need to, you can call netscape.plugins.refresh() to to find new XPT files and plug-in software.

Plug-in developers might find it useful for debugging purporses to turn off the exception catching mechanism currently implemented in Mozilla on Windows. To turn off Windows exception handling, add the following line into your prefs.js file:

user_pref("plugin.dont_try_safe_calls", true);

Netscape Communications