Filter Event Processing

Filter Structure and Registration

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

A metabase property, FilterLoadOrder, contains a list of all filters that should be loaded by IIS when the Web service is started.

Request Processing Sequence

The following steps outline how IIS and ISAPI filters generally interact:

  1. When IIS initially loads an ISAPI filter, IIS creates and partially populates a HTTP_FILTER_VERSION structure. IIS then calls the filter's GetFilterVersion function, passing a pointer to the new structure as a parameter.
  2. The ISAPI filter populates the HTTP_FILTER_VERSION structure with some version and descriptive information. More importantly, the filter also uses HTTP_FILTER_VERSION to specify which event notifications it should receive, and to declare the general priority level for the filter. In addition, the filter also indicates whether it is interested in events from secure ports only, unsecure ports only, or both.
  3. Each HTTP transaction between IIS and a client browser triggers several distinct events. Each time an event occurs for which an ISAPI filter has registered (by using HTTP_FILTER_VERSION, as described in step 2), IIS calls the filter's HttpFilterProc entry-point function.

    If more than one ISAPI filter has registered for a given event, then IIS will notify filters marked as high priority first, medium priority second, and low priority last. If more than one ISAPI filter has declared the same general priority level, IIS will use the order in which the filters appear in the FilterLoadOrder property to resolve the tie.

  4. The ISAPI filter uses the notification type information, passed by IIS as a parameter to HttpFilterProc, to determine what particular data structure is pointed to by the other HttpFilterProc parameter, pvNotification. The ISAPI filter can then use the data contained in that data structure, as well as in the context structure HTTP_FILTER_CONTEXT, to perform any custom processing.
  5. Once processing is complete, the filter returns one of the SF_STATUS status codes to IIS, and IIS continues processing the HTTP request or response—at least until another event occurs for which ISAPI filters have registered.
  6. When the Web service is stopped or unloaded, IIS will call TerminateFilter in all ISAPI filters, as part of its shutdown sequence, for any filters that have implemented and exported the function. TerminateFilter is typically used to perform cleanup and de-allocation of allocated resources.

It is important to remember that GetFilterVersion is called exactly once, when the ISAPI filter is initially loaded. If you want to perform some per-connection initialization, you will have to manage it internally within the context of the HttpFilterProc function call.

Note   The priority setting for ISAPI filters is per filter, not per notification. For example, you cannot assign a low priority rating for one type of notification, and a high priority rating for another type.

For more detailed information about event notification types, and in what general order they occur during an HTTP transaction, see the Event Notification Order.