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 Creating a Typical ISAPI Filter.
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 an encrypted 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.
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:
Exchange version information
The MFC implementation of GetFilterVersion compares the version number for which you are creating your filter with the server's version number.
Determine the requested events
Register your ISAPI filter applications only for the events that you require. If you register for extraneous events, your choices can have a significant negative impact on the performance and scalability of your filter.
Specify the priority to deliver the requested events
The priority of requested events is specified by GetFilterVersion in the dwFlags member of the HTTP_FILTER_VERSION structure. After the GetFilterVersion exchange, every time the server processes one of the events, it will call any filters that have registered for that event. The calling order depends on priority.
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:
OnPreprocHeaders Notifies the filter that the server has preprocessed the client headers.
OnAuthentication Authenticates the client.
OnUrlMap Notifies a filter when a server is mapping a logical URL to a physical path.
OnSendRawData Notifies the filter before raw data is sent from the server to the client.
OnReadRawData Notifies the filter after raw data is sent from the client to the server, but before the server processes it.
OnLog Logs information to a server file.
OnEndOfNetSession Notifies the filter that the session is ending.