Chapter 2
Development Overview

This chapter is an introduction to the issues and processes that you will need to know about as you write plug-ins. It outlines the steps in writing and implementing a plug-in code module for Communicator.

For more information about particular processes described in this chapter, refer to Chapters 3 through 8.

• Writing Plug-ins
• Registering Plug-ins
• Drawing Plug-ins
• Handling Memory
• Sending and Receiving Streams
• Working with URLs
• Getting Version and UI Information
• Displaying Messages on the Status Line
• Communicating with Java
• Building Plug-ins
• Installing Plug-ins

Plan your plug-in. Decide on the services you want the plug-in to provide.

1. Decide on a MIME type and file extension for the plug-in. See "Registering Plug-ins."

2. Download and decompress the SDK. See "The Plug-in Software Development Kit."

3. Create the plug-in project. You can either start from the template provided for your operating system in the source directory, or construct a plug-in project in your development environment using SDK-provided files. You can use a variety of environments to create plug-ins.

4. Make the necessary changes and additions to the SDK files to provide plug-in functionality and implement Plug-in API methods for basic plug-in operation. You'll find an overview of using Plug-in API methods in this chapter. More information about each function is provided in Chapters 3 though 8 of this guide.

5. Build the plug-in for your operating system. See "Building Plug-ins."

6. Install the plug-in in the plug-in directory for your operating system. See "Installing Plug-ins."

7. Test your plug-in and debug as necessary.

8. Create an HTML page and embed the plug-in object. For information about the HTML tags to use, see "Using HTML to Display Plug-ins." To see your plug-in in action, simply display the HTML page that calls it in Communicator.

9. If you decide to use LiveConnect capabilities in your plug-in, your next step is to read LiveConnecting Plug-ins with Java. Look at the View Source article, "Netscape Client Plug-Ins," to see how the Plug-in API and LiveConnect fit together in a plug-in created with Microsoft Visual C++.

[Top] [Writing Plug-ins]

The server looks for the MIME type registered by a plug-in, based on the file extension, and starts sending the file to the browser. Communicator looks up the media type, and if it finds a plug-in registered to that type, loads the plug-in.

When it starts up, Communicator checks for plug-in modules in the plug-in directory for the platform and registers them. It determines which plug-ins are installed and which types they support through a combination of user preferences that are private to Communicator and the contents of the plug-ins directory. You can see this information by choosing About Plug-ins from the Help menu (Window and Unix) or "?" (Help) menu (Mac OS).

A MIME type is made up of a major type (such as application or image) and a minor type, for example, image/jpeg. If you define a new MIME type for a plug-in, you must register it with IETF (Internet Engineering Task Force). Until your new MIME type is registered, preface its name with "x-", for example, image/x-nwim. For more information about MIME types, see these MIME RFCs: RFC 1521: "MIME: Mechanisms for Specifying and Describing the Forms of Internet Message Bodies" and RFC 1590: "Media Type Registration Procedure."

• Mac OS
• MS Windows
• Unix

On the Mac OS platform, the Plug-ins folder is located in the same folder as the Communicator application. Plug-ins are identified by file type NSPL. When Communicator starts up, it searches subfolders of the Plug-ins folder for plug-ins and follows aliases to folders and NSPL files. Plug-in filenames must begin with NP.

The MIME types supported by a plug-in are determined by its resources. 'STR#' 128 should contain a list of MIME types and file extensions in alternating strings. For example:

str 128	MIME Type
String 1	video/quicktime
String 2	mov, moov
String 3	audio/aiff
String 4	aiff
String 5	image/jpeg
String 6	jpg

Several other optional strings may contain useful information about the plug-in. Plug-ins must support 'STR#' 128 but are not required to support any of these others:

• STR#' 127 can contain a list of MIME type descriptions corresponding to the types in 'STR#' 128. For example, this description list corresponds to the types in the previous example: String 1: "QuickTime Video", String 4: "AIFF Audio", and String 5: "JPEG Image Format."
• STR#' 126: String 1 can contain a descriptive message about the plug-in. This message, which is in HTML format, is displayed by Communicator in its "About Plug-ins" page. String 2 can contain the name of the plug-in, thus allowing the name the user sees to be different from the name of the file on disk.

The Windows version information for the plug-in DLL determines the MIME types, file extensions, file open template, plug-in name, and description. In the MIME types and file extensions strings, multiple types and extensions are separated by the "|" character, for example:

video/quicktime|audio/aiff|image/jpeg

• File Extents: for file extensions
• MIME Type: for MIME types
• Language: for language in use

[Top] [Registering Plug-ins]

To determine the MIME types of the plug-ins, Communicator loads each plug-in library and calls its required NPP_GetMIMEDescription entry point. NPP_GetMIMEDescription should return a string containing the type, extension list, and type description separated by semicolons; for example, image/xbm;xbm;X Bitmap.

Communicator also calls the plug-in's optional NPP_GetValue entry point to determine the plug-in name and description.

The calls to NPP_GetMIMEDescription and NPP_GetValue are made for registration purposes only. During registration, Communicator does not call any other plug-in entry points, and the plug-in cannot call any Communicator entry points at all.

[Top] [Registering Plug-ins]

A windowless plug-in can call the following Netscape methods to draw itself:

• NPN_ForceRedraw: Force a paint message for windowless plug-ins.
• NPN_InvalidateRect: Invalidate an area in a windowless plug-in before repainting or refreshing.
• NPN_InvalidateRegion: Invalidate an area in a windowless plug-in before repainting or refreshing.

• NPP_GetValue: Query the plug-in for information.
• NPP_Print: Request a platform-specific print operation for the instance.
• NPP_SetValue: Set Communicator information.
• NPP_SetWindow: Set the window in which a plug-in draws.
• NPP_HandleEvent: Deliver a platform-specific event to the instance.

• NPN_GetValue: Get Communicator information.
• NPN_SetValue: Set plug-in Communicator information.

[Top] [Drawing Plug-ins]

• Use the NPN_MemAlloc method to allocate memory from Netscape Communicator.
• Use the NPN_MemFree method to free memory allocated with NPN_MemAlloc.
• Use the NPN_MemFlush method to free memory (Mac OS only) before calling memory-intensive Mac Toolbox calls.

[Top] [Handling Memory]

Streams produced by Communicator can be automatically sent to the plug-in instance or requested by the plug-in. The plug-in can select one of these transmission modes:

• Normal mode: Communicator sends the stream data sequentially to the plug-in as the data becomes available.
• Random-access mode: Communicator allows the plug-in to request specific ranges of bytes from anywhere in the stream. This mode requires server support.
• File mode: Communicator saves the data to a local file in cache and passes that file path to the plug-in.

For information about using these methods, see Chapter 5, "Streams." For a reference entry that describes each function, see "Stream Methods" in the API reference.

[Top] [Sending and Receiving Streams]

• Use NPN_GetURL to request Communicator to load a URL into a particular Communicator window or frame for display, or to deliver the data of that URL to the plug-in instance in a new stream.
• The NPN_GetURLNotify function operates like NPN_GetURL, except that it notifies the plug-in of the result when the operation completes.
• Use NPN_PostURL to send data to a URL from a memory buffer or file. The result from the server can also be sent to a particular Communicator window or frame for display, or delivered to the plug-in instance in a new stream.
• The NPN_PostURLNotify function operates like NPN_PostURL, except that it notifies the plug-in of the result when the operation completes.

[Top] [Working with URLs]

• To identify the browser in which your plug-in is displayed: Use the NPN_UserAgent method to read this information.
• To determine whether plug-in and Communicator versions are compatible and possibly provide alternative processing for different versions: Use the NPN_Version method to check for changes in major and minor version numbers.

[Top] [Getting Version and UI Information]

For information about using this method, see Chapter 8, "Version, UI, and Status Information." For a reference entry, see "Utility Methods" in the API reference.

[Top] [Displaying Messages on the Status Line]

To take advantage of Java and JavaScript, a plug-in must interact with the Java object model. The plug-in must have an associated Java class and implement methods of that class in native code. For example, the sample plug-in Simple, which is included in the Plug-in SDK, has an associated Java class that is defined in the simple.java file (in Simple's source directory).

Methods of the plug-in's associated Java class can be called from other Java code or JavaScript. For example, a form letter on an HTML page could control plug-in operation by using JavaScript to call a native method of the plug-in's class.

To prepare your plug-in for LiveConnect communication with Java, you need three Plug-in API methods:

• NPP_GetJavaClass: Use this method to return the Java class associated with the plug-in.
• NPN_GetJavaEnv: Use this method to get the Java execution environment, needed for all calls from plug-in native calls to Java.
• NPN_GetJavaPeer: Call this method to get the Java object associated with the plug-in instance.

NOTE: LiveConnect is enabled by default in Netscape 3.0 and later versions. You can manually enable (or disable) LiveConnect by setting the preferences for enabling Java and JavaScript. To enable or disable LiveConnect, see the "Java" or "JavaScript" topic in Communicator NetHelp. §

• Building a Win32 Plug-in
• Building a Mac OS Plug-in

Download the MS Windows Plug-in SDK (WinNPSDK.zip) from the Netscape FTP download page.

1. Unzip WinNPSDK.zip using your favorite zip utility. If you would like to use the MSVC++ project files without modification, unzip this file directly into your C:\ directory. If you are using pkunzip, use the -d flag to maintain the directory structure of the zip file.

   After unzipping the file, you will have a directory called C:\PluginSDK.

2. Open the file C:\PluginSDK\Examples\Simple\Windows\NPSimple32.mdp.

3. From the Build menu, choose Build NPSimple32.dll.

4. Copy the resulting file NPSimple32.dll to the plugins directory in the same directory as netscape.exe. Usually this is C:\Program Files\Netscape\Navigator\Program\plugins.

5. Copy the Java class file C:\PluginSDK\Examples\Simple\Simple.class to the same plugins directory. This file specifies the JavaScript interface to the plug-in.

6. If Communicator is running, be sure to exit.

7. Launch Communicator, and browse the file C:\PluginsSDK\Examples\Simple\Testing\
SimpleExample.html.

NOTE: The Plug-in SDK comes in CodeWarrior 9/10 and CodeWarrior 11 versions. Be sure to download the SDK for the version you are using. §

Download the Mac OS Plug-in SDK (MacNPSDK.sit) from the Netscape FTP download page.

1. Unstuff the file with Stuffit Expander, or another unstuffing utility.

2. In the Examples/Simple/Macintosh folder, open the SimplePPC.&micro project file.

3. From the Project menu, choose Make.

4. Copy the Java class file Examples/Simple/Simple.class
   to the Communicator Plug-ins folder.

5. Copy the plug-in (or an alias) Examples/Simple/SimplePPC to the Communicator Plug-ins folder.

6. If Communicator is running, type javascript:navigator.plugins.refresh(true);
   at the Netsite box and press Return. This reloads all plug-ins in the Plug-ins folder without your needing to restart Communicator.

7. Browse to Examples/Simple/Testing/SimpleExample.html.

NOTE: The Simple example does not work with the 68K Mac OS. §

Communicator's JAR Installation Manager. Set up your plug-in so that this feature is triggered when the user displays an HTML page whose embedded data requires a plug-in that is not installed.

Manual installation. The user copies the plug-in to the appropriate directory by hand. Plug-ins can reside in the following directories:

• Mac OS: Plug-ins folder or folder targeted by plug-in alias in the Plug-ins folder
• MS Windows: plugins directory
• Unix: Set by the environment variable NPX_PLUGIN_PATH, which defaults to /usr/local/netscape/plugins, ~/.netscape/plugins
  
  The plug-ins directory is located in the same directory as the Communicator application.

[Top] [Installing Plug-ins]

For more information about using JavaScript, see the JavaScript Reference.

[Top] [Installing Plug-ins]

• installation from the User's Point of View
• Preparing Your Plug-in to Use JAR Installation Manager

[Top] [Installing Plug-ins]

• The user goes to a web page that requires a plug-in that is not installed.
• The Safe Download dialog box appears, and Communicator starts downloading a JAR (Java ARchive) file. The user can stop the downloading at any time by clicking the Cancel button.
• When the downloading is complete, one of two security dialog boxes appears, depending on whether the JAR file is signed or not. The user decides whether to click Install to complete the installation, or Cancel to terminate it.
• When the installation is complete, the page updates, displaying the plug-in.

NOTE: In Communicator 4.0, you do not need to quit and restart to make the newly installed plug-in available. §

• Write an installation script. Writing a JavaScript script gives you two advantages: your script is reusable on any platform, and you can track your software with Netscape's version registry.

NOTE: If you use an existing installer, you must write a JavaScript script that starts the installer. §

• Place your plug-in files and the installation script in a JAR file. If you decide to use the digital signature security feature, you also include digitally signed files.
• Make the JAR file available to users and web page writers at a URL.
• When invoking this plug-in from a web page, the page author should include the PLUGINURL attribute in the plug-in's EMBED tag. This attribute should point to the JAR archive to use for installation.

[Top] [Installing Plug-ins]

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