

NSNVBITF: A DLL to Provide NSAPI Support for Visual Basic
=========================================================

Version 0.2, 4 May 1995

NOTICE: This software and its associated documentation ("the
software") was written by Steve Caine (shc@cfg.com) of
Caine, Farber & Gordon, Inc., 1010 East Union Street, Ste 205, Pasadena,
CA 91106 and is hereby placed in the public domain.  You may do
anything at all with the software. There are no restrictions.  The
software is provided AS IS and WITH ALL FAULTS.  Neither the author nor
Caine, Farber & Gordon, Inc. nor any other party assumes any
responsibility for the software or for any modification thereto.

Be sure to save your work often when developing and testing code that
uses this DLL. It interfaces directly with Visual Basic and Netscape
and any error is likely to crash your system in ways that will require
at least a reboot if not a full reset. It may trash files or do other
horrible things.

==============

INTRODUCTION
------------

This DLL is intended to support the Netscape.Network.1 OLE Automation
Object as described in "OLE Automation in Netscape" (03/22/95) by
Garrett Arch Blythe.  It has a few additional functions, such as those
to create and release the object and to supply options, but otherwise
it just supplies the defined interface functions.

Note that the DLL is specific to Visual Basic 3.0.  It accepts, and
returns, Visual Basic strings by reference.  If you decide to modify
the code, you should have an understanding of the "Control Development
Guide" in the "VB Professional Features Book 1".  In particular,
strings are passed as HLSTRs and returned as temporary HLSTRs.  It is
not necessary to know or understand this to use the DLL from VB, but
such knowledge and understanding are necessary if you plan to change
things much.

THE PACKAGE
-----------

The distribution consists of the following files:

	nsnvbitf.cpp	the source for the dll
	nsnvbitf.def	the def file
	nsnvbitf.mak	the make file

	nsnetdef.txt	a vb text file with the declares for all the dll
					entry points

The following two VB files are provided as a simple test and
illustration of using the DLL.  These are quick & dirty *in the
extreme*.  Do not take them as representing good VB programming
practice!  The files are:

	nsnet.mak	  	vb makefile for the test
	nsnet.frm		the form file for the test (text)

	
BUILDING THE DLL
----------------

The DLL was developed under Visual C++ V1.51.  It requires one file
that IS NOT distributed with the package due to licensing
considerations.  This is:

	vbapi.lib

and  may be found as part of the custom control development kit
which is part of VB 3.0.  The makefile assumes it has been copied to
the source directory.

After building the DLL, copy it to one of the standard DLL places.  For
example, you might put it in your windows\system directory if you will
have multiple applications using it or in your application's execution
directory if you have only one such application.

USING THE DLL
-------------

To use the DLL, you first create the automation object with
NsNetCreate.  You then use the various interface routines to support
your application.  Finally, you call NsNetRelease to release the
automation object.  Optionally, you can set a few options and trap
runtime errors.

IMPLEMENTATION NOTES
--------------------

While the MS C++ compiler was used to develop the DLL, it is really
just a C program.  The techniques used are based on those shown in the
drafts of Chapters 13 and 14 (old numbering) of "Inside OLE Second
Edition" which I don't think has been published, yet.  The drafts are
available on ftp.microsoft.com and on the WinObj CIS forum.

Each interface routine is pretty-much self-contained and sets up &
tears down its own VARIANTARG structures and calls Invoke directly.
Using helper functions would have made things a bit more compact, but
the current way seemed simplest at the time.

The most "dangerous" part of the implementation is the use of the
Visual Basic HLSTR data type for passing and returning strings.  I
*think* I'm doing things in the right order so that they won't move or
change size on me when I'm not expecting it, but only time -- and real
users! -- will tell.

RUNTIME ERRORS
--------------

The DLL handles runtime errors by passing them to the VB application
using VBRuntimeError.  The possible errors are shown below.  The error
number shown is actually added to the error number base (default 21000)
before being passed to VB.  You can change the base with the
NsNetSetErrorBase call if this conflicts with something else you are
using.  The errors are:

	1	A failure HRESULT was returned by one of the OLE functions.
		You may use the NsNetGetSCode function to retrieve the SCode
		that corresponds to the HRESULT.

	2	The system was unable to allocate a BSTR, probably do to lack
		of memory.

	3	You have attempted to use an interface function without first
		calling NsNetCreate (but see OPTIONS below).

Normally, any of these errors will stop your VB program.  To trap
errors, use the VB "ON ERROR" statement.  When your error handler gains
control, "err" will return the error number (with error base added to
it) and "error$" will return an error message.

OPTIONS
-------

A number of options can be set with the NsNetSetOptions call which is
passed a long containing option bits:

	0x00000001	Show hourglass cursor while creating the automation
				object, opening, and reading.

	0x00000002	After creating the automation object, warp the focus
	back to the active VB window.

	0x00000004	Automatically create the automation object the first
				time it is needed.

	0x00000008	Release the automation object before signaling an error
				to the application.

The default option bits are: 0x00000002.

ROUTINES TO CONTROL THE INTERFACE
---------------------------------

These routines control the operation of the DLL. The descriptions
below are given as if they were being declared as VB Subs or Functions.
See the NsNet.txt file for the actual Declare statements.

	Create the Netscape.Network.1 Automation Object
	-----------------------------------------------

		Sub NsNetCreate()

			The object will be created or, if not, an error will be
			signalled.

	Get the SCode From the Last Failed HRESULT
	------------------------------------------

		Function NsNetGetSCode() as Long

			You would normally call this after catching error 1 in
			order to determine what failed.

	Releasing the Automation Object
	-------------------------------

		Sub NsNetRelease()

			You should call this before exiting from your application.
			It is OK to call this even if the object has not been
			created.  In that case, it is a NOP.

	Setting a Different Error Base
	------------------------------

		Sub NsNetSetErrorBase(ErrorBase as Integer)

			ErrorBase becomes the number to which error numbers are
			added prior to signaling.  This is useful if you have other
			packages that also signal errors.

	Setting Options
	---------------

		Sub NsNetSetOptions(OptionMask as Long)

			See the OPTIONS section above for the possible contents of
			OptionsMask.

THE NSAPI INTERFACE ROUTINES
----------------------------

These are mostly just like the descriptions in the NSAPI spec.  The
names are the same but with a prefix of "NsNet".  The descriptions
below are given as if they were being declared as VB Subs or Functions.
See the NsNet.txt file for the actual Declare statements.

	Function NsNetBytesReady() as Integer

		Same as spec.

	Sub NsNetClose()

		Same as spec.

	Function NsNetGetContentEncoding() as String

		Same as spec.

	Function NsNetGetContentLength() as Long

		Same as spec.
		
	Function NsNetGetContentType() as String

		Same as spec.
		
	Function NsNetGetErrorMessage() as String

		Same as spec.
		
	Function NsNetGetExpires() as String

		Same as spec.
		
	Function NsNetGetFlagFancyFTP() as Integer

		Same as spec.

	Function NsNetGetFlagFancyNews() as Integer

		Same as spec.
		
	Function NsNetGetFlagShowAllNews() as Integer

		Same as spec.
	
	Function NsNetLastModified() as String

		Same as spec.

	Function NsNetGetPassword() as String

		Same as spec.

	Function NsNetGetServerStatus() as Integer

		Same as spec.

	Function NsNetGetStatus() as Long

		Same as spec.

	Function NsNetGetUsername() as String

		Same as spec.

	Function NsNetIsFinished() as Integer

		Same as spec.

	Function NsNetOpen(Url as String, Method as Integer, 
					   Postdata as String, Postdatasize as Long,
					   Postheaders as String) as Integer

		Same as spec.  Note that Postdata and Postheaders must be valid
		strings even if they are ignored for a given method.  The empty
		string ("") works fine for this.

	Function NsNetRead(Buffer as string, amount as Integer) as Integer

		Same as spec.  Note that Buffer is a regular VB string.  It
		need not be of any particular size when Read is called since
		the read data is put into a string of the proper size which is
		passed back as Buffer.

	Function NsNetResolve(Baseurl as String, Rel as String) as String

		Same as spec.

	Sub NsNetSetFlagFancyFTP(Flag as Integer)

		Same as spec.

	Sub NsNetSetFlagFancyNews(Flag as Integer)

		Same as spec.

	Sub NsNetSetFlagShowAllNews(Flag as Integer)

		Same as spec.

	Sub NsNetSetPasswords(Password as String)

		Same as spec.

	Sub NsNetSetUsernmae(Name as String)

		Same as spec.




