Chapter 9
Plug-in API Reference

To help you familiarize yourself with the Plug-in API as quickly as possible, this reference is organized into sections by task and parallels the organization of Chapters 3 through 8.

Functions

Structures

Constants and Definitions

[Top]

Functions

You can look up Plug-in API functions by functional group or API group.

Reference to Functions by Functional Group

API Organization: Netscape and Plug-in Methods

Each function entry includes the name of the function, its header file, syntax, return values, and parameter definitions.

[Top]

API Organization: Netscape and Plug-in Methods

Plug-in Method Summary

Netscape Method Summary

Plug-in API Methods: Functional Subgroups

Plug-in API methods are organized into two groups, according to whether they are called by Communicator or by the plug-in itself.

Plug-in methods are provided by the plug-in and called by Navigator. You implement these functions in the plug-in. The names of all plug-in functions begin with NPP_.

Netscape methods are provided by Navigator and called by the plug-in. These functions are implemented by Navigator. The names of all Netscape functions begin with NPN_.

In general, Plug-in API functions work the same way on all platforms. However, several functions, notably NPP_HandleEvent and NPN_MemFlush, operate differently depending on the platform. Platform-specific differences are described in the reference entries for the individual functions.

Unless otherwise stated, ownership for all API function parameters remains with the caller and values are valid only for the duration of each call. For example, if Netscape passes your plug-in a string, the plug-in should make its own copy of the string if you need to reference it after returning from that function. If you pass the Navigator a string or buffer, you are responsible for freeing the memory allocated for the data; the Navigator make its own private copy of the data if necessary.

Declarations for all API functions as well as definitions of all types and structures, error code values, used in the API functions are included in the file npapi.h.

This reference groups function reference entries according to their use in programming operations, as covered in Chapters 3 through 8. This overview gives you two ways to find a particular function.

Search by Plug-in API group in either Plug-in Method Summary or Netscape Method Summary.

Search by functional group within the API group through the lists in Plug-in API Methods: Functional Subgroups.

[Top] [Plug-in API Methods: Functional Subgroups]

Plug-in Method Summary

Method Name	Description
NPP_Destroy	Deletes a specific instance of a plug-in.
NPP_DestroyStream	Tells the plug-in that a stream is about to be closed or destroyed.
NPP_GetJavaClass	Returns the Java class associated with the plug-in.
NPP_GetValue	Allows Communicator to query the plug-in for information.
NPP_HandleEvent	Delivers a platform-specific window event to the instance.
NPP_Initialize	Provides global initialization for a plug-in.
NPP_New	Creates a new instance of a plug-in.
NPP_NewStream	Notifies a plug-in instance of a new data stream.
NPP_Print	Requests a platform-specific print operation for an embedded or full-screen plug-in.
NPP_SetValue	Sets information about the plug-in.
NPP_SetWindow	Tells the plug-in when a window is created, moved, sized, or destroyed.
NPP_Shutdown	Provides global deinitialization for a plug-in.
NPP_StreamAsFile	Provides a local file name for the data from a stream.
NPP_URLNotify	Notifies the instance of the completion of a URL request.
NPP_Write	Delivers data to a plug-in instance.
NPP_WriteReady	Determines maximum number of bytes that the plug-in can consume.

[Top] [Plug-in API Methods: Functional Subgroups]

Netscape Method Summary

Method Name	Description
NPN_DestroyStream	Closes and deletes a stream.
NPN_ForceRedraw	Forces a paint message for a windowless plug-in.
NPN_GetJavaEnv	Returns a pointer to the Java execution environment.
NPN_GetJavaPeer	Returns the Java object associated with the plug-in.
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; gets notification of the result.
NPN_GetValue	Allows the plug-in to query Communicator for information.
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_MemAlloc	Allocates memory from Communicator's memory space.
NPN_MemFlush	Requests that Communicator free a specified amount of memory.
NPN_MemFree	Deallocates a block of allocated memory.
NPN_NewStream	Requests the creation of a new data stream produced by the plug-in and consumed by Communicator.
NPN_PostURL	Posts data to a URL.
NPN_PostURLNotify	Posts data to a URL, and receives notification of the result.
NPN_ReloadPlugins	Reloads all plug-ins in the `Plugins` directory.
NPN_RequestRead	Requests a range of bytes for a seekable stream.
NPN_SetValue	Sets windowless plug-in as transparent or opaque.
NPN_Status	Displays a message on the status line of the browser window.
NPN_UserAgent	Returns Communicator's `user agent` field.
NPN_Version	Returns version information for the Plug-in API.
NPN_Write	Pushes data into a stream produced by the plug-in and consumed by Communicator.

[Top] [Plug-in API Methods: Functional Subgroups]

Plug-in API Methods: Functional Subgroups

The organization of Plug-in function definitions in this reference corresponds to their use in programming operations, as covered in Chapters 3 through 8. This section lists Plug-in API methods by functional subgroup.

Plug-in Methods: Functional Subgroups

Netscape Methods: Functional Subgroups

[Top]

Plug-in Methods: Functional Subgroups

Initialization and destruction

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] [Plug-in Methods: Functional Subgroups]

Drawing and events

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.

[Top] [Plug-in Methods: Functional Subgroups]

Working with URLs

Method Name	Description
NPP_URLNotify	Notifies the plug-in of the completion of a URL request.

[Top] [Plug-in Methods: Functional Subgroups]

Communicating with Java

Method Name	Description
NPP_GetJavaClass	Returns the Java class associated with the plug-in.

[Top] [Plug-in Methods: Functional Subgroups]

Receiving data streams

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.

[Top] [Plug-in Methods: Functional Subgroups]

Netscape Methods: Functional Subgroups

Drawing and events

Method Name	Description
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] [Netscape Methods: Functional Subgroups]

Working with URLs

Method Name Description

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] [Netscape Methods: Functional Subgroups]

Memory

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] [Netscape Methods: Functional Subgroups]

Method Name	Description
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.

Communicating with Java

Method Name	Description
NPN_GetJavaEnv	Returns a pointer to the Java execution environment.
NPN_GetJavaPeer	Returns the Java object associated with the plug-in.

[Top] [Netscape Methods: Functional Subgroups]

Sending data streams

Method Name	Description
NPP_DestroyStream	Tells the plug-in that a stream is about to be closed or destroyed.
NPN_NewStream	Requests the creation of a new data stream produced by the plug-in and consumed by Communicator.
NPP_Write	Delivers data to a plug-in instance.

[Top] [Netscape Methods: Functional Subgroups]

Receiving data streams

Method Name	Description
NPN_RequestRead	Requests a range of bytes from a seekable stream.

[Top] [Netscape Methods: Functional Subgroups]

Utility

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] [Netscape Methods: Functional Subgroups]

[Contents] [Previous] [Next] [Index]

Last Updated: 01/15/97 16:36:59

Chapter 9 Plug-in API Reference

Functions

API Organization: Netscape and Plug-in Methods

Plug-in Method Summary

Netscape Method Summary

Plug-in API Methods: Functional Subgroups

Plug-in Methods: Functional Subgroups

Initialization and destruction

Drawing and events

Working with URLs

Communicating with Java

Receiving data streams

Netscape Methods: Functional Subgroups

Drawing and events

Memory

Communicating with Java

Sending data streams

Receiving data streams

Utility

Chapter 9
Plug-in API Reference