NPP_Destroy

  • Revision slug: NPP_Destroy
  • Revision title: NPP_Destroy
  • Revision id: 190954
  • Created:
  • Creator: Nickolay
  • Is current revision? No
  • Comment add <code> and links

Revision Content

{{wiki.template('Np-plugin-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.

See Also

NPP_New, NP_Shutdown, NPP, NPN_MemAlloc, NPSavedData

Revision Source

<p> 
{{wiki.template('Np-plugin-api')}}
</p>
<h3 name="Summary">Summary</h3>
<p>Deletes a specific instance of a plug-in.
</p>
<h3 name="Syntax">Syntax</h3>
<pre>#include &lt;npapi.h&gt;
 
NPError NPP_Destroy(NPP instance, 
                    NPSavedData **save);
</pre> 
<h3 name="Parameters">Parameters</h3>
<p>The function has the following parameters:
</p>
<dl><dt>instance
</dt><dd>Pointer to the plug-in instance to delete.
</dd><dt><span class="plain">**save</span>
</dt><dd>State or other information to save for reuse by a new instance of this plug-in at the same URL. Passed to <a href="en/NPP_New">NPP_New</a>.
</dd></dl>
<h3 name="Returns">Returns</h3>
<ul><li> If successful, the function returns <code>NPERR_NO_ERROR</code>.
</li><li> If unsuccessful, the plug-in is not loaded and the function returns an error code. For possible values, see <a href="en/NPAPI/Constants#Error_Codes">Error Codes</a>.
</li></ul>
<h3 name="Description">Description</h3>
<p><code>NPP_Destroy</code> 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 <code>instance-&gt;pdata</code> at this time.
</p><p>If this function is deleting the last instance of a plug-in, <a href="en/NP_Shutdown">NP_Shutdown</a> is subsequently called. Use <a href="en/NP_Shutdown">NP_Shutdown</a> to delete any data allocated in <a href="en/NP_Initialize">NP_Initialize</a> and intended to be shared by all instances of a plug-in.
</p><p>Use the optional <code>save</code> 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 <a href="en/NPP_New">NPP_New</a>.
</p><p>Avoid trying to save critical data with this function. Ownership of the <code>buf</code> field of the <a href="en/NPSavedData">NPSavedData</a> structure passes from the plug-in to the browser when <code>NPP_Destroy</code> returns. The browser can and will discard this data based on arbitrary criteria such as its size and the user's page history.
</p><p>To ensure that the browser does not crash or leak memory when the saved data is discarded, <a href="en/NPSavedData">NPSavedData</a>'s <code>buf</code> field should be a flat structure (a simple structure with no allocated substructures) allocated with <a href="en/NPN_MemAlloc">NPN_MemAlloc</a>.
</p>
<h5 name="Mac_OS">Mac OS</h5>
<p>If you want to restore state information if this plug-in is later recreated, use <a href="en/NP_MemAlloc">NP_MemAlloc</a> to create an <a href="en/NPSavedData">NPSavedData</a> structure.
</p>
<div class="note"> 
<p>NOTE: You should not perform any graphics operations in <code>NPP_Destroy</code> as the instance's window is no longer guaranteed to be valid. 
</p>
</div>
<h3 name="See_Also">See Also</h3>
<p><a href="en/NPP_New">NPP_New</a>, <a href="en/NP_Shutdown">NP_Shutdown</a>, <a href="en/NPP">NPP</a>, <a href="en/NPN_MemAlloc">NPN_MemAlloc</a>, <a href="en/NPSavedData">NPSavedData</a>
</p>
Revert to this revision