NPN_SetValue

  • Revision slug: NPN_SetValue
  • Revision title: NPN_SetValue
  • Revision id: 125658
  • Created:
  • Creator: Josh
  • Is current revision? No
  • Comment 2 words added

Revision Content

{{ Np-browser-api() }}

Summary

Implemented by browsers. This call is used to inform the browser of variable information controlled by the plugin.

Syntax

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

Parameters

The function has the following parameters:

instance
Pointer to the plugin instance setting the variable.
variable
Values the function can set:
  • NPPVpluginWindowBool: Sets windowed/windowless mode for plugin display; true=windowed, false=windowless
  • NPPVpluginTransparentBool: Sets transparent mode for display of a plugin; true=transparent, false=opaque
  • NPPVjavaClass
  • NPPVpluginWindowSize
  • NPPVpluginTimerInterval
  • NPPVpluginScriptableInstance
  • NPPVpluginScriptableIID
  • NPPVjavascriptPushCallerBool: Specifies whether you are pushing or popping the JSContext off the stack
  • NPPVpluginKeepLibraryInMemory: Tells browser that plugin dll should live longer than usual
  • NPPVpluginNeedsXEmbed
  • NPPVpluginScriptableNPObject
  • NPPVformValue
  • NPPVpluginDrawingModel
value
The value of the specified variable to be set.

Returns

  • If successful, the function should return NPERR_NO_ERROR.
  • If unsuccessful, the function should return the most relevant NPAPI error code. For possible values, see Error Codes.

Description

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

NPPVpluginWindowBool (Windows and Unix) specifies that the plugin operates in windowed mode. The alternative is windowless where no window messages are sent to the plugin as there is no window associated with it. In windowless mode all the browser to plugin communications related to drawing, mouse and keyboard input are accomplished via NPP_HandleEvent. To set windowless operation call NPN_SetValue with NPPVpluginWindowBool as the variable parameter and FALSE as the value parameter. By default, plugins are windowed.

NPPVpluginTransparentBool (Windows and Unix) specifies that a plugin is either opaque or transparent. To specify an opaque mode, the plugin calls NPN_SetValue with NPPVpluginTransparentBool for the variable parameter and FALSE for the 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 Plugins project page for more details).

NPPVpluginKeepLibraryInMemory specifies that the plugin 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 plugin all plugin instances get NPP_Destroy call, and if there is no more instances of the plugin active the plugin is called its NP_Shutdown method and the plugin dll gets unloaded from memory. If this is not desired, the plugin 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. Plugin 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, NPP_GetValue

Revision Source

<p>{{ Np-browser-api() }}</p>
<h3 name="Summary">Summary</h3>
<p>Implemented by browsers. This call is used to inform the browser of variable information controlled by the plugin.</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 plugin instance setting the variable. </dd></dl> <dl><dt>variable </dt><dd>Values the function can set:
<ul> <li><code>NPPVpluginWindowBool</code>: Sets windowed/windowless mode for plugin display; true=windowed, false=windowless</li> <li><code>NPPVpluginTransparentBool</code>: Sets transparent mode for display of a plugin; true=transparent, false=opaque</li> <li><code>NPPVjavaClass</code></li> <li><code>NPPVpluginWindowSize</code></li> <li><code>NPPVpluginTimerInterval</code></li> <li><code>NPPVpluginScriptableInstance</code></li> <li><code>NPPVpluginScriptableIID</code></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> <li><code>NPPVpluginNeedsXEmbed</code></li> <li><code>NPPVpluginScriptableNPObject</code></li> <li><code>NPPVformValue</code></li> <li><code>NPPVpluginDrawingModel</code></li>
</ul>
</dd></dl> <dl><dt>value </dt><dd>The value of the specified variable to be set. </dd></dl>
<h3 name="Returns">Returns</h3>
<ul> <li>If successful, the function should return <code>NPERR_NO_ERROR</code>.</li> <li>If unsuccessful, the function should return the most relevant NPAPI error code. For possible values, see <a href="/en/NPAPI/Constants#Error_Codes" title="en/NPAPI/Constants#Error_Codes">Error Codes</a>.</li>
</ul>
<h3 name="Description">Description</h3>
<p>A good place to set plugin operation mode such as windowless mode is <a href="/en/NPP_New" title="en/NPP_New">NPP_New</a>, so the browser knows right away what mode the plugin is designed to operate in.</p>
<p><strong>NPPVpluginWindowBool</strong> (Windows and Unix) specifies that the plugin operates in windowed mode. The alternative is windowless where no window messages are sent to the plugin as there is no window associated with it. In windowless mode all the browser to plugin communications related to drawing, mouse and keyboard input are accomplished via <a href="/en/NPP_HandleEvent" title="en/NPP_HandleEvent">NPP_HandleEvent</a>. To set windowless operation call <code>NPN_SetValue</code> with <code>NPPVpluginWindowBool</code> as the variable parameter and FALSE as the value parameter. By default, plugins are windowed.</p>
<p><strong>NPPVpluginTransparentBool</strong> (Windows and Unix) specifies that a plugin is either opaque or transparent. To specify an opaque mode, the plugin calls <code>NPN_SetValue</code> with <code>NPPVpluginTransparentBool</code> for the variable parameter and FALSE for the value parameter. To specify a transparent mode, the value parameter should be set to TRUE.</p>
<p><strong>NPPVjavascriptPushCallerBool</strong> sets whether you are pushing or popping the appropriate JSContext off of the stack (See the two-way scriptability article on the Mozilla Plugins project page for more details).</p>
<p><strong>NPPVpluginKeepLibraryInMemory</strong> specifies that the plugin 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 plugin all plugin instances get <a href="/en/NPP_Destroy" title="en/NPP_Destroy">NPP_Destroy</a> call, and if there is no more instances of the plugin active the plugin is called its <a href="/en/NP_Shutdown" title="en/NP_Shutdown">NP_Shutdown</a> method and the plugin dll gets unloaded from memory. If this is not desired, the plugin can instruct the browser not to unload the dll and not to call <a href="/en/NP_Shutdown" title="en/NP_Shutdown">NP_Shutdown</a> when the page is left. In such a case all this will be done on the browser shutdown. Plugin 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" title="en/NP_Shutdown">NP_Shutdown</a> call.</p>
<h3 name="Remarks">Remarks</h3>
<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>
<h3 name="See_Also">See Also</h3>
<p><a href="/en/NPP_New" title="en/NPP_New">NPP_New</a>, <a href="/en/NPN_GetValue" title="en/NPN_GetValue">NPN_GetValue</a>, <a href="/en/NPP_SetValue" title="en/NPP_SetValue">NPP_SetValue</a>, <a class="internal" href="/En/NPP%20GetValue" title="En/NPP GetValue">NPP_GetValue</a></p>
Revert to this revision