Netscape Plug-Ins

The plug-in API consists of two sets of functions. The first set, where the names begin with “NPP_”, are functions that the plug-in must implement. These functions will be called by the browser as it downloads the file. The second set, with names beginning with “NPN_”, are services which the plug-in may ask the browser to provide, such as allocating and freeing memory, reading and writing URLs, providing version information and writing messages to the browser status field.

There are more than a dozen “NPP_” functions. The thought of implementing such a large set of complex functions may seem scary. To demystify the API, these functions can be broken down into a few general categories. There are functions that allow the plug-in to describe its capabilities (NPP_GetMIMEDescription, NPP_GetValue), initialize and finalize data structures (NPP_Initialize, NPP_Shutdown, NPP_New, NPP_Destroy), write into a graphics area (NPP_SetWindow) and receive data (NPP_NewStream, NPP_Write, NPP_WriteReady, NPP_StreamAsFile, NPP_DestroyStream). There are also functions that allow the plug-in to enable LiveConnect (NPP_GetJavaClass) and to describe its graphics area to a printer (NPP_Print).

UNIX plug-ins must implement NPP_GetMIMEDescription. This function returns a semicolonseparated-list of MIME descriptions. Each MIME description includes the MIME type, the file extensions associated with that MIME type, and a brief description of the MIME type. NPP_GetValue returns the name of the plug-in, as well as a detailed description of the plug-in.

NPP_Initialize and NPP_Shutdown are called just after the plug-in is loaded and just before the plug-in is unloaded, respectively. These functions give the plug-in the opportunity to allocate and initialize global data structures, then free any allocated resources when they are no longer needed.

NPP_New and NPP_Destroy are called to create or destroy a particular instance of the plug-in player. More than one embedded file may have the same MIME type on a single HTML page. The plug-in may need to maintain separate data structures for each instance. When a plug-in instance is created, the browser provides environment information, such as whether the plug-in is embedded or full page, and whether there are any special directives within the HTML <EMBED> tag. However, the browser will not provide a graphics area or the file contents to the plug-in instance until after the instance has been successfully created.

NPP_SetWindow provides the plug-in with a graphics area to draw in. UNIX plug-ins are provided with a Motif Drawing Area widget. The plug-in may draw directly into the graphics area using X Window System functions, or it may create new widgets, using the Drawing Area widget as the parent. Note that because of the two-phase widget deletion scheme of X, the plug-in must not be linked with any widget library. Otherwise, X may try to execute the second deletion phase after the plug-in (and the widget library) has been unloaded, resulting in a core dump. The plug-in must use only widget classes already linked into the browser. For Netscape, this means Motif widgets.

The browser uses the functions NPP_NewStream, NPP_Write, NPP_WriteReady, NPP_StreamAsFile, and NPP_DestroyStream to negotiate with the plug-in about data transfer mechanisms. The plug-in can elect to receive the data piecemeal, or the plug-in may ask the browser to collect all the data into a file before delivering it. If the data arrives piecemeal, the plug-in can set upper limits on size and rate for data transfer from the browser.

The function NPP_GetJavaClass allows the plug-in to enable LiveConnect. LiveConnect is a technique for plug-ins to interface with Java and JavaScript. LiveConnect allows JavaScript to control the execution of a plug-in. LiveConnect requires a special Java class to be loaded and executed. For many plug-ins, this may be unnecessary overhead.

The function NPP_Print allows the plug-in to describe itself, in a platform-specific manner, to a printer. For UNIX, this means writing PostScript to a file. Full-page plug-in instances are given a choice of whether they would like to handle all aspects of printing or whether the browser should handle most aspects. Embedded plug-in instances have no choice. The browser will query the user about print destination, page size and orientation, etc. The browser will then open a file and begin writing its own PostScript. When the plug-in instance is encountered, the function NPP_Print is called. The browser passes in parameters reminding the plug-in instance of its location on the page and providing the plug-in instance with a FILE pointer to add its PostScript. When NPP_Print returns, the browser continues to add PostScript to the file, then closes the file and sends it to the print destination.

If the plug-in does not add any PostScript, there will be a blank area in the plug-in's location on the printed page. Plug-ins that display still graphics should probably implement this NPP_Print. Plug-ins that display animation or which play sound may choose not to implement NPP_Print. This function will be called in response to a user selecting either the “File/Print” or the “File/Save As” menu option, then selecting PostScript as the output format. Needless to say, this is not a trivial function to implement properly. Even the PDF plug-in from Adobe contains a flaw which causes a core dump when using the “File/Save As” menu option. It may be better to omit this feature, rather than implement it poorly.