Netscape Plug-in API

  Netscape allows programmers to enhance the Navigator functionality by creating dynamically loadable libraries, called plug-ins. When the Navigator starts up, it queries available plug-ins for MIME-types [51] they can handle. Whenever a document with any of those MIME-types is opened in the browser, the appropriate plug-in is loaded. Navigator passes the document to the plug-in either as a stream while loading, or as a file after loading. Whichever method is used, is controlled by the plug-in. Netscape encourages plug-in developers to use the streamed transfer mode whenever possible. Downloading to a local file before viewing, may take some time for larger documents.

Netscape defines a Plug-in Application Programmer's Interface (API) [69] giving guidelines for plug-in developers. When calling a plug-in, Navigator expects certain functions to be defined, called ``plug-in methods''. Also, Navigator provides a set of functions for the plug-in to call, termed ``Netscape methods''. Functions defined by the plug-in have names starting with NPP, while function names provided by Navigator start with NPN.

What follows is a short description of the most important of the above mentioned functions. Let's start with the plug-in methods. The order of the functions resembles the calling order.

The following functions are used when the plug-in is initiated.

NPP_Initialize

is called when the plug-in is loaded, before any streams are handed to it. The function is supposed to do general plug-in initialization.

NPP_GetMIMEDescription

is used by Navigator to query the MIME-types this plug-in supports.

For each new instance of the plug-in, Navigator calls the following functions:

NPP_New

Called when a new instance of the plug-in is wanted. This is typically when the user enters a page containing data this plug-in gives support for. Among the parameters to this function, is a pointer to an instance specific structure. The plug-in should allocate and initialize a piece of memory to hold any instance data required, and enter a pointer to this memory into the instance data structure. The instance data structure is passed in every call to functions handling an instance.

NPP_SetWindow

is used to give the plug-in a sub-window of the browser, or to indicate that the window size has changed. The first time this function is called, the plug-in normally sets up the layout of its window.

There are several functions used for stream handling:

NPP_NewStream

indicates that a new stream is available. By returning certain values, the plug-in may request that data is passed either as a file, or in a streamed manner.

NPP_StreamAsFile

passes a filename to the plug-in. This function is called when the plug-in has requested the data as a file. The plug-in may open and process the file as it wishes.

 NPP_WriteReady

is used when data is transferred as a stream. Netscape Navigator calls NPP_WriteReady whenever it has something to send to the plug-in, to query the number of bytes it is able to handle. The number returned indicates a promise rather than a limit; Navigator may send more (or less) bytes than accepted by the plug-in, but the plug-in doesn't have to read more than returned by the last call to NPP_WriteReady. The actual data transfer is done in NPP_Write, which is called afterwards.

NPP_Write

lets Navigator transfer a block of bytes from the stream to the plug-in. The plug-in is supposed to accept at least as many bytes as it promised in the last call to NPP_WriteReady.

NPP_DestroyStream

is called to indicate that there are no more data available in the stream. Among the possible reasons passed as a parameter, are: End of stream reached, user break and network error. Note that the destruction of the stream does not imply destruction of the instance. The instance is still supposed to be around to repaint the window.

Finally, functions are called to tidy up when an instance, or the entire plug-in is no longer needed.

NPP_Destroy

is called when an instance is no longer needed. This is typically when the user leaves a page containing the window handled by this instance of the plug-in.

NPP_Shutdown

is the opposite of NPP_Initialize. It is called just before the plug-in is unloaded.

Most functions provided by Navigator is of no interest to the MPEG plug-in, so only a few are mentioned:

NPN_MemAlloc

may be used by plug-ins to allocate memory from Navigator's memory space.

NPN_MemFree

frees memory returned by NPN_MemAlloc.

NPN_GetURL

requests that Navigator opens a new URL. The resulting stream may be handled by Navigator itself, or by the plug-in, depending on parameters passed.

NPN_Status

enables displaying messages on Navigator's status line.