Last updated 11/15/95
The Netscape Client Plug-in API allows third parties to extend the Netscape client with native support for new data types and additional features. Plug-ins appear as additional capabilities of the Netscape client, indistinguishable to the user from the baseline features.
Plug-ins are dynamic code modules, native to a specific platform on which the Netscape client runs. Plug-ins are intended to be complementary to platform-native inter-application architectures such as OLE 2 and platform-independent programming languages such as Java. The primary goals of the plug-in API are to:
The current version of the plug-in API supports four broad areas of functionality. Plug-ins can:
Plug-ins can have one of three modes of operation: embedded, full-screen, or hidden.
An embedded plug-in is a part of a larger HTML document, where the plug-in is visible as a rectangular subpart of an HTML page. This is similar to an embedded GIF or JPEG image today, except that the image can be live and may respond to user events such as mouse motion. An example of such a plug-in might be an MPEG player. Embedded plug-ins are specified in HTML with the EMBED
tag (see an example of EMBED
tag syntax).
A full-screen plug-in would be the viewer for a particular data type that was not a part of an HTML document. In this mode a plug-in will completely fill the inner frame of a Netscape window with its representation of some data type. An example of this kind of plug-in is an Adobe Acrobat viewer.
A hidden plug-in is one that runs in the background. An example of this might be a MIDI player.
The Netscape user interface is intended to remain relatively constant regardless of which plug-ins are in use. The part of the application frame that is not displaying plug-in data should remain familiar to a Netscape user. In particular, the basic operations of the client, such as navigation, history, opening files and the like, are intended to apply to all pages, regardless of which plug-ins are required to view them.
One of the fundamental things that a plug-in can do is fetch a URL with all the network functionality of the standard Netscape client. The data from such a URL is provided as a stream as it arrives from the network. This allows a plug-in to implement a progressive viewer or to make a particular decision without seeing an entire stream. Individual plug-ins can request multiple simultaneous streams, to the extent that this is supported by the host client. The Netscape client caches plug-in data in its existing persistent cache mechanism.
Plug-ins are also provided a random access model of network data, via the proposed byte range extension to HTTP.
Plug-ins can themselves generate data that Netscape or other plug-ins will display. So they can be both producers and consumers of data. In this way plug-ins can be data translators or filters.
Plug-ins are dynamic code modules. They are associated with a MIME data type that the Netscape client has no native support for. When Netscape encounters an unknown data type from a server it will look for a plug-in that is associated with that MIME type and load it. Plug-ins consume no resources (other than disk space) when they have not been referenced. When the Netscape client starts, it enumerates the available plug-ins in a platform-specific manner and registers them according to their MIME type. A single plug-in may register for multiple MIME types.
The plug-in API is structured as two co-operating objects. One object represents an instance of the plug-in application and its current state. Each of these objects has a peer Netscape object that represents the associated Netscape window (or context) from which the plug-in was created. API calls are modeled as methods on the two objects.
A new instance is created whenever Netscape encounters data to be handled by a particular plug-in. There may be multiple instances of the same plug-in if there are multiple embedded objects on a single page or if several Netscape windows are open, each displaying the same data type. Plug-in instances are deleted when a user leaves the page.
All imaging and user interface events for an instance are handled in a platform-native way. The plug-in API provides a native window handle within which a plug-in should restrict its drawing. On some platforms all user event processing is relative to the window hierarchy, and the window handle is sufficient for event processing. On other platforms (notably the Macintosh) the native window is shared between the plug-in and the Netscape client, and events are explicitly provided to the plug-in by Netscape.
It is important that plug-ins do not block in any API call from the Netscape client. There is no yield function from the plug-in to Netscape since many plug-ins may be active at once. If a plug-in needs to do substantial asynchronous work, then it should use a separate thread or a timer if appropriate. In some cases a plug-in may achieve this goal by communicating with an entirely separate application thread. If a plug-in makes calls on the Netscape client object, it should be prepared to handle re-entrant API calls.
Streams are objects representing URLs and the data in them. Streams are associated with a specific instance of a plug-in, and there can be more than one stream object per instance. Streams can be created by Netscape in response to a document or user event, or streams may be explicitly requested by a plug-in. Typically an initial stream is generated by Netscape for each plug-in instance.
Initially streams are in push mode, where the stream data is provided as it is available. Plug-ins can request that streams be put in pull mode, where data is provided in response to specific read requests from the plug-in. In general this mode is more expensive, unless the stream is a local file. If the network protocol used for a particular stream is unable to support byte ranges, then pull mode may require that the entire file be downloaded before use.
Plug-ins have a facility to turn a network stream into a temporary local file and obtain a handle to that file. The use of this feature is strongly discouraged. Plug-ins should implement a stream-based interface wherever possible.
A plug-in may implement several methods. All methods except NP_New
are optional. Unless otherwise stated, ownership for all arguments in the API remains with the caller, and values are valid only for the duration of each call.
void NP_Initialize(void)
Global initialization for a plug-in. Called once when a plug-in is loaded and before any instances are created.
void NP_Shutdown(void)
Called when a plug-in is unloaded, typically at program termination time.
int *netscape_minor)
void NP_Version(int *plugin_major, int *plugin_minor, int *netscape_major,
Version information.
int16 argc, char *argn[], char *argv[], NPSavedData *saved)
NPError NP_New(void *pluginType, NPP instance, uint16 mode,
Creates a new instance of a plug-in. NPP
is an instance handle that uniquely describes this instance. Mode
indicates whether this instance is embedded or not. A list of name-value pairs may be passed in argc
, argn
, and argv
. These correspond to any HTML attributes associated with this instance. The final argument is any data saved for this instance as a result of a previous NP_Destroy
(see below). NP_New
returns 0L
or an error result if an instance cannot be created.
NPError NP_Destroy(NPP instance, NPSavedData **save)
Deletes a specific instance of a plug-in. All resources allocated to this instance should be relinquished. No further graphics operations should take place on any window objects associated with this instance.
The plug-in may specify in save
some specific piece of data, relative to this instance, that it would like preserved between instances. This is useful if the plug-in wishes to save some state so that, if the user were to return to exactly the same document at some time in the future, a new instance could be created that remembered the state. For example, a video player might choose to save the frame number that was last displayed so that, upon returning to this document, a new instance could initially display the same frame. This data is not persistent and may never be returned to the plug-in. The allocation space for the data passes ownership from the plug-in to Netscape when NP_Destroy
returns. Netscape can and will discard this data based on arbitrary criteria such as its size, the user's page history, and other factors. Plug-ins should treat it as a hint and not rely on it being provided in a future call to NP_New
.
NPError NP_SetWindow(NPP instance, NPWindow *window)
Provides a window for the plug-in to draw into. Typically this will be a subwindow of the Netscape window hierarchy. This method will only be called if the instance NPP
is of the types NPEmbed
or NPFull
. Subsequent calls to NP_SetWindow
for a single instance indicate that the window has been resized. A 0L
value for window
indicates that the plug-in should no longer use the window and must free any resources associated with it.
NPBool seekable, uint16 *stype)
NPError NP_NewStream(NPP instance, NPMIMEType type, NPStream *stream,
Notifies an instance of a new data stream. The stream may have been started by a user action or by a specific NP_GetUrl
request by the plug-in. The MIME-type of the stream is provided in type
. If the stream is known to be capable of byte-range requests, then the Boolean seekable
will be 1
. An instance can request stream modes other than the default (NPNormal
) by setting the value of stype
. The semantics of NPSeek
and NPAsFile
streams are described elsewhere.
int32 NP_WriteReady(NPP instance, NPStream *stream)
Returns the maximum number of bytes that an instance is prepared to accept in a subsequent NP_Write
call.
void *buf)
int32 NP_Write(NPP instance, NPStream *stream, int32 offset, int32 len,
Writes len
bytes of data in buf
to the stream
. Offset
is the logical position of buf
in an idealized file URL. A plug-in must consume at least as many bytes as it indicated in the preceding NP_WriteReady
call. A negative return value will cause an error on the stream which will subsequently be destroyed.
NPError NP_DestroyStream(NPP instance, NPStream *stream, NPError reason)
Closes and deletes the stream
. Reason
indicates why the stream was closed. Possible reasons are that it was complete, because there was some error, or because the user interrupted it.
void NP_StreamAsFile(NPP instance, NPStream *stream, const char* fname)
Provides a valid filename if a stream was opened in NPAsFile
mode and it completed without error. If the file was created from a network stream, it will be locked in the disk cache until the stream or its owning instance is destroyed.
int16 NP_HandleEvent(NPP instance, void *event)
Delivers a platform-specific event
to the instance
. Currently this function is only used on the Macintosh platform.
void NP_Print(NPP instance, void *platformPrint)
Requests a native print action for the current instance
. Platform-specific print machinery is provided in platformPrint
.
The following are the methods a plug-in can call on the Netscape client.
NPError NP_GetURL(NPP instance, const char *url, const char *window)
Requests that a new stream be created with the contents of url
. This operation is asynchronous and will happen at some time in the future. If window
is 0L
, then a new stream will be created for this instance, regardless of the type of the data. If window
is "_current"
, then the URL will be interpreted as though a user had requested it; this may result in the current plug-in being unloaded and the current view being replaced with the new MIME type.
*buf, NPBool file)
NPError NP_PostURL(NPP instance, const char *url, uint32 len, const char
Posts data to a URL.
NPError NP_RequestRead((NPStream *stream, NPByteRange *rangeList)
Requests a number of bytes for stream
. One or more NP_Writes
will result from this call. This operation is an error unless the stream is of type NPSeek
. Rangelist
is a 0L
terminated linked list of offsets and lengths to get from this stream. It is likely to be substantially more efficient to request a number of segments in one call than to make a number of separate calls to this routine.
NPError NP_NewStream(NPP instance, NPMIMEType type, NPStream *stream)
Creates a new stream of data from the plug-in to be interpreted by Netscape in the current window. This operation is currently only useful for instances of type NPBackground
.
int32 NP_Write(NPP instance, NPStream *stream, int32 len, void *buffer)
Writes len
bytes of data in buf
to the Netscape stream
.
NPError NP_DestroyStream(NPP instance, NPStream *stream, NPError reason)
Closes a stream object. Reason
indicates why the stream was closed.
void NP_Status((NPP instance, const char *message)
Provides a text status message that appears in the Netscape client user interface.
void *NP_MemAlloc (uint32 size)
Macintosh-specific.
void NP_MemFree (void *ptr)
Macintosh-specific.
uint32 NP_MemFlush(uint32 size)
Macintosh-specific.
Coming soon.
Coming soon.
Corporate Sales: 415/528-2555; Personal Sales: 415/528-3777
Copyright © 1996 Netscape Communications Corporation
If you have any questions, please visit Customer Service.