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.



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

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.
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.
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 "|".
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.
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.
This configuration key defines, if extra headers are considered by the processing of this handler.
This configuration value will be the trailing string of each extra request header.
The headers in this list are not treated as extra headers.

All Phases

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


The ISAPI filter handler is an experimental plug in. Since the IIS and Pi3Web has different architectures it is difficult to be 100% compliant.
The Pi3Expressions in the configuration variables may contain besides the standard shortcuts used in Pi3Expressions the following, context specific parameters.
ParameterEvaluates to
%aAll extra headers, as required for header ALL_HTTP
%lContent-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".

The following support functions are not supported:



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.


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