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

Memory Methods

NPN_MemAlloc 
 
NPN_MemFlush 
 
NPN_MemFree 

Three methods, from the Netscape group of Plug-in API methods, handle memory in plug-ins. See Chapter 7, "Memory," for information about using these methods.  [Top] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPN_MemAlloc

New functionality in Communicator 4.x

Allocates memory from Communicator's memory space

Plug-in API Type
Implemented by Navigator. See Netscape Method Summary.
Syntax
#include <npapi.h>
void *NPN_MemAlloc (uint32 size);
Parameters
The function has the following parameters: 
size
 Size of memory, in bytes, to allocate in Communicator's memory space.
Returns
Description
The plug-in calls NPN_MemAlloc to allocate a specified amount of memory in Communicator's memory space. If you allocate saved instance data with NPP_Destroy, be sure to use NPN_MemAlloc to allocate memory. This ensures that Communicator can free the saved data at a later time with the equivalent of NPN_MemFree.

Since Communicator and plug-ins share the same memory space, NPN_MemAlloc allows plug-ins to take advantage of any customized memory allocation scheme the application may have, and allows the application to manage its memory more flexibly and efficiently.

Mac OS
NPN_MemAlloc is particularly important on Mac OS, since the Mac OS version of Communicator frequently fills its memory partition with cached data that is only purged as necessary. Since NPN_MemAlloc automatically frees cached information if necessary to fulfill the request, calls to NPN_MemAlloc may succeed where direct calls to NewPtr fail. § 
Mac OS
New in Communicator 4.x: With Communicator 4.x on Mac OS, NPN_MemAlloc performs memory flushing internally. Existing calls to NPN_MemFlush have no effect. You only need to use NPN_MemFlush in situations where you cannot use NPN_MemAlloc, for example, when calling system methods that allocate memory indirectly. § 
See Also
NPN_MemFlush, NPN_MemFree
"Allocating and Freeing Memory"

[Top] [Memory Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPN_MemFlush

Implemented only on Mac OS.

Requests that Communicator free a specified amount of memory

Plug-in API Type
Implemented by Navigator. See Netscape Method Summary.
Syntax
#include <npapi.h>
uint32 NPN_MemFlush(uint32 size);
Parameters
The function has the following parameters: 
size
 Size of memory, in bytes, to free in the Communicator's memory space.
Returns
Description
The plug-in calls NPN_MemFlush when it is not possible to call NPN_MemAlloc, for example, when calling system APIs that indirectly allocate memory. To request that Communicator free as much memory as possible, call NPN_MemFlush repeatedly until it returns 0.

On Mac OS, you can use this method to free memory before calling memory-intensive Mac Toolbox calls.

In general, plug-ins should use NPN_MemAlloc to allocate memory in Communicator's memory space, since this function automatically frees cached data if necessary to fulfill the request.

With Communicator 4.x on Mac OS, NPN_MemFlush is not necessary for the Mac OS platform. NPN_MemAlloc now performs memory flushing internally. Existing calls to NPN_MemFlush have no effect.

See Also
NPN_MemFlush, NPN_MemFree
"Flushing Memory (Mac OS only)"

[Top] [Memory Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPN_MemFree

Deallocates a block of allocated memory
Plug-in API Type
Implemented by Navigator. See Netscape Method Summary.
Syntax
#include <npapi.h>
void NPN_MemFree (void* ptr);
Parameters
The function has the following parameters: 
ptr
 Block of memory previously allocated using NPN_MemAlloc.
Description
NPN_MemFree deallocates a block of memory that was allocated using NPN_MemAlloc only. NPN_MemFree does not free memory allocated by any other means.
See Also
NPN_MemAlloc, NPN_MemFlush
"Allocating and Freeing Memory"

[Top] [Memory Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

Utility Methods

  
NPN_ReloadPlugins
 
NPN_UserAgent
 
NPN_Status
 
NPN_Version

Netscape Communicator provides a variety of services to the plug-in through the Netscape method group. The functions in this section provide status line messages to the user, help identify the browser and the version of the Plug-in API that is currently in use, and reload plug-ins without restarting Communicator.

See Chapter 8, "Version, UI, and Status Information," for information about using these methods.

[Top] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPN_ReloadPlugins

New in Netscape Communicator 4.0. Not supported.

Reloads all plug-ins in the Plugins directory

Plug-in API Type
Implemented by Navigator. See Netscape Method Summary.
Syntax
#include <npapi.h>
void NPN_ReloadPlugins(NPBool reloadPages);
Parameters
The function has the following parameter: 
reloadPages
 Whether to reload pages. Values: 
  • true: Reload pages. 
  • false: Do not reload pages.
Description
NPN_ReloadPlugins reads the Plugins directory for the current platform and reinstalls all of the plug-ins it finds there.

Communicator knows about all installed plug-ins at start-up. If you add or remove any plug-ins, Communicator does not see them until you restart it. NPN_ReloadPlugins allows you to install a new plug-in and load it, or to remove a plug-in, without having to restart Communicator. You could use this function as part of the plug-in's SmartUpdate process.

See Also
NPN_Version
[Top] [Utility Methods] [Plug-in API Methods: Functional Subgroups] [API Organization: Netscape and Plug-in Methods]

NPN_Status

Displays a message on the status line of the browser window
Plug-in API Type
Implemented by Navigator. See Netscape Method Summary.
Syntax
#include <npapi.h>
void NPN_Status(NPP instance, const char* message);
Parameters
The function has the following parameters: 
instance
 Pointer to the current plug-in instance. 
message
 Pointer the buffer that contains the status message string to display.
Description
You can use this function to make your plug-in user interface simulate Communicator's behavior. When the user moves the cursor over a link in a browser window, Communicator displays information about it in the status message area (on the lower edge of the browser window). If your plug-in has a button or other object that acts as a link when clicked, you can call NPN_Status to display a description or URL when the user moves the cursor over it.

Communicator always displays the last status line message it receives, regardless of the message source. Your message is always displayed, but you have no control over how long it stays in the status line before another message replaces it.

See Also
NPN_UserAgent, NPP
"Displaying a Status Line Message"

[Top] [Utility Methods] [Plug-in API Methods: Functional Subgroups] [API Organization: Netscape and Plug-in Methods]

NPN_UserAgent

Returns Communicator's user agent field
Plug-in API Type
Implemented by Navigator. See Netscape Method Summary.
Syntax
#include <npapi.h>
const char* NPN_UserAgent(NPP instance);
Parameters
The function has the following parameter: 
instance
 Pointer to the current plug-in instance.
Returns
A pointer to a buffer that contains the user agent field of Communicator.
Description
The user agent is the part of the HTTP header that identifies the browser during transfers. You can use this information to verify that the expected browser is in use, or you can use it in combination with NPN_Version to supply different code for different versions of Netscape browsers.
See Also
NPN_Status, NPN_Version
"Getting Agent Information"

[Top] [Utility Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPN_Version

Returns version information for the Plug-in API

Plug-in API Type
Implemented by Navigator. See Netscape Method Summary.
Syntax
#include <npapi.h>
void NPN_Version(int*  plugin_major,
                 int*  plugin_minor,
                 int*  netscape_major,
                 int*  netscape_minor);
Parameters
The function has the following parameters: 
plugin_major
 Pointer to a plug-in's major version number; changes with major code release number. 
plugin_minor
 Pointer to a plug-in's minor version number; changes with point release number. 
netscape_major
 Pointer to Netscape Communicator major version; changes with major code release number. 
netscape_minor
 Pointer to Netscape Communicator version; changes with point release number.
Description
The values of the major and minor version numbers of the Plug-in API are determined when the plug-in and Communicator are compiled. For example, Plug-in API version 4.03 has a major version number of 4 and a point release number of 3. This function gets the values from the plug-in rather than from Communicator.
This function returns this value:  In this parameter: 
Plug-in major version number  
plugin_major 
Plug-in point release number  
plugin_minor 
Communicator major version number  
netscape_major 
Communicator point release number  
netscape_minor 
 
A plug-in can use this function to check that the version of the Plug-in API it is using is compatible with the version in use by Communicator. This could be part of the initialization process. For more information and an example, see "Getting the Current Version."

You can use NPN_Version to inquire on version constants (NPVERS constants), which represent particular Communicator features. Once the plug-in obtains a version number, it can inquire on a version constant to find out if the feature it represents exists in this version. For example, the plug-in could inquire on the constant NPVERS_HAS_WINDOWLESS to see if it is running in a version of Communicator that supports windowless functionality. For more information and an example, see "Finding Out if a Feature Exists." For a listing of version constants defined in the Plug-in API, see "Version Feature Constants."

NOTE: Platform-specific code in the Plug-in API files npwin.cpp, npmac.cpp, or npunix.c checks version numbers automatically. A plug-in whose major version is less than the major version of Communicator is not loaded. §
See Also
NPN_UserAgent, NPP_Initialize
"Getting the Current Version," "Finding Out if a Feature Exists," "Version Feature Constants"

[Top] [Utility Methods] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

Methods for Communicating with Java

  
NPP_GetJavaClass
 
NPN_GetJavaPeer
 
NPN_GetJavaEnv

Communicating with Java and JavaScript offers many advantages to the plug-in, including improved handling of sound, graphics, and video and using Java and JavaScript controls. By using a Netscape LiveConnect connection (new with Communicator 3.0), a plug-in can communicate directly with Java and, through Java, with JavaScript. These Netscape and Plug-in methods associate the Java class and environment with the plug-in.

For an introduction to these methods, see "Communicating with Java." For a discussion of all the issues involved in creating LiveConnected plug-ins, see LiveConnecting Plug-ins with Java.

[Top] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPP_GetJavaClass

New in Netscape Navigator 3.0.

Returns the Java class associated with the plug-in

Plug-in API Type
Implemented by plug-in. See Plug-in Method Summary.
Syntax
#include <npapi.h>
jref NPP_GetJavaClass(void);
Returns
Description
NPP_GetJavaClass gets the Java class associated with a plug-in.

If you want a plug-in to communicate with Java and, through Java, with JavaScript, you must define a Java class for it. This class allows Java to call plug-in methods. Depending on the purpose of the plug-in, you can use Java's Plugin (the default plug-in class), or subclass from Plugin.

Call NPP_GetJavaClass during plug-in initialization to find the plug-in's associated Java class. If the plug-in does not have one, it should return null. Otherwise, use the javah-generated "use_" function to both initialize your class and return it. If the plug-in class can't be found, "use_" sends an error that is displayed to the user.

This method is used only to allow the plug-in to communicate with Java, for example, when using LiveConnect, and is not necessary for basic Plug-in API support. For more information and instructions, read about calling plug-in native methods from Java in LiveConnecting Plug-ins with Java.

See Also
NPN_GetJavaEnv, NPN_GetJavaPeer
LiveConnecting Plug-ins with Java.

[Top] [Methods for Communicating with Java] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPN_GetJavaEnv

New in Netscape Navigator 3.0.

Returns a pointer to the Java execution environment

Plug-in API Type
Implemented by Navigator. See Netscape Method Summary.
Syntax
#include <npapi.h>
JRIEnv* NPN_GetJavaEnv(void);
Returns
Description
NPN_GetJavaEnv returns a handle to the Java execution environment.

In order to invoke Java methods from native code, the plug-in must pass its Java execution environment in any JRI calls it makes. The environment is a handle on the Java interpreter; it serves both as a dispatching mechanism to call JRI operations and an encapsulation of the current Java execution thread. The first time you call NPN_GetJavaEnv, allow time as the interpreter may have to initialize itself.

This method is used only to allow the plug-in to communicate with Java, for example, when using LiveConnect, and is not necessary for basic Plug-in API support. For more information and instructions, read about accessing Java methods from plug-ins  in LiveConnecting Plug-ins with Java.

See Also
NPP_GetJavaClass, NPN_GetJavaPeer
LiveConnecting Plug-ins with Java

[Top] [Methods for Communicating with Java] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

NPN_GetJavaPeer

New in Netscape Navigator 3.0.

Returns the Java object associated with the plug-in instance

Plug-in API Type
Implemented by Navigator. See Netscape Method Summary.
Syntax
#include <npapi.h>
jref NPN_GetJavaPeer(NPP instance);
Parameters
The function has the following parameters: 
instance
 Pointer to the current plug-in instance.
Returns
Description
NPN_GetJavaPeer returns the peer field of the Java Plugin object associated with a plug-in. The peer field helps in associating the instance and its Java object by providing access to the instance (the NPP object that represents the plug-in). You can use this method at any time to get access to the plug-in's Java class.

Before using NPN_GetJavaPeer, you must provide a Java class for the plug-in and implement NPN_GetJavaClass to return that class.

The Java object is created only when NPN_GetJavaPeer is called for the first time. This way, you do not start the Java interpreter unless you need the plug-in. However, JavaScript may call this method in order to talk to a plug-in on a web page.

This method is used only to allow the plug-in to communicate with Java, for example, when using LiveConnect, and is not necessary for basic Plug-in API support. For more information and instructions, read about calling plug-in methods from Java  in LiveConnecting Plug-ins with Java.

See Also
NPP_GetJavaClass, NPN_GetJavaEnv
LiveConnecting Plug-ins with Java

[Top] [Methods for Communicating with Java] [Reference to Functions by Functional Group] [API Organization: Netscape and Plug-in Methods]

[Contents] [Previous] [Next] [Index]
Last Updated: 01/15/97 16:37:49  
Copyright © 1997 Netscape Communications Corporation