NPN_SetValue

  • Revision slug: NPN_SetValue
  • Revision title: NPN_SetValue
  • Revision id: 125647
  • Created:
  • Creator: Pmash
  • Is current revision? No
  • Comment migration

Revision Content

{{wiki.template('Np-browser-api')}}

Summary

Sets various modes of plug-in operation.

Syntax

#include <npapi.h>
 
NPError NPN_SetValue(NPP         instance,
                     NPPVariable variable, 
                     void        *value);

Parameters

The function has the following parameters:

instance
Pointer to the current plug-in instance.
variable
Values the function can set:
  • NPPVpluginWindowBool: Sets windowless mode for display of a plug-in; true=windowless, false=not windowless
  • NPPVpluginTransparentBool: Sets transparent mode for display of a plug-in; true=transparent, false=opaque
  • NPPVjavascriptPushCallerBool: - Specifies whether you are pushing or popping the JSContext off the stack
  • NPPVpluginKeepLibraryInMemory: - Tells browser that plugin dll should live longer than usual
value
The value of the specified variable to be set, TRUE or FALSE.

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

A good place to set plug-in operation mode such as windowless mode is NPP_New, so the browser knows right away what mode the plug-in is designed to operate in.

NPPVpluginWindowBool (Windows and Unix) specifies that plug-in operates in windowless mode. In this mode no window messages are send to the plug-in as there is no window associated with it, all the browser to plug-in commucations related to drawing and mouse and keyboard input are event based and accomplished via NPP_HandleEvent. To set windowless operation plugin calls NPN_SetValue with NPPVpluginWindowBool as its variable parameter and TRUE as its value parameter. As a default, plug-ins are windowd, so if NPP_New does not contain this call the plug-in is considered to be windowed.

NPPVpluginTransparentBool (Windows and Unix) specifies that a plug-in is either opaque or transparent. To specify an opaque mode, the plugin calls NPN_SetValue with NPPVpluginTransparentBool for its variable parameter and FALSE for its value parameter. To specify a transparent mode, the value parameter should be set to TRUE.

NPPVjavascriptPushCallerBool sets whether you are pushing or popping the appropriate JSContext off of the stack (See the two-way scriptability article on the Mozilla Plug-ins project page for more details).

NPPVpluginKeepLibraryInMemory specifies that the plug-in does not want to be unloaded from memory after the page which initiated it has gone. Normally, when the browser navigates away from the page containing the plug-in all plug-in instances get NPP_Destroy call, and if there is no more instances of the plug-in active the plug-in is called its NP_Shutdown method and the plug-in dll gets unloaded from memory. If this is not desired the plug-in can instruct the browser not to unload the dll and not to call NP_Shutdown when the page is left. In such a case all this will be done on the browser shutdown. Plug-in calls NPN_SetValue any time with NPPVpluginKeepLibraryInMemory as variable parameter and value set to TRUE. By default, the dll will be unloaded from memory preceded by NP_Shutdown call. Remarks

All four variable values are boolean. Although the function prototype has type of value void *, the actual boolean should be placed there, not a pointer to a boolean. The browser code reads this parameter as follows (NPPVpluginWindowBool as an example):

NPError NP_EXPORT _setvalue(NPP npp, NPPVariable variable, void *value)
{
 ...
 BOOL bWindowless = (value == NULL);
 ...
}

So the proper way to call this function from a plug-in would be:

BOOL bWindowed = FALSE;

NPN_SetValue(npp, NPPVpluginWindowBool, (
      void *)bWindowed); 


See Also

NPP_New, NPN_GetValue, NPP_SetValue

Revision Source

<p>
{{wiki.template('Np-browser-api')}}
</p>
<h3 name="Summary">Summary</h3>
<p>Sets various modes of plug-in operation.
</p>
<h3 name="Syntax">Syntax</h3>
<pre>#include &lt;npapi.h&gt;
 
NPError NPN_SetValue(NPP         instance,
                     NPPVariable variable, 
                     void        *value);
</pre>
<h3 name="Parameters">Parameters</h3>
<p>The function has the following parameters:
</p>
<dl><dt>instance
</dt><dd>Pointer to the current plug-in instance.
</dd></dl>
<dl><dt>variable
</dt><dd>Values the function can set:
<ul><li> <code>NPPVpluginWindowBool</code>: Sets windowless mode for display of a plug-in; true=windowless, false=not windowless
</li><li> <code>NPPVpluginTransparentBool</code>: Sets transparent mode for display of a plug-in; true=transparent, false=opaque
</li><li> <code>NPPVjavascriptPushCallerBool</code>: - Specifies whether you are pushing or popping the JSContext off the stack
</li><li> <code>NPPVpluginKeepLibraryInMemory</code>: - Tells browser that plugin dll should live longer than usual 
</li></ul>
</dd></dl>
<dl><dt>value
</dt><dd>The value of the specified variable to be set, TRUE or FALSE.
</dd></dl>
<h3 name="Returns">Returns</h3>
<ul><li> If successful, the function returns NPERR_NO_ERROR.
</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>A good place to set plug-in operation mode such as windowless mode is <a href="en/NPP_New">NPP_New</a>, so the browser knows right away what mode the plug-in is designed to operate in.
</p><p><b>NPPVpluginWindowBool</b> (Windows and Unix) specifies that plug-in operates in windowless mode. In this mode no window messages are send to the plug-in as there is no window associated with it, all the browser to plug-in commucations related to drawing and mouse and keyboard input are event based and accomplished via <a href="en/NPP_HandleEvent">NPP_HandleEvent</a>. To set windowless operation plugin calls <code>NPN_SetValue</code> with <code>NPPVpluginWindowBool</code> as its variable parameter and TRUE as its value parameter. As a default, plug-ins are windowd, so if <a href="en/NPP_New">NPP_New</a> does not contain this call the plug-in is considered to be windowed.
</p><p><b>NPPVpluginTransparentBool</b> (Windows and Unix) specifies that a plug-in is either opaque or transparent. To specify an opaque mode, the plugin calls <code>NPN_SetValue</code> with <code>NPPVpluginTransparentBool</code> for its variable parameter and FALSE for its value parameter. To specify a transparent mode, the value parameter should be set to TRUE.
</p><p><b>NPPVjavascriptPushCallerBool</b> sets whether you are pushing or popping the appropriate JSContext off of the stack (See the two-way scriptability article on the Mozilla Plug-ins project page for more details).
</p><p><b>NPPVpluginKeepLibraryInMemory</b> specifies that the plug-in does not want to be unloaded from memory after the page which initiated it has gone. Normally, when the browser navigates away from the page containing the plug-in all plug-in instances get <a href="en/NPP_Destroy">NPP_Destroy</a> call, and if there is no more instances of the plug-in active the plug-in is called its <a href="en/NP_Shutdown">NP_Shutdown</a> method and the plug-in dll gets unloaded from memory. If this is not desired the plug-in can instruct the browser not to unload the dll and not to call <a href="en/NP_Shutdown">NP_Shutdown</a> when the page is left. In such a case all this will be done on the browser shutdown. Plug-in calls <code>NPN_SetValue</code> any time with NPPVpluginKeepLibraryInMemory as variable parameter and value set to TRUE. By default, the dll will be unloaded from memory preceded by <a href="en/NP_Shutdown">NP_Shutdown</a> call.
Remarks
</p><p>All four variable values are boolean. Although the function prototype has type of value void *, the actual boolean should be placed there, not a pointer to a boolean. The browser code reads this parameter as follows (NPPVpluginWindowBool as an example):
</p>
<pre>NPError NP_EXPORT _setvalue(NPP npp, NPPVariable variable, void *value)
{
 ...
 BOOL bWindowless = (value == NULL);
 ...
}
</pre> 
<p>So the proper way to call this function from a plug-in would be:
</p>
<pre>BOOL bWindowed = FALSE;

NPN_SetValue(npp, NPPVpluginWindowBool, (
      void *)bWindowed); 
</pre>
<p><br>
</p>
<h3 name="See_Also">See Also</h3>
<p><a href="en/NPP_New">NPP_New</a>, <a href="en/NPN_GetValue">NPN_GetValue</a>, <a href="en/NPP_SetValue">NPP_SetValue</a>
</p>
Revert to this revision