FILENAME:	np3_103.ZIP

CATEGORY:	Development tool

DESCR:		Development tool to create Netscape plug-ins easily
                (Netscape Navigator version 2.0 or greater,
		 Internet Explorer 3.02, 4.0 compatible) (all 32-bit
		 versions)

VERSION:	1.03

TARGET:		Delphi 3.0 (3.01) (compatible with 2.0, 4.0x by source code)

AUTHOR:		(C) Andrei N. Kashin, 1997 - 1999

URL:		
		Email: Andrei.Kashin@pobox.spbu.ru


STATUS:		FREEWARE


		You can use the tool on your own risk. I am not responsible
		for any damage or loss caused by the use of the tool.
		(it's usual "as is" statement). Anyway, I'll appreciate your
                donations (in any form: bug-reports, suggestions, ideas, etc.)

------------------------------------------------------------------------
FILES IN NP3_103.ZIP

Files are placed into different directories (folders) in the archive by their
category. To extract files from ZIP archive use WinZip or '-d' option of pkunzip.exe
utility.

\reg -    Directory contains main unit npapi.dcu and files needed for registering
          tool's component TNetscapeStream. 
	
  	NPAPI.DCU	The main unit. Includes Netscape Plug-In
                	API, implementation of TPluginForm,
			TNetscapeStream	and other procedures to
			interact with Netscape Navigator.

   	NPAPI.INT     	Contains interface to NPAPI.dcu with
                	comments.
                	Contains most of Netscape plugin API
			definitions. It's my free donation for
			all Delphi developers who intend to develop
			their own plug-in implementations based on
			the API.

  	MSTREAM.PAS     Registration unit to install TNetscapeStream
  	MSTREAM.DCR	Icon picture for TNetscapeStream component


\base - Directory contains basic Netscape plugin project as a base for
        other plugin projects. It should be placed into Delphi's Repository
	for easier using.
        
	NPBASE.DPR		The basic project to create plugin DLLs.
	NPBASE.DOF		Project options file for NPBASE.DPR

        MFORM.PAS		Unit containing a start form to modify.
        MFORM.DFM

        TEST.HTM		HTML file to browse by Netscape Navigator.

	TEST.XXX		Dummy files needed for TEST.HTM
	TEST1.XXX


\demo - Directory contains enhanced demo project

        NPDEMO1.DPR		Enhanced demo project. It shows how to use
	MFORM1.PAS		the tool. It is a simple polygon viewer
	MFORM1.DFM		with adjustable color (through 'embed' tag
	DEMOFIG.HTM		parameters or by means of scrollbars).
	NP_DEMO.RES
	FIG1.XCV		
	FIG2.XCV

\src - Directory contains the source of the tool's main unit npapi.dcu

	NPAPI.PAS		Source file.


README.TXT - This file.

---------------------------------------------------------------------------------


---------------------------------------------------------------------------------

INSTALLATION

Unzip the archive into a new directory. It's recommended to make a backup
copy of the archive.

Install component TNetscapeStream using registration unit mstream.pas from
"reg" subdirectory. You can freely modify this unit to put the component into
a component page you prefer. By default it's placed into 'System' component
palette page.

Put file npapi.dcu into LIB directory of Delphi Compiler.

Add project npbase.dpr from "base" subdirectory to Object repository. It will be
starting point to create your own plugins. Choose "Project|Add to repository"
option from menu and fill dialog form fields as you like. It's preferable
to put the project onto 'Projects' page of Object repository and
name it "Netscape plugin".

-----------------------------------------------------------------------------

USING

To start your own plugin project choose File|New... option from menu
and choose plugin project you have added to the repository.

To create your own plugin you need to define its MIMEType and FileExtents
properties. You can modify these values in VersionInfo page of
"Project Options" dialog. See "Important notes" later in this file
for more information about it.

You have to correct value of SearchPath field of "Directories/Conditionals"
if your Delphi installation differs from default ("C:\Program Files\Borland\
Delphi 3")

Add and modify controls on main form as you like. You can copy and paste
controls from other forms already created.

To check newly created plugin compile the project and put the resulting
DLL into PLUGIN directory of Netscape Navigator, start Netscape
Navigator and select Help|About Plug-Ins option from menu. You'll see
a table of installed plug-ins. Check out that your DLL is installed. 
After that browse the file test.htm (also presented in the archive).
You'll see two of your forms embedded into HTML-page.
(You have to modify "type" parameter of "embed" tags in test.htm
each time after changing MIMEType of your plugin).

You can use a powerful feature of Delphi 3 to debug your DLL while
it is running. Choose "Run|Parameters... option" from menu and
select Netscape Navigator as a host application for your DLL.
To avoid moving of your plugin DLL into PLUGIN directory
of Netscape Navigator each time after compilation you can
select this directory as "Output directory" in "Directories/
Conditionals" page of "Project options" dialog.

Use npdemo1.dpr project from "demo" subdirectory (all functionality is in
MFORM1.PAS unit) as an example to create enhanced plugins. You can adopt your
already existing forms to use as an plugin by simple replacing
TForm -> TPluginForm in their inheritance clause.

-----------------------------------------------------------------------------

LIMITATIONS

Because embedded objects in Netscape Navigator are child windows (non popup
and non MDI child) the only type of the form you can use is one with FormStyle 
fsNormal, without border icons, caption and menu bar, BorderStyle must be
bsNone or bsSingle only.

Because a several instances of plugin object can exist at the same time the
form you modify must be non autocreated. It will be created by means of the
tool in proper time automatically. For the same reason, do not put private
data for each form instance into global variables. Don't close the form
yourself.

The tool doesn't cover all possibilities of Netscape plugins at the moment.
Nevertheless it contains all functionality usually needed.

Technical documentation about Netscape PlugIns you can obtain from Netscape
developer site at:
http://developer.netscape.com/library/documentation/plugin.html

You don't need to read all documentation but only Plugin Basics chapter,
espessially parts about using "embed" and "object" tag. You have to know these
facts anyway as a plugin developer.


Special notes about Borland VCL (Visual Component Library):
It concerns only Delphi 3.0 (not 3.01 Maintenace Release) users.
In 3.01 these problems are fixed.

VCL is not threadsafe. It means, that VCL based DLLs become unstable
in multythread host applications when VCL code is executed in other
thread than VCL knows. It's impossible to fix the problem easily
because VCL is thread sensitive in the kernel. It's the same problem
as for ActiveX controls and forms.

I'm very sorry but it's the only cause that my tool has serious
limitations for IE plugin development. Unlike Netscape, IE runs
new thread of execution for each browsing window.

I've found how to fix the most unpleasant bug (which gives permanent
lock-ups for my tool).

You should have VCL sources to do it.
In graphics.pas insert commented line of code into FreeMemoryContexts
procedure. It must look as follows:

procedure FreeMemoryContexts;
var
  I: Integer;
begin
  with BitmapCanvasList.LockList do
  begin
    for I := Count-1 downto 0 do
    with TBitmapCanvas(Items[I]) do
      if TryLock then
      try
        FreeContext;
      finally
        Unlock;
      end;
  end;
  BitmapCanvasList.UnlockList; //  to unlock the list locked by LockList
end;

Then rebuild VCL library and use this updated version.
You can use then ConfirmThreadSafe procedure from npapi.dcu unit to
disable thread checking in plugin instance initialization.

I didn't include fixed 'graphics.dcu' into my tool in accordance with
Borland's deploy requirements (see deploy.txt in Delphi 3 directory).
You have to fix the problem yourself. :-(


----------------------------------------------------------------------------

TNetscapeStream

This is a non visual component to simplify the using of Netscape's streams.
To get data from URL stated in SRC parameter of EMBED tag you have to use this
component. It is bilt into NPAPI.DCU and support a limited subset of Netscape's
streams functions to read data from URL.

It supports two types of Netscape streams: 
(see npapi.int for references)

1) stNORMAL 

  You'll get notifications onRead to read next portion of data as they ready.
  In case of successful transfer completion you'll get notification event
  onCloseStream with Reason code NPRES_DONE; in case of user pressed Stop
  button or network error you'll get Reason code NPRES_USER_BREAK and
  NPRES_NETWORK_ERR accordingly.

2) stAsFile

  You'll get notification onAsFile when a local copy of URL will be created or
  notification onCloseStream with corresponding reason code in case of failure.

You can use read only property URL to know out the URL from which you are
receiving data.

 
The special message NM_NewStream will be sent to a form when a new stream is
to be created. You can ignore this message or use TNetscapeStream to handle
the stream (how to use it you can find out from an example in mform.pas).

-----------------------------------------------------------------------------

Important notes:

1) file name of Netscape plugin must begin with 'np' ( for example, npdemo.dll,
   npmview.dll, npxxxxx.dll). Therefore, name your plugin projects according
   with this rule.

2) plugin is DLL, not a program. Therefore, it is controlled by Netscape
   Communicator according with options found in HTML page containig "embed"
   tag. 

3) each plugin must have unique MIMEType to distinguish from other plugins.
   MIMEType corresponds 'type' parameter of 'emded' or 'object' HTML tag.
   It's the most important. In addition plugin should contain information about
   file extentions it supports and their short descriptions. Short desciptions
   are used in file open dialog and must look like "Windows bitmap (*.bmp)".
   It's possible to define several MIME-Types and corresponding file extensions
   for each MIME-Type but the tool supports only one MIME-Type and file
   extension at the moment. This serious limitation will be removed in the
   future.

4) The information about MIMEType, file extensions and their short descriptions
   stored in FileVersion resource part of DLL. In addition to standard entries
   for this resource type, Netscape plugin has 3 new entries:
   MIMEType, FileExtents and FileOpenName.

   You can found how to assign values to these parameters from following
   example:
  
   MIMEType:     application/demo
   FileExtents:  dem
   FileOpenName: Demo data (*.dem)

   You can easily modify these values from Project Options dialog, VersionInfo
   page. I've added these entries to basic plugin project options already.
   Do not uncheck "Include version information in project" checkbox and do not
   check "Default" checkbox. Do not change Language Local ID (it must be $0409
   English United States).  It's needed for succesful plugin installation.
   You can change other version info entries according your private data.

5) The tool can support only windowed plugins. Therefore, do not use 'hidden'
   option  of 'embed' or 'object' HTML tag.

6) You have to edit values for 'width' and 'height' parameters of 'embed' tag
   manually  to represent your form in suitable size.

7) Because both creating and destroying of plugin instances are under Netscape
   Communicator's control you should'n call Close, Free or Destroy procedures
   for the  form you use as a plugin. It will be done automatically.

---------------------------------------------------------------------------------------

Technical support


Send E-mail with your questions and etc. by address:

Andrei.Kashin@pobox.spbu.ru


Any suggestions, comments and bug reports are most welcome.


Thank you.

