----------------------------------------------------------------------
Netscape Navigator Unix Plugin Architecture V 0.6
----------------------------------------------------------------------
dpSuresh <dp@netscape.com>
Fri Feb  9 17:43:44 PST 1996

This document describes the architecture of the unix plugins.
This would help developers write their own plugins and interface them
with netscape.

Intended Audience
----------------------------------------------------------------------
	- Plugin developers on unix platforms
This assumes that the developer is aware of when and why a plugin is
required.

Platforms currently supported
----------------------------------------------------------------------
	- SunOS 4.1.3 and above
	- Solaris 5.3
	- Solaris 5.4
	- IRIX 5.2 and above
	- OSF1 V2.0 alpha and above

Contents
----------------------------------------------------------------------
	- General architecture of Netscape Unix Plugins
	- How to write a plugin
	- Sample Text plugin
	- Do's and Dont's

General architecture of Netscape Unix Plugins
----------------------------------------------------------------------

----------------------------------------------------------------------
               |                         |
               |                         |
Netscape       |         Wrapper         |             Plugin Developer
Navigator      |         npunix.c        |             npshell.c
               |                         |
Talks with the | Implements function     |  Can ignore the existence of
the plugin via | tables as required      |  functions tables and call NPN_*()
wrapper code   | by the navigator's      |  functions to call the navigator
in npnix.c     | plugin interface and    |  and implement NPP_* functions
               | provides plugin         |  to hookup to the navigator.
               | developers with a       |
               | std. set of functions   |
               |                         |
               | WONT NEED TO EDIT THIS. | FILL UP functions in npshell.c
               | NEED TO COMPILER WITH   | and write many more...
               | THIS.                   |
----------------------------------------------------------------------

The plugin in the unix platform is implemented as a dynamically loadable
module (.so) The navigator searches for these dynamically loadable modules
in the list of directories as specified by the environment variable
NPX_PLUGIN_PATH. This variable can be set to a ':' separated list of
directories. The default path if this environment variable is not set
is "/usr/local/lib/netscape/plugins"

	NOTE: On SunOS4.1.3, if there are any non-loadable modules in
	      any of the directories specified by NPX_PLUGIN_PATH, then
	      the dlopen() library call exits rather than giving an error.
	      thus causing the navigator to terminate.

The navigator detect which MIME types are recognized by a plugin by calling
NPP_GetMIMEDescription() in npshell.c (via NP_GetMIMEDescription() in
npunix.c). From then on, whenever it detect data of the
particular MIME type, it loads the plugin and creates instances of the
corresponding plugin object. Before creating the first plugin instance
the navigator will call NPP_Initialize() in npshell.c (via NP_Initialize()
in npunix.c). Also after the last plugin instance has been destroyed,
the navigator will call NPP_Shutdown() in npshell.c (via NP_Shutdown()
in npunix.c)

How to write a plugin
----------------------------------------------------------------------
	1. Fill up all the neccessary functions in npshell.c
	   To hook up and talk with the navigator. Refer to
	   "The plugin API" for more information on these
	   functions.

	2. Add new functions/files as required by your plugin.
	   Use npapi.h for a description of data structures passed
	   between the navigator and the plugin code.

	3. Compile the plugin code with npunix.c, npshell.c into
	   a platform specific dynamically loadable module.

	4. Install the dynamically loadable in NPX_PLUGIN_PATH,
	   /usr/local/lib/netscape/plugins/ by default.

	5. Start the navigator. From now on, whenever the MIME type
	   of interest to the plugin is encountered, the navigator
	   will call the apropriate functions in the plugin.

Sample Text plugin
----------------------------------------------------------------------
As an example, here is a text plugin. This plugin is intended only to
demonstrate how plugin developers can write plugins. The text plugin
operates on MIME type and extension "text/plain;.txt"
So whenever the navigator gets data with mime type "text/plain"
(or) needs to display a file with the extension ".txt", it passes the
data over to the plugin code as discussed by the Plugin API. The text
plugin creates a scrolled window using motif and displays the data
it received in the window. All code that is specific to the text
plugin is ifdeffed TEXT_PLUGIN in npshell.c

How to run the sample test plugin
----------------------------------------------------------------------
	1. Compile the text plugin code to get a libtextplugin.so
	2. Make a directory say, $HOME/.netscape/plugins

		mkdir $HOME/.netscape/plugins

	3. Copy the libtextplugin.so to that directory

		cp libtextplugin.so $HOME/.netscape/plugins

	4. Set NPX_PLUGIN_PATH to that directory

	    for csh:
		setenv NPX_PLUGIN_PATH $HOME/.netscape/plugins
	    for ksh/sh:
		NPX_PLUGIN_PATH=$HOME/.netscape/plugins; export NPX_PLUGIN_PATH

	5. Invoke the netscape that is plugin enabled. In the location
	   field type in the file URL address of Test.html
	    e.g if Test.html was found in /home/dp/plugins/SDK/Test.html
		the URL to use would be
		file:/home/dp/plugins/SDK/Test.html

NOTE: If you give a http address and dont see the plugin;
	(a) See if the file Test1.txt is accessible using a http address
	(b) Check if the server returns "text/plain" as the mime type for
	    http access to Test1.txt
	    

Do's and Dont's
----------------------------------------------------------------------
	- INSTALL YOUR OWN EVENT HANDLERS FOR THE PLUGIN WINDOW TO
	  GET EVENTS.
	  Netscape Navigator uses Xt/Motif for its display. Plugins
	  can use them and install their own event handlers for their
	  window.

	- DONT USE WorkProcs IN Xt.
	  WorkProcs will not be called.

	- USE THE X RESOURCE NAME SPACE WITH CARE.
	  plugins and netscape share the same X resources space.
	  So be sure your plugin gets it resources separately.
	  The navigator resources do not follow a pattern although
	  we eventually will. Until then, chose unique names that
	  are not used by the navigator for its X resources for
	  X resources and names of widgets used by plugins.

	- TAKE CARE WHEN INSTALLING TIMERS TO GET IDLE CYCLES.
	  Plugins installing TIMERS to get idle cycles (e.g for doing
	  some animation as long as the plugin is in view) by using the
	  XtAppAddTimeOut() should take care to not install 0 interval
	  timer callbacks. If they do, then the network events will never
	  happen.
