Share via

ISAPI Extensions: Filters

  • Article

|  Overview |  How Do I

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

  • How ISAPI Filters Can Enhance a Server

  • Filter Entry-Point Functions

  • Types of Filter Notifications

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 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, and , 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 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 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.

HttpFilterProc

The second CHttpFilter member function to consider as an entry point is . 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 and providing whatever special functionality your filter needs. Other overridable member functions include:

  •    Notifies the filter that the server has preprocessed the client headers.

  •    Authenticates the client.

  •    Notifies a filter when a server is mapping a logical URL to a physical path.

  •    Notifies the filter before raw data is sent from the server to the client.

  •    Notifies the filter after raw data is sent from the client to the server, but before the server processes it.

  •    Logs information to a server file.

  •    Notifies the filter that the session is ending.

See Also   , , Internet: Where Is...