NSNVBITF: A DLL to Provide NSAPI Support for Visual Basic

Version 0.2, 4 May 1995

This DLL provides access to all methods and properties of the Netscape.Network.1 OLE Automation Object which is described in the OLE Automation Object specification. It was written by Steve Caine (shc@cfg.com ) of Caine, Farber & Gordon, Inc. It is freely usable and redistrubutable as described below .

Table of Contents

Legal Stuff

The software described here, and its associated documentation, ("the software") has been placed in the public domain by Caine, Farber & Gordon, Inc. You may do anything you want with it. 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.

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
xvbapi.h      a header file with some vb api definitions

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. These is:

vbapi.lib

which 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.

The Access Functions

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. All function names begin with the NsNet prefix.

Functions to Control the Interface

Create the Netscape.Network.1 Automation Object

Sub NsNetCreate()

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

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 OptionMask.

The NSAPI Interface Functions

These are mostly just like the descriptions in the NSAPI spec.

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 NsNetSetUsername(Name as String)

Same as spec.

Last Modified: May 04, 1995