APIs for inline viewers

Contents

• Introduction
• plug-ins overview
• API details

Introduction

Things get even more complicated when trying to support document formats that haven't yet been invented.

PLUG-IN

• The plug-ins are not normally be provided with the browser. The likelihood is that you will have to buy a plug-in from a 3rd party and put them in a place that netscape expects to find plug-ins.

• Each alien document/image will have its own copy of the plug-in working on its behalf. It is discarded when another document is loaded into the frame/browser.

• On startup, netscape looks at which plug-ins are available to it. These are loaded only when they are needed and are each given a (sub)window to display their results in.

• in addition to the display window, each plug-in is also given a stream from which it can (should) request the contents of the url (document to be displayed.

  Naturally some document formats just can not be read in one go. It is possible to convert the given stream into a temporary local file and operate on that.

Plug-in Methods

The following methods may be implemented by a plug-in. NP_New must be implemented by the plug-in.

void NP_Initialize(void)

Global initialization for a plug-in. Called only the 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.

NPError NP_New(void *pluginType, NPP instance, NPPluginType mode, int16 argc, char *argn[], char *argv[], NPSavedData *saved)

Creates a new instance of a plug-in. NPP is an instance handle which 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 NULL 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 which is relative to this instance which 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 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 users 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 sub-window of the Netscape window hierarchy. This method will only be called if the instance NPP is of type NPEmbed or NPFull. Subsequent calls to NP_SetWindow for a single instance indicate that the window has been resized. A NULL value for window indicates that the plug-in should no longer use the window and must free any resources associated with it.

NPError NP_NewStream(NPP instance, NPMIMEType type, NPStream *stream, NPBool seekable, NPStreamType *stype)

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 TRUE. 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.

int32 NP_Write(NPP instance, NPStream *stream, int32 offset, int32 len, void *buf)

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. TBD: The printing API is not specified by this current draft of the spec.

Netscape Methods

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 NULL 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 and this may result in the current plug-in being unloaded and the current view being replaced with the new mime-type.

NPError NP_PostURL(NPP instance, const char *url, uint32 len, const char *buf, NPBool file)

Posts data to a URL. Currently unimplemented.

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 NULL 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 which appears in the Netscape client user interface.

---