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

Chapter 3
Initialization and Destruction

This chapter describes the methods that provide the basic processes of initialization, instance creation and destruction, and shutdown.

This chapter ends with Initialize and Shutdown Example, which includes the NPP_Initialize and NPN_Shutdown methods.

For a reference entry that describes each function discussed in this chapter, see "Initialization and Destruction Methods" in the API reference.

[Top]

Initialization

 Communicator calls NPP_Initialize once when a plug-in is loaded, before the first instance is created. Use this function to allocate the memory and resources shared by all instances of your plug-in.

NPError NPP_Initialize(void){
   };
After the last plug-in instance is deleted, Communicator calls NPP_Shutdown, which releases the memory or resources allocated by NPP_Initialize. For an example that shows the use of both the NPP_Initialize and NPN_Shutdown methods, see "Initialize and Shutdown Example."

During initialization, when Communicator encounters data of a MIME type registered for a plug-in (either embedded in an HTML page or in a separate file), it loads the plug-in code into memory (if it hasn't been loaded already) and creates a new instance of the plug-in. For more information, see "Registering Plug-ins."

Plug-ins are native code libraries: .DLL files on Windows, .SO or .DSO files on Unix, and PowerPC Shared Library files or 68K code resources on Mac OS. To reduce memory overhead, plug-ins are usually loaded only when needed and released as soon as possible.

In the initialization process, Communicator passes the plug-in two tables of function pointers for all API calls:

The function tables also contain version information that the plug-in checks to verify that it is compatible with the API capabilities provided by the application. To check this information, use NPN_Version.

No plug-in API calls can take place in either direction until the initialization completes successfully, with the exception of the functions NPP_Initialize and NPP_Shutdown, which are not in the function tables. However, because NPP_Initialize is called at the end of the initialization process, you can call other methods, such as such as NPP_MemAlloc and NPP_Status, from NPP_Initialize.

[Top] [Initialization]

Instance Creation

 After initialization, the plug-in instance is created. More than one instance of the same plug-in can exist if a single page contains multiple embedded plug-ins, or if several Communicator windows are open and display the same data type. At this point, a plug-in can call the NPN_SetValue function to specify whether it is windowed (the default) or windowless.

Plug-in instance are created with NPP_New and destroyed with NPP_Destroy. NPP_New informs the plug-in of the creation of a new instance with the specified MIME type. You can allocate instance-specific private data at this time.

NPError NPP_New(NPMIMEType pluginType,
                NPP instance, uint16 mode,
                int16 argc, char *argn[],
                char *argv[], NPSavedData *saved);
The pluginType parameter represents the MIME type of this instance of the plug-in. You can assign more than one MIME type to a plug-in, which could potentially allow the plug-in to respond to data streams of different types with different interfaces and behavior.

The instance parameter represents an NPP object, created by Communicator. You can store the instance-specific private data in its pdata field (instance->pdata).

The mode parameter identifies the display mode in which the plug-in was invoked, either NP_EMBED or NP_FULL.

The next three parameters pass parameters from the EMBED or OBJECT tag that called the plug-in. The argc parameter is the number of HTML arguments in the tag. It determines the number of attributes in the arrays specified by the argn and argv parameters.

The arguments in the EMBED tag are name-value pairs made up of the attribute name (for example, ALIGN) and its value (for example, top). The argn array contains the attribute names; the argv array contains the attribute values.

Communicator ignores any nonstandard attributes in an EMBED tag, so the web page author can use the arg parameters to specify private attributes defined for a particular plug-in. For example, the following EMBED tag has the standard attributes SRC, HEIGHT, and WIDTH and the private attribute LOOP: 

<EMBED SRC="movie.avi" HEIGHT=100 WIDTH=100 LOOP=TRUE>
With the EMBED tag in the example, Communicator passes the values in argv to the plug-in instance:

argc = 4
argn = { "SRC", "HEIGHT", "WIDTH", "LOOP" }
argv = { "movie.avi", "100", "100", "TRUE" }
The saved parameter allows an instance of a plug-in to save its data and, when the instance is destroyed, pass the data to the next instance of the plug-in at the same URL. The data is saved in the History list. As long as the plug-in still appears in this list, that saved data is associated with the page; any new instances receive this data.

[Top] [Instance Creation]

Instance Destruction

 Plug-in instances are created with NPP_New and destroyed with NPP_Destroy. Communicator calls NPP_Destroy when a plug-in instance is deleted, usually because the user has left the page containing the instance, closed the window, or quit the application. If this is the last instance created by a plug-in, NPP_Shutdown is called.

You should not perform any graphics operations in NPP_Destroy because the instance window is no longer guaranteed to be valid. Also, be sure to delete any private instance-specific information stored in the plug-in's instance->pdata.

NPError NPP_Destroy(NPP instance, NPSavedData **save);
The instance parameter represents the plug-in instance to delete.

The plug-in can use the optional save parameter to save data for reuse by a new instance with the same URL. The data is passed to NPP_New through its saved parameter. For example, a video player could save the last frame number to be displayed. When the user returns to the page, the previous frame number is passed to the new instance of the plug-in, so it can initially display the same frame.

Note that you cannot count on data being saved this way; the data may be lost if Communicator restarts or purges memory. Ownership of the buf field of the NPSavedData structure passes from the plug-in to Communicator when NPP_Destroy returns.

The example in this section sets up a buffer and allocates memory for it. You can use this type of buffer to handle data saved from one instance of a plug-in to another. The example shows the use of the optional save parameter of NPP_Destroy and saved parameter of NPP_New.

To ensure that Communicator does not crash or leak memory when the saved data is discarded, the buf field should be a flat structure (a simple structure with no allocated substructures) allocated with NPN_MemAlloc, as in this example: 

char* myData = "Here is some saved data.\n";
int32 myLength = strlen(myData) + 1;
*save = (NPSavedData*) NPN_MemAlloc(sizeof(NPSavedData));
(*save)->len = myLength;
(*save)->buf = (void*) NPN_MemAlloc(myLength);
strcpy((*save)->buf, myData);
If you allocate saved instance data in NPP_Destroy, be sure to allocate memory with this function, since Communicator can delete the saved data with the equivalent of NPN_MemAlloc at any time.

[Top] [Instance Destruction]

Shutdown

 When the application no longer needs the plug-in, it is shut down and released. NPP_Shutdown gives you an opportunity to delete data allocated in NPP_Initialize to be shared by all instances of a plug-in. Communicator calls the plug-in's NPP_Shutdown function, which informs the plug-in that its library is about to be unloaded, and gives it a chance to cancel any outstanding I/O requests, delete threads it created, free any memory it allocated, and perform any other closing tasks.

The NPP_Shutdown function releases memory or resources shared across all instances of a plug-in. It is called once after the last instance of the plug-in is destroyed, before releasing the plug-in library itself.

void NPP_Shutdown(void);
For an example that shows both the NPP_Initialize and NPN_Shutdown methods, see "Initialize and Shutdown Example."

WARNING: Library unloading for plug-ins: If a plug-in uses LiveConnect plug-ins on pages connected through LiveConnect, the plug-in's actual library may not be unloaded until Java garbage collection time, 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. §
[Top]

Initialize and Shutdown Example

 This example demonstrates the use of the NPP_Initialize and NPP_Shutdown methods.

/* Define global variable to hold the user agent string. */
static char* userAgent = NULL;
/* Initialize function. */
NPError NPP_Initialize(void)
{
    /* Get the user agent from Communicator. */
    char* result = NPN_UserAgent();
    if (result == NULL) return NPERR_OUT_OF_MEMORY_ERROR;
 
    /* Allocate some memory so that you can keep a copy of it. */
    userAgent = (char*) NPN_MemAlloc(strlen(result) + 1);
    if (userAgent == NULL) return NPERR_OUT_OF_MEMORY_ERROR;
 
    /* Copy the string to your memory. */
    strcpy(userAgent, result);
    return NPERR_NO_ERROR;
}
 
/* Shutdown function */
NPError NPP_Shutdown(void)
{
    /* Delete the memory you allocated. */
    if (userAgent != NULL)
        NPN_MemFree(userAgent);
    return NPERR_NO_ERROR;
}
 [Top]
[Contents] [Previous] [Next] [Index]

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

Copyright © 1997 Netscape Communications Corporation