This sample illustrates how you can create a simple conversion filter. Any conversion filter must accomplish several tasks, including parsing HTTP request headers, sending HTTP responses, and saving filter state. For the purposes of demonstration, this sample filter converts HTML files into upper case if requested by the client browser. The client browser makes the request by inserting the (nonexistent) subdirectory \uc someplace in the URL path. Thus the URL request
http://www.mysite.com/uc/mypage.htmwould indicate that the server should send an all-upper case version of the mypage.htm file back to the client browser.
The GetFilterVersion entry-point function is called by IIS when the filter is first loaded into memory, when the Web service is initially started. In addition to passing the typical version and descriptive information to IIS, GetFilterVersion also registers this filter for the SF_NOTIFY_URL_MAP and SF_NOTIFY_SEND_RAW_DATA notifications.
As with most filters, HttpFilterProc handles the bulk of the processing. HttpFilterProc will first be invoked when the client browser's URL request has been received and mapped to a local, physical path on the server. The filter parses the path, looking for the \uc string that will indicate whether the file should be converted to uppercase. If the special string is found, it is removed from the request, the request is reassembled, and the pFilterContext member of the HTTP_FILTER_CONTEXT structure is set to 1. If the string is not found, pFilterContext remains null.
When HttpFilterProc is invoked for the SF_NOTIFY_SEND_RAW_DATA notifications, it first checks to see if the pFilterContext flag has been set or not. A null value for the flag indicates that the \uc string was never found in the SF_NOTIFY_URL_MAP event, so no conversion is performed for the current request. However, if pFilterContext has been set to 1, it indicates that the string was found and that uppercase conversion is requested by the client browser.
Once it is determined that conversion is requested, HttpFilterProc executes a series of loops to parse the outgoing response. The first loop separates the HTTP header from the rest of the response. The header is then searched to make sure that the content-type of the response is HTML. The final loop of the function performs the actual character case conversion. It is important to note that if HttpFilterProc did not check the content-type specified in the header, responses that contained binary data, such as GIF files, would be corrupted by the case conversion loop.
This project is available in the ...\isapi\filters\upcase subdirectory of the IIS samples directory.