ISAPI - web server application programming interface
ISAPI is an open API by which shared libraries may extend the functionality of a web server. It is supported by Microsoft's IIS and the Zeus Web Server. To enable ISAPI in ZWS, one should configure the mod_isapi module for the web site.
These manual pages describe the Zeus Web Server ISAPI implementation: this closely follows the published Microsoft specification, however some details are implemented by use of idioms more appropriate to Unix. In particular, where Microsoft's implementation calls for use of the Win32 GetLastError function, the ZWS implementation uses the ANSI C errno variable to communicate errors.
ISAPI provides for extension of the web server via shared libraries exporting appropriate functions for use by the ISAPI runner. Such libraries come in two kinds; extensions and filters. The present manual refers to such libraries as `handlers' when discussing features common to both kinds; the present page of the manual provides context for the more detailed accounts provided by other pages (see SEE ALSO, below). For each kind of handler, the interface to the library is specified in terms of three exported routines: an initialization routine (Get*Version), a processing routine (Http*Proc) and an optional termination routine (Terminate* - the * in each case being Filter or Extension).
On Tru64 UNIX (because of complications in that OS's handling of shared libraries) the interface functions of an ISAPI handler must appear in the shared library which implements the handler - if the handler depends on further shared libraries, it can only use these to provide the tools needed by its interfaces; it cannot delegate, to them, provision of the ISAPI interface functions themselves.
When the web server is asked for a URL which its URL-to-resource mappings identify as being served by a given ISAPI extension, the web server loads the appropriate library and invokes its initialization routine: this routine is called exactly once and serves to communicate version information between the extension and the ISAPI runner. Likewise, when the web server is shut down or when it determines that it no longer needs the extension loaded, it calls the termination routine (if present) before unloading. In between, an extension serves web pages in a role similar to that of a CGI script (but more flexible and efficient).
For contrast, the web server loads all ISAPI filters when it starts up, and keeps them loaded until it shuts down. As for extensions, the initialization routine is called exactly once and communicates version information; a filter's initialization also declares which stages, in the handling of client requests, it intends to handle. If the filter provides a TerminateFilter, this will be called before the library is unloaded when the web server shuts down.
A filter can intervene in the processing of client requests at various stages: at the point where a client connects (distinguishing secure and non-secure cases); after the web server has read the client's request; after it has parsed the headers; after it has authenticated the client; after access has been denied (if it is); after the URL has been mapped to a local file-system filename; before the raw reply is sent; at the stage where logging is performed; and when the client disconnects. A given filter may be called, for a given client request, at several stages.
The actual handling of client requests is performed by the processing routine, Http*Proc. For an extension, this is called once for each client request depending on the extension; the HttpExtensionProc takes just one argument, a pointer to a data structure (the extension control block) describing the request being handled. For a filter, the argument list includes a similar pointer (to the filter context) along with an indication of the stage of processing and a pointer to further data specific to that stage of processing. In general, the filter context or extension control block serves as the primary control structure for a handler's interaction with a request.
This control structure depends on whether the handler is a filter or an
extension; however, in both cases, the control structure includes some
functions which enable the Http*Proc to perform tasks necessary to its
role. This manual documents these function as if they were library
functions (e.g. GetServerVariable(3)).
The functions provided by the control structure take, as first argument, a `connection identifier'. For filters, the connection identifier to use is the pointer, to the filter context, which was passed in as the first argument to HttpFilterProc. For extensions, the connection identifier to use is provided as the ConnID field of the extension control block passed to HttpExtensionProc.
GetExtensionVersion(3),
GetFilterVersion(3),
HttpExtensionProc(3),
HttpFilterProc(3),
TerminateExtension(3),
EXTENSION_CONTROL_BLOCK(5),
HTTP_FILTER_CONTEXT(5).
$ZEUSHOME/web/include/httpext.h $ZEUSHOME/web/include/httpfilt.h $ZEUSHOME/web/include/wintypes.h $ZEUSHOME/webadmin/docroot/docs/modules/isapi/*.html
Copyright (C) 2000-2001 Zeus Technology Limited. All rights reserved.