NPP_Destroy is called when a plug-in instance is deleted, typically because the user has left the page containing the instance, closed the window, or quit the application. You should delete any private instance-specific information stored in instance->pdata. If the instance being deleted is the last instance created by your plug-in, NPP_Shutdown will subsequently be called, where you can delete any data allocated in NPP_Initialize to be shared by all your plug-in's instances. Note that you should not perform any graphics operations in NPP_Destroy as the instance's window is no longer guaranteed to be valid.
You can use the save parameter if you want to save some state or other information to be reused by a new instance with the same URL. This data will be passed to the new instance via a parameter to NPP_New, called when the instance is created. For example, a video player might choose to save the frame number that was last displayed. If the user returned to the page, when the new instance was created it would have the previous frame number passed to it, so it could initially display the same frame.
Note that ownership of the buf field of the NPSavedData structure passes from the plug-in to Netscape when NPP_Destroy returns. Netscape can and will discard this data based on arbitrary criteria such as its size and the user's page history; thus you should not save critical data using this mechanism. To ensure that Netscape does not crash or leak memory when the saved data is discarded, the buf should be a flat structure (i.e., a simple structure with no allocated substructures) allocated with NPN_MemAlloc. For example:
The NPP_DestroyStream function is called when the stream identified by stream for the plug-in instance denoted by instance will be destroyed. You should delete any private data allocated in stream->pdata at this time.
The reason the stream was destroyed is indicated by the by the parameter reason. The most common reason code is NPRES_DONE, indicating simply that the stream completed normally because all data was sent to the instance. Other possible reason codes are NPRES_USER_BREAK, indicating that the user canceled the stream by clicking the "Stop" button, and NPRES_NETWORK_ERR, indicating that the stream failed due to network problems. The complete list of reason codes is found in npapi.h.
Delivers a platform-specific event to the instance.
On the Macintosh, event is a pointer to a standard Macintosh EventRecord. All standard event types are passed to the instance as appropriate. In general, return TRUE if you handle the event and FALSE if you ignore the event.
In addition to these standard types, three additional event types may be passed in the event->what field of the EventRecord:
This function is called once when a plug-in is loaded, before the first instance is created. You should allocate any memory or resources shared by all instances of your plug-in at this time. After the last instance has been deleted, NPP_Shutdown will be called, where you can release any memory or resources allocated by NPP_Initialize.
NPP_New creates a new instance of your plug-in with MIME type specified by pluginType. The parameter mode is NP_EMBED if the instance was created by an EMBED tag, or NP_FULL if the instance was created by a separate file. You can allocate any instance-specific private data in instance->pdata at this time. The NPP pointer is valid until the instance is destroyed.
The parameters argc, argn and argv pass a list of name-value pairs to the plug-in for the HTML attributes associated with this instance. Since Netscape ignores any non-standard attributes within an EMBED tag, you can use private attributes to communicate instance-specific options or other information to the plug-in. For example, the following EMBED tag has the standard attributes SRC, HEIGHT, and WIDTH, and the private attribute LOOP:
NPP_NewStream notifies the instance denoted by instance of the creation of a new stream specifed by stream. The NPStream* pointer is valid until the stream is destroyed. The MIME type of the stream is provided by the parameter type.
The stream may have been started by Netscape from the file specified in the SRC attribute of the EMBED tag (for an embedded instance) or the file itself (for a full-page instance). A plug-in can also request a stream with function NPN_GetURL. NPP_DestroyStream is called when the stream completes (either successfully or abnormally). The plug-in can terminate the stream itself by calling NPN_DestroyStream.
The parameter stype defines the mode of the stream. By default the mode is NP_NORMAL, but the plug-in can request a different mode if necessary:
NPP_Print requests the plug-in instance identified by instance to print itself. If the instance is full-page, NPP_Print will initially be called with platformPrint->mode equal to NP_FULL before Netscape displays any print dialogs. If the plug-in wishes to completely control the print process for this instance, it can access the platform-specific printer information in platformPrint and handle the print dialogs and printing process as it sees fit. If the plug-in does print the instance in full-page mode, it should set pluginPrinted to TRUE. If the plug-in does not want to take control of the complete printing process it can set pluginPrinted to FALSE (the default value) and Netscape will display whatever print dialogs are necessary and call NPP_Print again (this time, with platformPrint->mode equal to NP_EMBED).
If the instance is embedded, or full-page but the plug-in declined control of the print process as described above, NPP_Print will be called with platformPrint->mode equal to NP_EMBED. platformPrint->embedPrint.window contains the window that the plug-in should render the instance into for printing.
On the Macintosh, when printing in mode NP_FULL the field platformPrint contains a standard Macintosh THPrint (see Printing.h).
On Windows, note that the coordinates for the window rectangle are in TWIPS. Therefore you need to convert the x-y point using the Windows API call DPtoLP() when you output text.
NPP_SetWindow informs the plug-in instance specified by instance of the the window denoted by window in which the instance draws. This NPWindow pointer is valid for the life of the instance, or until NPP_SetWindow is called again with a different value. Subsequent calls to NPP_SetWindow for a given instance typically indicate that the window has been resized. If either window or window->window are NULL, the plug-in must not perform any additional graphics operations on the window and should free any resources associated with the window.
On Windows and UNIX, the platform-specific window information specified in window->window is a handle to a subwindow of the Netscape window hierarchy. On the Macintosh, this field points to a NP_Port structure.
This function is called once after the last instance of your plug-in is destroyed. Use this function to release any memory or resources shared across all instances of your plug-in.
NPP_StreamAsFile provides the instance with a full path to a local file, identified by fname, for the stream specified by stream. NPP_StreamAsFile is called as a result of the plug-in requesting mode NP_ASFILEONLY or NP_ASFILE in a previous call to NPP_NewStream. If an error occurs while retrieving the data or writing the file, fname may be NULL.
Note that if the file is created from a stream from the network, the file is locked in the Netscape disk cache until the stream or its instance is destroyed.
NPP_Write is called after a call to NPP_NewStream in which the plug-in requested a normal-mode stream, in which the data in the stream is delivered progressively over a series of calls to NPP_WriteReady and NPP_Write. The function delivers a buffer buf of len bytes of data from the stream identified by stream to the instance. The parameter offset is the logical position of buf from the beginning of the data in the stream.
The function returns the number of bytes written (consumed by the instance). A negative return value causes an error on the stream, which will subsequently be destroyed via a call to NPP_DestroyStream.
Note that a plug-in must consume at least as many bytes as it indicated in the preceeding NPP_WriteReady call. All data consumed must be either processed immediately or copied to memory allocated by the plug-in: the buf parameter is not persistent.
NPP_WriteReady determines the maximum number of bytes that the instance will consume from the stream in a subsequent call NPP_Write. This function allows Netscape to only send as much data to the instance as the instance is capable of handling at a time, allowing more efficient use of resources within both Netscape and the plug-in.
For example, suppose the plug-in allocates in NPP_NewStream an 8K buffer to hold the data written from that stream. In the first call to NPP_WriteReady it could return 8192, resulting in a call to NPP_Write with a buffer of up to 8K bytes. After this data is copied from Netscape's buffer to the plug-in's buffer, the plug-in begins to asynchronously process the data. When the next NPP_WriteReady call is made, only half of the data has been processed, so to avoid allocating additional buffers, the plug-in could return 4096, resulting in a call to NPP_Write of up to 4K bytes.
Note that the buffer passed to NPP_Write may be larger than the size returned from NPP_WriteReady. The value returned from NPP_WriteReady is only a promise to consume a certain amount of data from the buffer, not an upper limit on the buffer size. In the example above, if the plug-in allocates an 8K buffer and returns 8192 from NPP_Write, but gets 10000 bytes from Netscape in a subsequent call to NPP_Write, the plug-in should copy the first 8192 bytes from Netscape's buffer into its own buffer, and return 8192 (the number of bytes actually consumed) from NPP_Write.