Tcl Browser Plugin Design

This page attempts to describe how the Tcl web browser plugin is designed, mostly from the C level and to some extent the Tcl level.

The C lifecycle of a typical single plugin instance: I use NP_* as per the NPAPI, but NPP_* is how it is mapped to the actual functions in the Tcl browser plugin sources

NP_Initialize: Called when the plugin is first requested to exist in the browser. The actual instance request is not until NP_New, but we need to make sure the environment is "ready", and complain otherwise. Note: In Firefox (as of 1.5), all plugin instances will be created in the same thread, even across multiple FF toplevels. However, IE runs each toplevel browser window in a separate thread. It is possible that NP_Initialize and NP_Shutdown are called from separate threads.

NP_New: Called when an actual plugin instance is requested. Multiple instances can exist per page, and/or across toplevel browser windows. With IE, toplevel browser windows will be separate threads.

NP_SetWindow: Called with the parameters that let us know where to put our Tk window. It can be called multiple times with changing geometry or other configuration information for the same instance window.

NP_NewStream: Called when we have a data input stream.

NP_Write: Called when data is coming in (written to the plugin).

NP_DestroyStream: Paired with NP_NewStream, called when a data input stream has ended.

NP_Destroy: Paired with NP_New, called when a plugin instance is being destroyed.

NP_Shutdown: Paired with NP_Initialize, called when the plugin should be fully shutdown. Note: This may be called from a separate thread than NP_Initialize.

The installation structure of the plugin:

 +--- /path/to/browserdir/plugins/
   +--- (lib)nptcl<ver>.(so|dll)
   +--- nptcl/
     +--- tclplugin.(so|dll) # a [stardll], may also use regular Tcl installation
     +--- basekit(.exe)      # optional, used by default on unix
     +--- plugin<ver>
       +--- config/
       +--- safetcl/
       +--- utils/
       +--- installed.cfg

Mozilla Gecko NPAPI reference: [L1 ]

XPInstall documentation for creating XPIs (plugin delivery): [L2 ]

Old Netscape docs for NPAPI: [L3 ]