Developer Notes for ISAPI Filters

There are some important issues you should consider in developing your ISAPI filter. The following notes provide some general guidelines summarizing these issues.

Language and Framework Choice

• Consider using the MFC library: This documentation set assumes that you are using either C or C++ as your development language and that you are not making use of the Microsoft Foundation Classes (MFC) library. (The MFC library provides an object model, as well as a wizard, that might aid you in creating ISAPI filters. Classes such as CHttpFilter and CHttpFilterContext are provided. For more information, see the MFC and Visual C++ documentation.

Choice of Notifications

You should choose carefully which notifications to handle. Here are some issues to keep in mind when making your selection:

• Do not register for a notification unless you need that notification: You should register your filters to be notified of only those events that it needs for processing. Some filter notifications are very expensive in terms of CPU resources and I/O throughput (most notably SEND_RAW_DATA), and can have a significant effect on the speed and scalability of IIS.
• Register for SF_NOTIFY_END_OF_NET_SESSION: You should register most of your filters for SF_NOTIFY_END_OF_NET_SESSION, as it is a good time to perform session-level resource maintenance, such as recycling buffers. For performance reasons, most filters keep a pool of filter buffers and only allocate or free them when the pool becomes empty or too large to save on the overhead of the memory management.
• Do not attempt to change the notification flags in the metabase: The metabase property FilterFlags contain flags that indicate to IIS which notification types a particular ISAPI filter can support. However, this property is populated by IIS from the bit flags passed in the HTTP_FILTER_VERSION structure from GetFilterVersion. FilterFlags should be considered read-only.

Proper Use of Notifications and Filters

It is important to use the different event notification types properly. Here are a few tips:

• Avoid extended or extraneous processing within filters: Certain operations are costly to perform, and should be avoided within ISAPI filters, if possible; POST operations are a good example. Also, in most cases, an ISAPI filter should only return data to the client when it handles an exception case —such as when a request is denied, or generates an error.
• Use SF_NOTIFY_AUTHENTICATE only to map credentials to a Windows 2000 account, not to deny access: Because SF_NOTIFY_AUTHENTICATE is sent by IIS only on the first request of each session, you should not perform your sole validation checking within the handler for this notification—it will not always be called. Instead, you should typically use only SF_NOTIFY_AUTHENTICATE notification handlers for authenticating user name and passwords.
• Care should be taken to prevent recursion when accessing certain server variables: If a filter retrieves the PATH_TRANSLATED or PATH_INFO server variables within the SF_NOTIFY_URL_MAP notification, the filter will be called recursively with the SF_NOTIFY_URL_MAP notification to do the physical translation for the variable.
• Do not change request from static to dynamic, or vice versa, within SF_NOTIFY_URL_MAP: If you must translate a request from a dynamic file to a static file, or static to dynamic, you should do so from within a SF_NOTIFY_PREPROC_HEADERS handler, not from within a SF_NOTIFY_URL_MAP handler.
• Use the AllocMem callback function with care: You can use the AllocMem callback function with the HTTP_FILTER_CONTEXT structure to allocate memory. The memory that is allocated will automatically be freed when the communication with the client is terminated. Managing memory in this way can have a negative impact on performance, because memory allocated by IIS in response to calls to AllocMem comes from the global IIS process heap. It may be preferable to create your own memory pool and adjust the pool only as necessary. This may reduce the overhead caused by allocating and de-allocating memory from the global IIS process heap.
• Assign the correct priority to your filter: Some of the functionality provided with IIS makes use of bundled ISAPI filters. In general, unless there is a compelling reason to do otherwise, you should avoid designating your filters high priority to avoid conflicting with the system filters.

Raw Data Filters

A raw data filter is simply a filter that has registered for the SF_NOTIFY_READ_RAW_DATA event notification. However, there are a number of additional complexities and considerations to keep in mind when developing raw data filters. These issues include:

• Filters that register for the SF_NOTIFY_READ_RAW_DATA event must be assigned at the Web service level: They can not be assigned to an individual Web site.
• Raw data filters should be selective about what types of content they process, if possible: For instance, if your filter performs processing only on HTML files, other files should be ignored early in the notification sequence. If your filter determines that the file is not of the appropriate type, it can use the SF_REQ_DISABLE_NOTIFICATIONS ServerSupportFunction to disable all further notifications for that request.

An example of a filter that reads raw data is provided in the \Inetpub\iissamples\sdk\isapi\filters directory. See the Cookie Conversion Filter in the ISAPI Examples section of Developer Samples for more information.