GetFilterVersion - Initialization for an ISAPI filter.
#include "httpfilt.h" BOOL GetFilterVersion ( HTTP_FILTER_VERSION *pVer ) { /* do the job */ return TRUE; }
When the ISAPI runner loads a library for use as a filter, it calls the GetFilterVersion export of the library: if no such routine is available, or if GetFilterVersion returns FALSE, the runner rejects the library and does not try to use it as a runner.
An ISAPI filter may be run either `in-process' as part of the web server or `out of process' under the control of a separate ISAPI runner. See below for differences between the events notified to filters in the two cases. In the Zeus web server, a filter can discover which case applies by consulting the environment variable whose name is ``0'': a call to getenv("0") will return the string ``zeus.isapi'' when running out of process (in-process, it with either return NULL or return some string other than ``zeus.isapi'').
On Tru64 UNIX (because of complications in that OS's handling of shared libraries) GetFilterVersion must appear in the shared library which implements the filter - if the filter 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.
The one parameter, pVer, has fields for the version of ISAPI against which the filter was compiled
and for the version and name of the filter itself: GetFilterVersion should fill these in appropriately (see HTTP_FILTER_VERSION(5)
for details). It should also assign, to pVer->dwFlags, a (bit-field or) DWORD value constructed as a bit-wise `or' of SF_NOTIFY_
flags. These come in three groups: security port, event designator and
priority order.
Two bits of dwFlags are used to select among requests according as they come in on secure or insecure ports. Setting both bits selects all ports, regardless of security; selecting neither ignores all ports.
If this bit is unset, the filter will not be invoked for requests being handled on secure ports (i.e. those using SSL).
If this bit is unset, the filter will not be invoked for requests being handled on insecure ports.
These bits specify events in the processing of each request. The web server handles each request in a succession of stages: at each stage (or `notification event'), it will call filters which have set the corresponding bit in dwFlags. The order in which events' notification codes are given here is the usual order of event-processing: however, this is only for guidance - filters should not make assumptions about the order of events. Some requests will bypass some events, others may repeat events, take some events in a non-standard order or combine some or all of these variations.
Some notification events are only notified to filters running in-process: if an out-of-process filter selects a notification which is only supported in-process, the web server will reject it at start-up.
Invoked (in-process only) when the client's data are read. Since the client's data may be read in several chunks, this notification may be repeated later in proceedings.
Invoked only once per request, after all HTTP headers have been read (and processed by any SF_NOTIFY_READ_RAW_DATA filters).
Invoked when the server is converting the URL to a file-system path. This occurs at least once, after SF_NOTIFY_PREPROC_HEADERS, and may occur repeatedly thereafter.
Invoked just before an attempt at authenticating the client. Every client connection prompts this notification, as does any request which supplies authentication headers.
Invoked (in-process only) if a 401 response is sent to the client: this notification will generally be followed only by SF_NOTIFY_END_OF_REQUEST and SF_NOTIFY_END_OF_NET_SESSION (both also only in-process).
Invoked after request is processed, before reply headers are sent.
Invoked (in-process only, but possibly repeatedly) during transmission of the raw data. For (only) this notification, filters are handled in the reverse of priority order (see below).
Invoked (in-process only), for each request, at the end of processing.
Invoked (in-process only) after each HTTP request has completed but before the web server performs logging operations (if any).
Invoked (in-process only) when each client connection is closed. If Keep-Alive is active, many requests may have been handled by the connection.
Where several filters select a notification event, the filters are sorted into priority order (high priority first, low priority last - except, as noted above, that this order is reversed for SF_NOTIFY_SEND_RAW_DATA). When a request comes to the relevant stage in processing, it is passed to the first filter in this order: if the filter returns SF_STATUS_REQ_NEXT_NOTIFICATION (which is usual), the request will then be passed to the next filter in order (and so on); if a filter returns SF_STATUS_REQ_HANDLED_NOTIFICATION, the remaining filters for that notification will be skipped and the request will be moved on to its next stage of processing.
Note that order is unspecified among filters of equal priority: one should generally avoid having several filters of equal priority. Such ambiguity is, of course, harmless in so far the filters' actions are `orthogonal' or in so far as one can be sure that no request will be processed by more than one filter at each priority. Note, even in these cases, that each should return SF_STATUS_REQ_NEXT_NOTIFICATION, as there may be filters with lower priority.
Available priorities are (in their usual order - this is reversed for the SF_NOTIFY_SEND_RAW_DATA notification):
High priority filters process a request first.
Medium priority filters process a request next.
Low priority filters process a request last.
Return TRUE on success; FALSE otherwise.
isapi(7),
GetExtensionVersion(3),
HttpFilterProc(3),
TerminateFilter(3),
HTTP_FILTER_VERSION(5).
$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.