ISAPIFLT

Description:
Load and execute an ISAPI (Internet Server API) filter DLL. You can find more informations about ISAPI filters in the MSDN library. This handler will load the configured ISAPI filter DLL when the server is started. If you want to load more than one ISAPI filter you must use one ISAPIFLT handler for each filter DLL. During a HTTP request the handler will dispatch the registered ISAPI filter notifications to the filter DLL.

Options:

Overview

Option	Default	Values	Short Description	Example(s)
Condition	-	A Pi3Expression	If condition is TRUE, filter is responsible for the request	Condition "®exp('/admin/',$z)"
FilterDLLPath	+	A valid file path	The path to an ISAPI filter DLL	FilterDLLPath "C:\Pi3Web\Isapi\daf.dll"
Terminators	-	Init, Headers, Hostmap, Mapping, CheckPath, CheckAuth, CheckAccess, CheckType, Handle, Log, Destroy	Phases, that are terminated by this handler	Terminators Headers \| Mapping \| Log
SystemLogon	Yes	Yes\|No	Indicates if the server should attempt a system logon	Terminators Headers \| Mapping \| Log
Variable	-	<Pi3Expression>	A variable definition	Variable "GATEWAY_INTERFACE=CGI/1.1"
ExtraHeaders	Yes	Yes\|No	Indicates if extra headers are considered	ExtraHeaders Yes
ExtraHeadersPrefix	-	<A string>	Used as prefix of each extra header	ExtraHeadersPrefix "HTTP_"
ExtraHeadersIgnore	-	<Space delimited Strings>	List of unconsidered extra headers	ExtraHeadersIgnore "Content-Type Content-Length"

- in the default indicates no default
+ in the default indicates the field is mandatory

Description of Options

Condition

If the condition given by the Pi3Expression is TRUE, the filter controlled by this handler is responsible for the request. The filter will get all notifications registered with GetFilterVersion during startup. This gives the ISAPI filter handlers more flexibility and a superior control mechanism as replacement for the IIS filter priority chain.

FilterDLLPath

The DLL given by this option will be loaded during server startup and controlled by the handler during HTTP requests. Only ISAPI filter DLLs are allowed here. If the DLL is not an ISAPI filter or the filter version is not compliant or the filter uses an unsupported notification type the DLL will not be loaded and the server start will be aborted with an error message.

Terminators

Pi3Web server needs exactly one handler to complete one HTTP request phase. For efficiency the following handlers will not be called if a phase is completed. From this it follows sometimes we have to change the default termination of a phase (i.e. Mapping ) to give ISAPI filters a chance to be called by the main dispatcher. Sometimes we have to complete a phase by an ISAPI filter (i.e. a Log filter). If the filter DLL returns "SF_STATUS_REQ_HANDLED_NOTIFICATION", PIAPI_COMPLETE will be returned automatically by the handler. Otherwise we can use this option to explicite complete a phase if the filter is called. All phase names are allowed here separated by "|".

SystemLogon

If this parameter is switched off and the returned status by the filter is SF_STATUS_REQ_HANDLED_NOTIFICATION, this is treated as successful authentication. If this parameter is switched on and the returned status by the filter is SF_STATUS_REQ_HANDLED_NOTIFICATION, the Pi3Web will attempt a system logon.

Variable

Specifies a server variable expression to be set into the buffer of ISAPI extension calls to GetServerVariable. Could be set multiple times in one configuration object.

ExtraHeaders

This configuration key defines, if extra headers are considered by the processing of this handler.

ExtraHeadersPrefix

This configuration value will be the trailing string of each extra request header.

ExtraHeadersIgnore

The headers in this list are not treated as extra headers.

Phase:
All Phases

Returns:
PIAPI_COMPLETED, PIAPI_CONTINUE, PIAPI_ERROR, or INT_REDIRECT according to the status returned by the filter.

Notes:

General

The ISAPI filter handler is an experimental plug in. Since the IIS and Pi3Web has different architectures it is difficult to be 100% compliant.

Parameters

The Pi3Expressions in the configuration variables may contain besides the standard shortcuts used in Pi3Expressions the following, context specific parameters.

Parameter	Evaluates to
%a	All extra headers, as required for header ALL_HTTP
%l	Content-Length as DWORD, as required for ISAPI

Filter version

The version of the filter DLL is checked against the server ISAPI version (2.1). If the version isn't compliant the filter isn't loaded and the server start will abort with an error message.

Filter notifications

All filter notification events are supported except of SF_NOTIFY_READ_RAW_DATA and SF_NOTIFY_SEND_RAW_DATA events. If the filter try to register these events, the filter will not be loaded and the server start will abort with an error message.

Notification order

Filter priority is not supported with Pi3Web. If you chain ISAPI filters with other handlers the order is fixed in Config.Pi3 in the "Handlers" section of the HTTPLogicObject. To much filters with lots of notifications will noticeable slow down the server.

Phase completion

An architecture sign of Pi3Web is, that one handler must finish a connection phase by returning PIAPI_COMPLETED. If the filter DLL will return "SF_STATUS_REQ_HANDLED_NOTIFICATION" after handling a notification, the handler will return PIAPI_COMPLETED and the phase is finished. If the filter does not, then you can force this with the handler option "Terminators".

ServerSupportFunction

The following support functions are not supported:

SF_REQ_SET_NEXT_READ_SIZE

SF_REQ_GET_CONNID

Server variables

A pre-defined set of IIS server variables are supported. "ALL_HTTP" will hold all request headers except of the values stored in other server variables. This is very flexible by adding, changing or removing "Variable" parameters from the configuration file.

Authentication filters

If an authentication filter returns SF_STATUS_REQ_HANDLED_NOTIFICATION on notification SF_NOTIFY_AUTHENTICATION, the server will attempt to logon and impersonate the user at the system dependent on setting "SystemLogon".

This works only on Windows NT/2000/XP and requires permissions to "act as part of the operating system" for the user running the Pi3Web (except XP). Otherwise the HTTP statuscode 401 and appropriate response headers to force a basic authentication are set by the Pi3Web.

Example:

	<Object>
		Name DAFFLT
		Class ISAPIFLTClass
		Condition "®exp('*/admin/*',$z)"
		FilterDLLPath "C:\Pi3Web\Isapi\daf.dll"
		Terminators Headers | Mapping
	</Object>