Implementing Required ISAPI Filter Functions

  • Article

For an ISAPI filter to be used by IIS, it must provide a standard interface. Each filter application must implement and export two primary functions, GetFilterVersion and HttpFilterProc. A third function, TerminateFilter, is considered optional and is commonly used by filters to perform cleanup operations.

Initialization Using GetFilterVersion

The first time a request is made to a Web site on which a filter is installed, the initialization code in the filter?s GetFilterVersion function is executed.

Adding Functionality Using HttpFilterProc

Every filter is contained in a separate DLL that must export two entry-point functions, GetFilterVersion and HttpFilterProc, and optionally export the TerminateFilter function.

The metabase property, FilterLoadOrder, contains a list of all filters that IIS loads when the Web service is started.

The HttpFilterProc function is responsible for processing the event information. IIS calls the filter for every event for which it is registered. When IIS calls HttpFilterProc, it passes in an HTTP_FILTER_CONTEXT data structure. This structure is similar to the EXTENSION_CONTROL_BLOCK structure for an ISAPI extension, in that it is associated with a particular request and is used by IIS to coordinate filter processing. When IIS calls the filter's HttpFilterProc, it also passes in a DWORD that identifies the event that occurred and a pointer to a memory area, defined by IIS, that contains the event information. For more information about the interaction between ISAPI filters and IIS during event processing, see Filter Request Processing Sequence.

For examples of the use of HttpFilterProc, see Obtaining Server Variables and Adding to a Response Header.

The order in which events are processed is an important part of event handling. A number of factors can have an impact on this order; see Event Notification Order for a general outline of the issues involved.

Termination Using TerminateFilter

The optional TerminateFilter entry-point function can be used to gracefully free any allocated resources. For filters that implement and use worker thread pools, it is the recommended alternative. For filters that do not use worker threads, cleanup operations can be performed in DllMain instead.