« Gecko Plugin API Reference « Plug-in Side Plug-in API
Summary
Deletes a specific instance of a plug-in.
Syntax
#include <npapi.h>
NPError NPP_Destroy(NPP instance,
NPSavedData **save);
Parameters
The function has the following parameters:
- instance
- Pointer to the plug-in instance to delete.
- **save
- State or other information to save for reuse by a new instance of this plug-in at the same URL. Passed to NPP_New.
Returns
- If successful, the function returns
NPERR_NO_ERROR. - If unsuccessful, the plug-in is not loaded and the function returns an error code. For possible values, see Error Codes.
Description
NPP_Destroy releases the instance data and resources associated with a plug-in. The browser calls this function when a plug-in instance is deleted, typically because the user has left the page containing the instance, closed the window, or quit the browser. You should delete any private instance-specific information stored in the plug-in's instance->pdata at this time.
If this function is deleting the last instance of a plug-in, NP_Shutdown is subsequently called. Use NP_Shutdown to delete any data allocated in NP_Initialize and intended to be shared by all instances of a plug-in.
Use the optional save parameter if you want to save and reuse some state or other information. Upon the user's return to the page, this information is passed to the new plug-in instance when it is created with NPP_New.
Avoid trying to save critical data with this function. Ownership of the buf field of the NPSavedData structure passes from the plug-in to the browser when NPP_Destroy returns. The browser can and will discard this data based on arbitrary criteria such as its size and the user's page history.
To ensure that the browser does not crash or leak memory when the saved data is discarded, NPSavedData's buf field should be a flat structure (a simple structure with no allocated substructures) allocated with NPN_MemAlloc.
Mac OS
If you want to restore state information if this plug-in is later recreated, use NP_MemAlloc to create an NPSavedData structure.
NOTE: You should not perform any graphics operations in NPP_Destroy as the instance's window is no longer guaranteed to be valid.