ISAPI Extensions: Filters

HomeOverviewHow Do I

This article describes the benefits of ISAPI filters and how to use them with Internet servers. Topics included in this article are:

The development environment includes an ISAPI Extension Wizard to help you create an ISAPI filter and set the appropriate notifications. For information on using the wizard, see the article Steps to Create a Typical ISAPI Filter.

See the MFC Internet sample MFCUCASE for an illustration of how to use a CHttpFilter object to create a filter that converts content to uppercase by overriding two CHttpFilter member functions: OnSendRawData and OnUrlMap.

How Filters Can Enhance a Server

Use Internet Server API (ISAPI) filters to enhance Internet servers with custom features such as enhanced logging of HTTP requests, custom encryption and compression schemes, or new authentication methods. The filter application sits between the network connection to the clients and the HTTP server. Depending on the options that the filter application requests notification for, it can act on several server actions. Filters can be set to receive notification when selected events occur, including reading raw data from the client, processing the headers, managing communications over a secure port using Personal Communications Technology (PCT) or Secure Sockets Layer (SSL), or handling other stages in the processing of the HTTP request.

Filter Entry-Point Functions

Use the MFC class CHttpFilter to create a filter to manage the incoming and outgoing data for an ISAPI server. Two entry-point member functions, CHttpFilter::GetFilterVersion and CHttpFilter::HttpFilterProc, establish the filter and configure it for the notifications it will act upon.

GetFilterVersion

Using CHttpFilter requires that the filter application's path be inserted into the registry, in HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/W3SVC/Parameters/FilterDLLs. When the server starts up, it reads this value and loads the DLLs listed. It then calls CHttpFilter::GetFilterVersion to perform three tasks:

HttpFilterProc

The second CHttpFilter member function to consider as an entry point is CHttpFilter::HttpFilterProc. As events happen, the server notifies each filter that registered for the event by calling the filter’s HttpFilterProc entry point. MFC's implementation of CHttpFilter::HttpFilterProc determines which event was fired and calls one of the CHttpFilter members dedicated to handling the specific notification. You can override HttpFilterProc to provide special handling for events. To write code that reacts only to a particular event, see the next section, Types of Filter Notifications.

Types of Filter Notifications

When CHttpFilter::HttpFilterProc is called, the notifications received will determine which of the CHttpFilter member functions will be called. In your override of an individual HttpFilterProc member function, you can set the filter object to change data in a specific manner. For example, you can create an encryption or compression filter by overriding OnSendRawData and providing whatever special functionality your filter needs. Other overridable member functions include:

See Also   CHttpFilter, CHttpFilterContext, Internet: Where Is...