Quick Reference to Functional Groups | URL Methods |
Initialization and Destruction Methods | Memory Methods |
Drawing Methods | Utility Methods |
Stream Methods | Methods for Communicating with Java |
Initialization and Destruction: Summary | Memory: Summary |
Drawing Event Handling: Summary | Utility: Summary |
Stream: Summary | Communicating with Java: Summary |
URL: Summary |
[Top] [Reference to Functions by Functional Group]
Method Name | Description |
---|---|
NPP_Initialize |
Provides global initialization for a plug-in. |
NPP_New |
Creates a new instance of a plug-in. |
NPP_Destroy |
Deletes a specific instance of a plug-in. |
NPP_Shutdown |
Provides global deinitialization for a plug-in. |
[Top] [Reference to Functions by Functional Group]
Method Name | Description |
---|---|
NPP_HandleEvent |
Delivers a platform-specific event to the instance. |
NPP_SetWindow |
Tells the plug-in when a window is created, moved, sized, or destroyed. |
NPP_Print |
Requests a platform-specific print operation for an embedded or full-screen plug-in. |
NPP_GetValue |
Allows the Navigator to query the plug-in for information. |
NPP_SetValue |
Sets information about the plug-in, called by the plug-in. |
NPN_ForceRedraw |
Forces a paint message for a windowless plug-in. |
NPN_InvalidateRect |
Invalidates specified drawing area prior to repainting or refreshing a windowless plug-in. |
NPN_InvalidateRegion |
Invalidates specified drawing region prior to repainting or refreshing a windowless plug-in. |
NPN_GetValue |
Allows the plug-in to query Communicator for information. |
NPP_SetValue |
Sets information about the plug-in; called by Communicator. |
[Top] [Reference to Functions by Functional Group]
Method Name | Description |
---|---|
NPP_NewStream |
Notifies a plug-in instance of a new data stream. |
NPP_DestroyStream |
Tells the plug-in that a stream is about to be closed or destroyed. |
NPP_StreamAsFile |
Provides a local file name for the data from a stream. |
NPP_Write |
Delivers data to a plug-in instance. |
NPP_WriteReady |
Returns the maximum number of bytes that an instance can consume. |
NPN_DestroyStream |
Closes and deletes a stream. |
NPN_NewStream |
Requests the creation of a new data stream produced by the plug-in and consumed by Communicator. |
NPN_Write |
Delivers data to a plug-in instance. |
NPN_RequestRead |
Requests a range of bytes from a seekable stream. |
[Top] [Reference to Functions by Functional Group]
Method Name | Description |
---|---|
NPP_URLNotify |
Notifies the plug-in of the completion of a URL request. |
NPN_GetURL |
Requests Communicator to create a stream for the specified URL. |
NPN_GetURLNotify |
Requests creation of a new stream with the contents of the specified URL, and notifies the plug-in of the result. |
NPN_PostURL |
Posts data from a file or buffer to a URL. |
NPN_PostURLNotify |
Posts data from a file or buffer to a URL, and receives notification of the result. |
[Top] [Reference to Functions by Functional Group]
Method Name | Description |
---|---|
NPN_MemAlloc |
Allocates memory from Communicator's memory space. |
NPN_MemFlush |
Mac OS only. Requests that Communicator free a specified amount of memory. |
NPN_MemFree |
Deallocates a block of allocated memory. |
[Top] [Reference to Functions by Functional Group]
Method Name | Description |
---|---|
NPN_ReloadPlugins |
Reloads all plug-ins in the Plugins directory. |
NPN_Status |
Displays a message on the status line of the browser window. |
NPN_UserAgent |
Returns the Communicator user agent field. |
NPN_Version |
Returns version information for the Plug-in API. |
[Top] [Reference to Functions by Functional Group]
Method Name | Description |
---|---|
NPP_GetJavaClass |
Returns the Java class associated with the plug-in. |
NPN_GetJavaEnv |
Returns a pointer to the Java execution environment. |
NPN_GetJavaPeer |
Returns the Java object associated with the plug-in. |
[Top] [Reference to Functions by Functional Group]
NPP_Initialize |
NPP_New |
NPP_Destroy |
NPP_Shutdown |
Four methods from the Plug-in group of Plug-in API methods mark essential stages in the life of a plug-in. They provide services that every plug-in must include: initialization, instance creation and destruction, and shutdown.
See Chapter 3, "Initialization and Destruction," for information about using these methods.
[Top] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
#include <npapi.h> NPError NPP_Initialize(void)
After the last instance of a plug-in has been deleted, Communicator calls NPP_Shutdown, where you can release allocated memory or resources.
NPP_Shutdown, NPP_New"Initialization"
[Top] [Initialization and Destruction Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
#include <npapi.h> NPError NPP_Destroy(NPP instance, NPSavedData **save);
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. |
If this function is deleting the last instance of a plug-in, NPP_Shutdown is subsequently called. Use NPP_Shutdown to delete any data allocated in NPP_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 Communicator when NPP_Destroy returns. The Communicator can and will discard this data based on arbitrary criteria such as its size and the user's page history.
To ensure that Communicator 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.
NOTE: You should not perform any graphics operations in NPP_Destroy as the instance's window is no longer guaranteed to be valid. §
NPP_New, NPP_Shutdown, NPP, NPN_MemAlloc, NPSavedData"Instance Destruction"
[Top] [Initialization and Destruction Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
#include <npapi.h> NPError NPP_New(NPMIMEType pluginType, NPP instance, uint16 mode, int16 argc, char *argn[], char *argv[], NPSavedData *saved);
The plug-in's NPP pointer is valid until the instance is destroyed with NPP_Destroy.
If instance data was saved from a previous instance of the plug-in by the NPP_Destroy function, it is returned in the saved parameter for the current instance to use.
All attributes in the EMBED tag (standard and private) are passed in NPP_New in the argn and argv arrays. Communicator ignores any non-standard attributes within an EMBED tag. This gives developers a chance to use private attributes to communicate instance-specific options or other information to the plug-in. Place private options at the end of the list of standard attributes in the EMBED Tag.
NPP_Destroy, NPP_Shutdown, NPP, NPSavedData"Instance Creation," "EMBED Tag"
[Top] [Initialization and Destruction Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
#include <npapi.h> void NPP_Shutdown(void);
If you have defined a Java class for your plug-in, be sure to release it at this time so that Java can unload it and free up memory.
NOTE: If enough memory is available, Communicator can keep the plug-in library loaded if it expects to create more instances in the near future. Communicator calls NPP_Shutdown only when the library is finally unloaded. §
WARNING: Library unloading for plug-ins that use LiveConnect: The plug-in library may not be unloaded until Java garbage collection occurs, and when the plug-in's peer class native methods are unloaded. Developers should be aware that this could happen at any time, even long after the NPP_Shutdown call. §
NPP_Initialize, NPP_Destroy"Instance Destruction"
[Top] [Initialization and Destruction Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
Netscape Methods | Plug-in-Methods | Query/Set Information |
---|---|---|
NPN_ForceRedraw |
NPP_GetValue |
NPN_GetValue |
NPN_InvalidateRect |
NPP_HandleEvent |
NPN_SetValue |
NPN_InvalidateRegion |
NPP_Print |
|
NPP_SetValue |
||
NPP_SetWindow |
In order to draw windowed and windowless plug-ins and handle events, you use a variety of functions from the Netscape and Plug-in groups. This section also contains reference entries for methods that query and set information.
See Chapter 4, "Drawing and Event Handling," for information about using these methods.
Allows Communicator to query the plug-in for information
#include <npapi.h> NPError NPP_GetValue(void *instance, NPPVariable variable, void *value);
You can use this method as an optional entry point that Communicator can call to determine the plug-in name and description. It returns the requested values, specified by the variable and value parameters, to the plug-in.
NPP_SetValue, NPP"Specifying That a Plug-in Is Windowless"
[Top] [Drawing Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
Delivers a platform-specific window event to the instance
#include <npapi.h> int16 NPP_HandleEvent(NPP instance, void* event);
NPEvent"Event Handling for Windowed Plug-ins," "Event Handling for Windowless Plug-ins"
[Top] [Drawing Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
#include <npapi.h> void NPP_Print(NPP instance, NPPrint* PrintInfo);
instance |
Pointer to the current plug-in instance. Must be embedded or full-screen. |
printInfo |
Pointer to NPPrint structure. |
WARNING: To avoid an issue with backward-compatibility that occurred in Communicator 4.0 and was resolved in 4.03, be sure to upgrade to the latest version of the Plug-in API. Make sure that the minor version constant is set to 11. §
NPPrint, NPFullPrint, NPEmbedPrint"Drawing Plug-ins"
[Top] [Drawing Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
Sets information about the plug-in
#include <npapi.h> NPError NPP_SetValue(void *instance, NPPVariable variable, void *value);
For example, to specify that a plug-in is windowless, use NPP_SetValue with NPPVpluginWindowBool as the variable to set and false as the value parameter. If a plug-in does not make this call, it is considered a windowed plug-in.
NPP_New, NPP_GetValue[Top] [Drawing Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
#include <npapi.h> NPError NPP_SetWindow(NPP instance, NPWindow *window);
The data structure passed in NPP_SetWindow is an NPWindow object, which contains the coordinates of the instance's area and various platform-specific data. This window is valid for the life of the instance, or until NPP_SetWindow is called again with a different value.
For windowed plug-ins on Windows and Unix, the window parameter contains a handle to a subwindow of the Netscape window hierarchy. On Mac OS, this field points to an NP_Port structure. For windowless plug-ins, it is a platform-specific handle to a drawable.
Before setting the window parameter to point to a new window, it is a good idea to compare the information about the new window to the previous window (if one existed) to account for any changes.
NOTE: NPP_SetWindow is useful only for embedded (NP_EMBED) or full-screen (NP_FULL) plug-ins, which are drawn into windows. It is irrelevant for hidden plug-ins. §
NPP_HandleEvent, NPWindow, NP_Port"Drawing Plug-ins," "Windowed Plug-ins"
[Top] [Drawing Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
Forces a paint message for a windowless plug-in
#include <npapi.h> void NPN_ForceRedraw(NPP instance);
instance |
Plug-in instance for which the function forces redrawing. |
Once a value has been invalidated with NPN_InvalidateRect or NPN_InvalidateRegion, a plug-in can call NPN_ForceRedraw to force a paint message. This causes a synchronous update event or paint message for the plug-in.
NPN_InvalidateRect, NPN_InvalidateRegion, NPP"Forcing a Paint Message"
[Top] [Drawing Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
Invalidates specified drawing area prior to repainting or refreshing a windowless plug-in
#include <npapi.h> void NPN_InvalidateRect(NPP instance, NP_Rect *invalidRect);
instance |
Pointer to the current plug-in instance. |
invalidRect |
The area to invalidate, specified in a coordinate system that originates at the top left of the plug-in. |
NPN_InvalidateRect causes the NPP_HandleEvent method to pass an update event or a paint message to the plug-in. After calling this method, the plug-in receives a paint message asynchronously.
Communicator redraws invalid areas of the document and any windowless plug-ins at regularly timed intervals. To force a paint message, the plug-in can call NPN_ForceRedraw after calling this method.
NPN_ForceRedraw, NPN_InvalidateRegion, NP_Rect, NPP"Invalidating the Drawing Area," "Forcing a Paint Message"
[Top] [Drawing Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
Invalidates specified drawing region prior to repainting or refreshing a windowless plug-in
#include <npapi.h> void NPN_InvalidateRegion(NPP instance, NP_Region invalidRegion);
instance |
Pointer to the current plug-in instance. |
invalidRegion |
The area to invalidate, specified in a coordinate system that originates at the top left of the plug-in. |
NPN_InvalidateRegion causes the NPP_HandleEvent method to pass an update event or a paint message to the plug-in. If a plug-in calls this method, it receives a paint message later. Communicator redraws invalid areas of the document and windowless plug-ins at regularly timed intervals. To force a paint message, the plug-in can call NPN_ForceRedraw after calling this method.
NPN_ForceRedraw, NPN_InvalidateRect, NP_Region, NPP"Invalidating the Drawing Area," "Forcing a Paint Message"
[Top] [Drawing Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
Currently used only on Unix and Windows.
Allows the plug-in to query Communicator for information
#include <npapi.h> NPError NPN_GetValue(NPP instance, NPNVariable variable, void *value);
The method returns a value of type HWND. In many cases, a plug-in may still have to create its own window (a transparent child window of the browser window) to act as the owner window for popup menus and modal dialogs. This transparent child window can have its own WindowProc within which the plug-in can deal with WM_COMMAND messages sent to it a result of tracking the popup menu or modal dialog.
NPN_SetValue, NPP_GetValue, NPP_SetValue"Drawing Plug-ins," "Creating Pop-up Menus and Dialog Boxes"
[Top] [Drawing Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]
Sets windowless plug-in as transparent or opaque
#include <npapi.h> NPError NPN_SetValue(NPP instance, NPNVariable variable, void *value);
instance |
Pointer to the current plug-in instance. |
variable |
Unix only: Information the call is setting. Values: |
value |
Function returns the name of the plug-in in the value parameter. |
To specify an opaque windowless plug-in, Communicator calls NPN_SetValue with NPPVpluginWindowBool for its variable parameter and false for its value parameter.
To specify a transparent windowless plug-in, Communicator calls NPN_SetValue with NPPVpluginTransparentBool for its variable parameter and false for its value parameter.
The plug-in makes this call from its NPP_New method. As a default, plug-ins are windowed, so if the NPP_New method does not include this call, the plug-in is considered to be windowed.
NPP_New, NPN_GetValue, NPP_SetValue"Specifying That a Plug-in Is Windowless"
[Top] [Drawing Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]