Netscape Plugin

$Revision: 5.0.2.3 $

The Allegro Common Lisp Netscape Plugin is a custom DLL built using the techniques described in Building and Using an Allegro Common Lisp Based DLL. The plugin works with Netscape 4.0. The plugin supports using the Windows API to place controls and graphics in the Netscape browser window.

The plugin is documented below. The source code files and building steps are also explained. If you have Visual C++, you may build the plugin yourself from scratch.

Sections

What is the Allegro Common Lisp Netscape Plugin?
A Security Warning
Creating an Allegro Common Lisp Netscape Plugin Application
Building the Allegro Common Lisp Netscape Plugin DLL
Building the Allegro Common Lisp Netscape Plugin DXL

What is the Allegro Common Lisp Netscape Plugin?

The Allegro Common Lisp Netscape Plugin supports executing Common Lisp code that is referenced in a web page's HTML source. After installing the plugin files in the Netscape Plugins directory, users may execute Lisp applications available on a remote network location. The Lisp application may create Windows controls and graphics in the Netscape browser window.

Below is an example. To execute it, you must first install Netscape 4.0 on your PC. Then, following the steps below, generate the files npacl.dll, and npacl.dxl. Copy these two files along with two other files from the Allegro CL installation directory lnkacl.dll and acl<version>.*pll (name varies depending on which Allegro CL version you have installed) into the Netscape plugins directory.  Note: you must restart Netscape after putting files in the plugins directory, since Netscape only looks at this directory when it starts.

Here is an example, called the Game of Life, which you can run after restarting Netscape with the new plugin installed.

A Security Warning

The Allegro Common Lisp Netscape Plugin can execute any Common Lisp function, including ones that may examine or change files on the Netscape client PC.

Creating an Allegro Common Lisp Netscape Plugin Application

Use the HTML embed command to embed a Lisp application in the HTML document of your choosing:

<embed src="<Allegro directory>/examples/plugin/life.cl" width="400" height="400" console="N">

The life.cl file contains the application source code. It resides in the same directory as the document containing the embed command. The custom console attribute supports creating a Lisp console window. If the console value is Y and it is the first time a Common Lisp plugin application is run during a Netscape session, a separate Lisp console window will be created. You can use the console window for debugging during application development.

Examine the life.cl file to learn how to develop a plugin application. There are two user package symbols in the plugin Lisp image that are important: user::*window* and user::*idle-function*.

The *window* symbol is bound to the Netscape browser window that the application may draw in or create controls in. If the plugin application binds the *idle-function* symbol to a function, then that function is invoked after all other initialization steps are completed. Typically, the *idle-function* function subclasses the *window* to let the application process Window events and messages, and then sets up the application.

The Game of Life code uses win: package Windows API functions, such as KillTimer(). It also uses some simple macros that make it easier to call some of the more complex Windows API functions. The define-wndproc macro is an example. Examine the simpwin.cl file for documentation about the define-wndproc macro and other useful macros you can use when developing your own plugin application.

The Game of Life application Lisp code is transmitted to the plugin via a Netscape stream. If the HTML document is on a different computer, this will involve a network connection. For more complex plugin applications, it may be desirable to minimize the amount of code Netscape transmits. To reduce code transmission, pre-compile your application code into fasl files, have users wishing to run your code place the fasl files in their Netscape Plugins directory, and then have the plugin application code load the fasl files. Note that the user's Netscape Plugins directory is assigned to the sys: logical pathname when the Lisp plugin is run.

Building the Allegro Common Lisp Netscape Plugin DLL

The files required to build the Allegro Common Lisp Netscape Plugin, in <Allegro directory>/examples/plugin/, are:

Information about the Netscape Plugin SDK is available via the Netscape About Plugins Help menu choice.

The npshell.cpp source code calls external functions InitializeLisp(), RemoteCommand(), and GetLispThread(), which are documented in Building and Using an Allegro Common Lisp Based DLL. In addition, the undocumented functions CreateStream(), WriteToStream(), and DestroyStream() are called. These functions are used to create pipe-like I/O functionality between the DLL C code and the plugin Lisp thread. Here is documentation for those routines:

int CreateStream( int *lisp_fd )

Parameters

lisp_fd

a pointer to an integer that will contain a file descriptor acting as the read end of the pipe.

Return Value

0 if the operation failed, otherwise a file descriptor acting as the "write" end of the pipe.

void WriteToStream( int fd, char *buf )

Parameters

fd	a file descriptor previously returned by a CreateStream() call
buf	a null terminated string to be written to the pipe

void DestroyStream( int fd )

Parameters

fd	a file descriptor previously returned by a CreateStream() call

Remarks

Frees the resources associated with the stream. There can be no more than 19 active streams.

Below are the steps required to build npacl.dll, at an MS-DOS command prompt, but you can use the already built version in the <Allegro directory>/examples/plugin directory.  You will need Microsoft Visual C++ 5.0 to execute the following commands.

cd <Allegro directory>\examples\plugin

rc /l 0x409 npacl.rc     // compiles the resource file

cl -nologo -c -Ic -D_AFXDLL -MD -W3 -G3 -DWIN32
 -D_MT -Zi -Od npshell.cpp -Fonpshell.obj

cl -nologo -c -Ic -D_AFXDLL -MD -W3 -G3 -DWIN32
 -D_MT -Zi -Od npwin.cpp -Fonpwin.obj

link -nologo -stack:16777216 /DEBUG:FULL /DEBUGTYPE:CV
 user32.lib gdi32.lib kernel32.lib comctl32.lib comdlg32.lib
 winmm.lib advapi32.lib msvcrt.lib shell32.lib wsock32.lib
 -dll -out:npacl.dll -def:npacl.def -map:acl.map npwin.obj
 npshell.obj npacl.res -machine:i386 -version:4.1
 -nod:libc.lib user32.lib gdi32.lib kernel32.lib
 comctl32.lib comdlg32.lib winmm.lib advapi32.lib msvcrt.lib
 shell32.lib wsock32.lib ..\..\lnkacl.lib -base:0x63850000

Note that the lnkacl.lib file is provided by Franz, in the Allegro directory.

Building the Allegro Common Lisp Netscape Plugin DXL

The np.cl file contains code that supports the Lisp side of the Netscape plugin.

The dist.cl file can be loaded into Allegro CL to generate a distribution directory nspi/ (under the Allegro CL installation directory). The contents of this directory can be copied to the Netscape Plugins directory. If you use dist.cl, you can skip the rest of the steps below.

Here are the steps required to build the npacl DXL:

(compile-file-if-needed "<Allegro directory>/examples/dll/lnk.cl")
(load "<Allegro directory>/examples/dll/lnk.fasl")
(require :winapi)
(require :winapi-dev)
(compile-file-if-needed "<Allegro directory>/examples/plugin/simpwin.cl")
(load "<Allegro directory>/examples/plugin/simpwin.fasl")
(compile-file-if-needed "<Allegro directory>/examples/plugin/np.cl")
(load "<Allegro directory>/examples/plugin/np.fasl")
(sys::resize-areas :old 512000 :verbose t :global-gc t :pack-areas nil)
(dumplisp :name "<Allegro directory>/examples/plugin/npacl.dxl")

The above commands should be entered into a non-IDE Allegro Common Lisp session.

Copyright (C) 1998-1999, Franz Inc., Berkeley, CA. All Rights Reserved.