
WebSite API 1.1 SDK
Microsoft ISAPI Compatibility
Return to Overview
Rev 13-Apr-96
WebSite's API supports both native generator extensions and generators
written for the Microsoft Internet Server Application Programming
Interface (ISAPI). In ISAPI terminology, generators are called Internet
Server Applications (ISAs). They similar in concept to WSAPI generators,
dynamic link libraries that implement a server-side application. Unlike
WSAPI, ISAPI supports only load-on-demand generators. Most ISAs can be
run behind WebSite Pro with no modification.
Compatibility Specifics
WebSite Pro supports only ISAPI-ISAs. It does not support ISAPI filters. If
you need to implement a filter for WebSite Pro, use WSAPI.
Extension Control Block
When WebSite Pro calls the HttpExtensionProc() entry of the ISA, it
passes the address of the ECB for the current transaction. There are a
few things to note:
- The ConnID field contains the address of the WSAPI
Transaction Control Block (TCTX) for the current
request.
- WebSite Pro uses its internal content reading machinery to efficiently
read all of the content sent with the request into memory.
Therefore, the lpbData field will point to a memory block containing
the entire content sent. cbAvailable and cbTotalBytes
will always be equal. No ReadClient() loops are needed.
- The major and minor versions are 1 and 0 respectively, for ISAPI/1.0.
WriteClient() Function
WebSite Pro's implementation of WriteClient() is buffered.
For most ISAs, buffering will improve network throughput by minimizing
the number of packets transmitted for a given data volume, regardless of
the sizes of data chunks passed to WriteClient(). If the ISA
depends on unbuffered I/O to the net, it may not operate as expected.
ReadClient() Function
Since WebSite Pro reads all incoming content into memory before calling the
ISA, the ReadClient function does nothing. It always returns FALSE.
Enhanced GetServerVariable() Function
WebSite Pro's ISAPI compatibility mode provides the ISAPI-required
GetServerVariable() function, and all of the server variables
listed in the ISAPI documentation. WebSite Pro's implementation also provides
a number of additional server variables not supported by ISAPI. For the
complete list of server variables supproted by WebSite Pro's implementation
of see the documentation for the WSAPI
get_server_variable()
function.
ServerSupportFunction()
WebSite Pro's ISAPI compatibility mode supports the five server support
functions listed in the ISAPI/1.0 specification. If additional server
support functions are added, changing the specification, we will
implement them as quickly as possible. Most of the functions
that will be discovered by the ISAPI implementors have already been
implemented in WSAPI, so this shouldn't be difficult in most cases.
There are a few things to note about the ISAPI/1.0 support functions:
- the HSE_REQ_SEND_RESPONSE_HEADER callback is implemented
according to observation and testing with Microsoft-provided samples.
The documentation is incomplete.
- an ISA that returns the HSE_STATUS_PENDING status code will
cause the calling thread to be immediately suspended (put to sleep). The
ISA must have another active thread within it which calls the
HSE_REQ_DONE_WITH_SESSION callback to unblock the original
thread that started the ISA in the first place. Failure to do so will
cause the calling thread to remain active until WebSite Pro's transaction sanity
timer goes off.
Upgrading an ISA to use WSAPI
ISAPI is a simple interface, so most of an ISA's logic is normally
implemented within the ISA itself. In ISAs, many of the common
processing steps needed to implement generator applications are
supported by user written code or source code from libraries or sample
applications. In contrast, WSAPI exports over 40 functions that can be used
to replace user-written code with vendor-maintained and optimized code
contained within WebSite Pro itself.
A good example is form decoding. Under ISAPI, ISAs must implement
form decoding themselves. WebSite Pro's in-memory form decoder is optimized
for speed, and it is heavily used for all CGI applications. Therefore it
is mature code, and we support it. But there's more: with the
introduction of the new multipart/form-data encoding type,
the job of writing form decoding code has become much more complex.
Robust decoding of MIME multipart content structures is not a trivial
task. WebSite Pro's decoder hides the specifics of the encoding used for a
given form, giving the application a simple enumeration interface. By
removing the user-written code from your ISA and substituting the simple
function calls to WSAPI, your ISA automatically gains the ability to
process the new multipart form data encoding (which is required for
form-based file uploading).
Calling WSAPI Functions from an ISA
ISAs running under WebSite Pro's ISAPI compatibility mode can be
upgraded/simplified to use WSAPI support functions. The hConn
(connection ID) field in the ISAPI extension control block (ECB) passed
from WebSite contains the address of the WSAPI Transaction Context Block
(TCTX) associated with the current request. To call a WSAPI support function
from an ISA, simply cast the connection ID to a TCTX pointer
in any call that requires a TCTX pointer.
[email protected];