<B>nstplugin</B> -- embedding of NST circuits in Netscape

SYNOPSIS:

The NST plug-in extends the Netscape browser so that it can display HTML documents together with embedded windows from NST applications. The windows are fully interactive, so that "live documents" become possible. The embedded NST applications are instantiated from their *.NST circuit files specified with a SRC tag in the HTML document. They can be located in any URL, offering the possibility for distribution and executing NST applications over the Web. When a NST application has been loaded into Netscape, it can be "pushed" into a running instance of Neo, allowing to inspect and modify the underlying circuit further. Since NST circuits can implement a wide range of functions, the Neo/nstplugin combination can be viewed as a graphical environment for the rapid creation of a great variety of specialized Netscape plugins.

REQUIREMENTS ON AN NST CIRCUIT FOR DISPLAY IN A HTML PAGE:

To make a NST circuit suitable for display within a HTML page by the nstplugin, the circuit must fulfil the following three requirements: 1. When the circuit is instantiated, it must come up with a single NST graphics window. In the following, we will refer to this window as the main window of the circuit. It is this window that the nstplugin will embed into its display of the HTML page (the required HTML command is described below). 2. The main graphics window must be maintained througout the entire lifetime of the circuit, i.e., the circuit must not allow any commands that would close or remake its main window (such commands would crash the netscape session). 3. Any required data of the circuit must be included in its *.NST file (i.e., no separate *.nst data file can be used). If a circuit requires more than a single window, there are two possibilities (that can be combined). Either the main window is made as an input_window with a suitable number of named areas to accommodate all required further windows. Or the main window offers commands that open (and optionally close again) the required additional windows while the circuit is running. Such additional windows will then appear separately from the browser window. Unlike the main window, the additional, non-embedded windows are not restricted to native NST graphics windows, e.g., they may also be windows created with the tcl_prog unit. However, such windows will not share their event loop with the netscape browser. As a result, the browser controls will `freeze'' until any non-NST windows have become closed again.

CONTROL FLOW:

If the embedded circuit contains no provisions for any interactive input, it just will be executed repeatedly while the mouse pointer is in the area of the embedded main window or in any of the auxiliary windows that may have opened during operation of the circuit. After the mouse pointer has left the embedded window, the current execution step will be completed, then control will be given back to the Netscape browser (therefore, a single execution step of the circuit should only take a short time to avoid noticeable latency). The same applies when a circuit contains one or several mouse units or if the main window is an input_window with further widgets for control of named units etc. In this case, the control of the circuit via its main window will be the same as if it were not embedded, with the exception that only mouse actions inside the main window or any subsequently opened auxiliary windows will be effective. I.e., when the mouse pointer returns back into the Netscape window, the operation of the NST event loop will be suspended (after the current "round" of callbacks has been completed) until the mouse pointer returns back into one of the NST windows. The recommended way is to use a single input_window with an %R button to establish a continous loop over the remaining widgets to which then actions of named NST units ("callback units") can be bound.

HTML COMMANDS FOR EMBEDDING A CIRCUIT:

To embed a circuit stored as a file circuitfile.NST in a HTML page requires an embed statement of the following form


   <EMBED SRC=circuitfile.NST WIDTH=300 HEIGHT=200>

(the example assumes that a rectangular area of 300x200 pixels is sufficient to accomodate the main window of the to-be-embedded circuit). As usual, circuitfile.NST is relative to the file of the HTML document where the EMBED statement occurs (a suffix NST.gz is allowed to indicate gzip'ed data). Instead of a file name the specification of the circuit file can also be a general URL. This allows to fetch NST circuits from a remote site. Note, however, that in this case the required folder libraries for the fetched circuit must still be available locally (cf. below). Several NST circuits can be embedded in the same or on several simultaneously viewed HTML pages. In this case, control will always pass to the circuit in whose window the cursor is. When a page with a NST circuit was left (entirely, not only with the cursor) and is revisited later, the circuit will become re-instantiated, i.e., any former state information is lost (but see below).

MANAGING OF FOLDERS:

A file neofolders placed in one of the directories


   "." "$(HOME)/.nstplugin" or "$(HOME)"

(searched in that order) determines which NST folders will be loaded into the NST plugin when it is initialized (the format is the same as for the usual neofolders file). Since Netscape completely unloads a plugin when the last viewed instance is left and must reload and re-initialize the plugin after such an event (which happens already when switching from a page with a single instance to a new page, even if this contains another instance, unless at least one further window with an instance in it is open) it is adviseable to keep the number of entries in the neofolders file small to avoid unnecessary overhead. Instead, loading of folders should be largely relied on the specifications in the loaded circuit files themselves (however, if a shared library cannot be found or is not specified, the instance will not appear on the page). This is also the reason why the directory .nstplugin is provided to allow the specification of a different (smaller) neofolders startup file.

TRANSFERRING LOADED CIRCUITS INTO NEO:

A loaded circuit can be transferred into a running instance of Neo for closer investigation. To this end, Neo must have been started with the special command


    neo -i :netscape

(no other name for the executable will work). The transfer of a loaded circuit can then be triggered from Netscape by pressing the F4-function key when the mouse cursor is in the rectangle of the embedded circuit (it may be necessary to move the pointer a little while the F4 key is down). The transfer will use a named pipe (fifo) :netscape located in the directory $(HOME)/.nstplugin (the same directory where the .nstfolders file for the nstplugin is located; the fifo will be created by Neo when started in the above way. If, however, the nstplugin directory does not exist, or if no Neo is up or has not been started in the above specified way, the transfer will not happen. If everything is ok, Netscape will block until the circuit has been fully instantiated in Neo (instantiation starts only after the mouse pointer has been moved into one of Neo's windows). If something goes wrong during this process, it helps to explicitly remove the fifo :netscape in the $(HOME)/.nstplugin directory. The instantiated circuit will be a new instance in Neo that has been initialized with the current data from Netscape (for private files, this offers a way to save the state of an instance when leaving its page: Neo can overwrite its SRC file with the loaded copy. When later returning to the page, it will then load the saved copy). The transferred instance can be run fully independently from the Netscape process. The only difference is that neo started in -i :netscape mode will have its autoexec feature disabled (i.e, execution of a circuit cannot be triggered by the mere entering of a window with the cursor) and Neo will not automatically call any named _init units in this mode. This means that any circuits received from Netscape must always be actively started.

FETCHING OF REMOTE CIRCUITS AND PORTABILITY:

If a remote document with embedded NST circuits is loaded, the remote NST circuits will be fetched and instantiated, PROVIDED that the NST versions match and that the required libraries are available locally. In particular, circuits that are only composed of units from the "standard" compiled folders stdr, misc and scrn will always be remotely portable. (this includes already a wide range of possibilities, since the prog_unit is a member of stdr; but note also that #imported prog_unit loadlibs may spoil remote portability). However, if a circuit accesses data files, their file names are currently just transported `verbatim''. This will make it generally impossible for a fetched circuit to access the file contents except for the (unlikely!) event that the calling site offers a suitable mirror set of files.

SAFETY ISSUES:

Since NST circuits can write files, the automatic start of any embedded NST circuit when visiting a new HTML page poses a safety risk. Therefore, the set of URLs from which embedded NST circuits are allowed to run must be explicitly specified in a file named trusted_urls and located the ~/.nstplugin directory. Each line in this file specifies an URL for which the plugin is allowed to run its NST circuit. Entire sets of URL names can be specified with the usual Unix file globbing wildcards (which, however, here CANNOT BE ESCAPED with a backslash). For instance, an entry "file:*" (the apostrophes are not part of the entry) lets all local circuits be accepted, while remote ones still require the presence of more specific entries. Very safety-concerned users might also wish to write-protect the trusted_urls file for the owner, so that the plugin cannot modify it. Even if you entirely disable the safety-checking mechanism by specifying a single '*' in your trusted_urls file you still must have created the trusted_urls file itself, indicating that you have actively taken some decision about the level of safety that you desire. Those embedded NST circuits that the safety check has prevented from being loaded will just appear as empty boxes with a corresponding message. In this case, you still can inspect (and run!) the corresponding circuit by using the F4 function key to push it into a running neo instance, as explained before. As an additional convenience, each name of a visited `untrusted'' URL that was a NST circuit is appended to a file untrusted_urls in the ~/.nstplugin directory to make it easy to extend the trusted_urls file with visited URLs (however, any changes to the trusted_urls file will take effect only when the nstplugin is newly loaded).

INSTALLATION AND REQUIRED LIBRARIES:

The nstplugin is implemented as a shared library nstplugin.so that must be placed in the Netscape plugin directory (Netscape finds this directory by looking at the value of the $NPX_PLUGIN_PATH environment variable). The plugin requires for its operation the two shared NST libraries libnst.so and libnstld.so (in $LD_LIBRARY_PATH). Additionally, it requires all those shared libraries that implement any NST folders that are referenced by to-be-embedded circuits. Such folder libraries should be placed in $NST_LD_LIBRARY_PATH (if this is not defined, $LD_LIBRARY_PATH will be searched instead).

FILES:

.nstplugin.so: the plugin itself, to be placed in Netscape's plugin directory

.nstplugin: a home directory that is specific for the nstplugin and that contains various auxiliary files

.neofolders: (in .nstplugin home directory) NST folders loaded with the nstplugin

trusted_urls: (in .nstplugin home directory) list of URLs that the plugin is allowed to load and start as NST circuits.

untrusted_urls: (in .nstplugin home directory) list of encountered URLS that were NST circuit files but could not be instantiated because they had no entry in file trusted_urls

:netscape: (in .nstplugin home directory) named pipe for communication with Neo (will be created automatically, when needed). Should be removed when Netscape blocks during transmission of a circuit to Neo.

libnst.so
libnstld.so: (in $NST_LD_LIBRARY_PATH or $LD_LIBRARY_PATH) shared libraries required by the plugin (alternatively, you can also create a `fat'' plugin binary in which the above libraries are compiled in).

BUGS:

The requirement of a single graphics window that is maintained through the lifetime of the circuit is not automatically enforced. Printing/Saveing a page will leave the areas that belong to embedded NST circuits blank (this is the fault of a netscape print interface that is for UNIX only scantly documented, with important documented features not conforming to reality).

TECHNICAL NOTES:

Any attempts to send output to stdout or stderr will be captured by the Netscape browser and will appear in a window that pops up. The embedding mechanism relies on a pair of longjmps into and out from NST routines together with explicit saving and restoring of stack memory. This requires that the nstplugin is compiled in non-optimizing mode. It also assumes a downward growing stack frame (otherwise two routines must be re-implemented for "upward logic"). The plugin is very picky about ref counts of shared libraries: any self-implemented objects that dlopen shared libraries must ensure that the ref counts end up at 0 when the last instance of the object is deleted.

FILE

/homes/jontrup/nst5/man/../o.sol2//../pluginsrc/nstplugin.c