Writing a simple ISAPI Filter for IIS (Views: 2141)
Problem/Question/Abstract: This article shows you the basics of creating a simple ISAPI filter and how to use one to map sub-domains into specific folders. http://daniel.yourdomain.com will map the same way as http://www.yourdomain.com/members/daniel Answer: Borland has gone a long way helping us to create web applications. As of today, however, there is no real support for writing ISAPI Filters. Note: ISAPI Filters are quite different from ISAPI/NSAPI Extensions! INTRODUCTION I have had no chance, so far, to look into Delphi 6 and figure how it supports ISAPI Filters, a first look revealed no new facts, anyway. ISAPI Filters are not called by referencing them in the URI of the request like http://www.yourserver.com/cgi/isapi.dll?params=54,4568,54.8 rather they are installed with the IIS-Console and invoked on EVERY call made to your web site. Therefore, ISAPI Filters have to be very fast in processing requests. THE LIBRARY BASICS Every ISAPI Dll has to export two (or three) functions. These functions are called by thi IIS to initialize the filter, to process every single request and to destroy the filter. Attn.: These names are case-sensitive! GetFilterVersion is called once, while the filter is running. All preliminary work is to be done here. The filter has to return on what kind of events it is supposed to process data. HttpFilterProc is called for every object requested by the client, regardless of whether it is an image, a html file or an ASP script. TerminateFilter is called when the web server is shuting down. Use this function to free resources reservered, etc. This function must return the value 1 - as off IIS 4 (NT) and IIS 5 (W2K). THE EVENTS PASSED TO HTTPFILTERPROC The following basic events are defined: SF_NOTIFY_READ_RAW_DATA - The filter wants to process all incoming data (like form data) SF_NOTIFY_PREPROC_HEADERS - The filter wants to process all header information sent by the client (browser type, uri, cookies, ...) SF_NOTIFY_AUTHENTICATION - The filter is used to check the user authentication sent by the client SF_NOTIFY_URL_MAP - The filter is used to map incoming requests to specific folders and files on the hard drive SF_NOTIFY_ACCESS_DENIED - The filter wants to process responses when authentication has failed (for logging, ...) SF_NOTIFY_SEND_RAW_DATA - The filter wants to process all outgoing data (like link checker, cookie munchers, ...) SF_NOTIFY_LOG - The filter is used to change the data sent to the IIS log files SF_NOTIFY_END_OF_NET_SESSION - The filter has to free resources reserved for specific users Note: The samples named are just a short list of possible uses for ISAPI filters. Because a filter is invoked on every request, you have to register the filter for every event you want to handle. Events, the filter does not register for, are not sent to it, thus increasing the speed of the filter. THE SUBDOMAIN <--> URL MAPPER In this article I show you one simple, but useful application of such an ISAPI filter. This filter does not respect some aspects of good programming, like loading setup information, but rather has them written directly into the code - this one is left for you. I am just showing you the basics of ISAPI Filter programming. The filter to be installed on the "Properties" dialog with your IIS-Console for the specific "Web Site." Attn: You can install the filter on multiple "Web Sites," it is, however, loaded once only for all web sites using it. Therefore, you have to take care of this fact within your code. Further: I have not made this sample aware of the multi-threading part an ISAPI Filter has to take care of. WHAT DOES THIS SAMPLE DO Incoming request like http://username.yourdomain.com/guestbook.asp are mapped as they were entered like http://www.yourdomain.com/members/username/guestbook.asp "Members" can be defined by you. This filter maps the subdomain only, if the subfolder corresponding with the subdomain exists. MORE ON ISAPI FILTERS In a future article I will publish a complete unit with all definitions for ISAPI Filters. At present I am still working on them. You can read more on ISAPI filters on the msdn.microsoft.com home page. Here are the ISAPI header conversions: ISAPI Filter Header (D3K) THE SOURCE CODE FOR THE ISAPI FILTER LIBRARY library DomainMapper; uses Windows, SysUtils, Classes, FileCtrl; {$R *.RES} // these constants must be changed to match your environment const // as found on the hard drive FAbsBaseFolder = 'C:\INetPub\WWWRoot\Members\'; // as entered in the URL FRelBaseFolder = '/members/'; const SF_MAX_FILTER_DESC_LEN = (256 + 1); SF_NOTIFY_SECURE_PORT = $00000001; SF_NOTIFY_NONSECURE_PORT = $00000002; SF_NOTIFY_READ_RAW_DATA = $00008000; SF_NOTIFY_PREPROC_HEADERS = $00004000; SF_NOTIFY_AUTHENTICATION = $00002000; SF_NOTIFY_URL_MAP = $00001000; SF_NOTIFY_ACCESS_DENIED = $00000800; SF_NOTIFY_SEND_RAW_DATA = $00000400; SF_NOTIFY_LOG = $00000200; SF_NOTIFY_END_OF_NET_SESSION = $00000100; SF_NOTIFY_ORDER_HIGH = $00080000; SF_NOTIFY_ORDER_MEDIUM = $00040000; SF_NOTIFY_ORDER_LOW = $00020000; SF_NOTIFY_ORDER_DEFAULT = SF_NOTIFY_ORDER_LOW; SF_NOTIFY_ORDER_MASK = SF_NOTIFY_ORDER_HIGH or SF_NOTIFY_ORDER_MEDIUM or SF_NOTIFY_ORDER_LOW; SF_STATUS_REQ_FINISHED = $8000000; SF_STATUS_REQ_FINISHED_KEEP_CONN = $8000001; SF_STATUS_REQ_NEXT_NOTIFICATION = $8000002; SF_STATUS_REQ_HANDLED_NOTIFICATION = $8000003; SF_STATUS_REQ_ERROR = $8000004; SF_STATUS_REQ_READ_NEXT = $8000005; type PHTTP_FILTER_VERSION = ^HTTP_FILTER_VERSION; HTTP_FILTER_VERSION = record dwServerFilterVersion: DWORD; dwFilterVersion: DWORD; lpszFilterDesc: array[0..SF_MAX_FILTER_DESC_LEN - 1] of Char; dwFlags: DWORD; end; THTTP_FILTER_VERSION = HTTP_FILTER_VERSION; LPHTTP_FILTER_VERSION = PHTTP_FILTER_VERSION; LPVOID = POINTER; TFilterGetServerVariableProc = function( var pfc {: THTTP_FILTER_CONTEXT}; VariableName: PChar; Buffer: Pointer; var Size: DWORD ): BOOL; stdcall; TFilterAddResponseHeadersProc = function( var pfc {: THTTP_FILTER_CONTEXT}; lpszHeaders: PChar; dwReserved: DWORD ): BOOL; stdcall; TFilterWriteClientProc = function( var pfc {: THTTP_FILTER_CONTEXT}; Buffer: Pointer; var Bytes: DWORD; dwReserved: DWORD ): BOOL; stdcall; TFilterAllocMemProc = function( var pfc {: THTTP_FILTER_CONTEXT}; cbSize: DWORD; dwReserved: DWORD ): Pointer; stdcall; TFilterServerSupportFunctionProc = function( var pfc {: THTTP_FILTER_CONTEXT}; sfReq: DWORD; pData: Pointer; ul1, ul2: DWORD ): BOOL; stdcall; PHTTP_FILTER_CONTEXT = ^THTTP_FILTER_CONTEXT; THTTP_FILTER_CONTEXT = record cbSize: DWORD; Revision: DWORD; ServerContext: Pointer; ulReserved: DWORD; fIsSecurePort: BOOL; pFilterContext: Pointer; GetServerVariable: TFilterGetServerVariableProc; AddResponseHeaders: TFilterAddResponseHeadersProc; WriteClient: TFilterWriteClientProc; AllocMem: TFilterAllocMemProc; ServerSupportFunction: TFilterServerSupportFunctionProc; end; HTTP_FILTER_CONTEXT = THTTP_FILTER_CONTEXT; PCardinal = ^Cardinal; TGetServerVariable = function( var pfc: THTTP_FILTER_CONTEXT; VariableName: PChar; Buffer: LPVOID; BuffSize: PCardinal ): BOOL; StdCall; TGetHeaderProc = function(var pfc: THTTP_FILTER_CONTEXT; lpszName: PChar; var lpvBuffer; var lpdwSize: DWORD): BOOL stdcall; TSetHeaderProc = function(var pfc: THTTP_FILTER_CONTEXT; lpszName, lpszValue: PChar): BOOL stdcall; TAddHeaderProc = function(var pfc: THTTP_FILTER_CONTEXT; lpszName, lpszValue: PChar): BOOL stdcall; PHTTP_FILTER_PREPROC_HEADERS = ^THTTP_FILTER_PREPROC_HEADERS; THTTP_FILTER_PREPROC_HEADERS = record GetHeader: TGetHeaderProc; SetHeader: TSetHeaderProc; AddHeader: TAddHeaderProc; dwReserved: DWORD; end; { * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Exported Functions * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * } function GetFilterVersion(var pVer: HTTP_FILTER_VERSION): BOOL; stdcall; export; begin with pVer do begin // version dwFilterVersion := MakeLong(0 {minor}, 1 {major}); // description StrPCopy(lpszFilterDesc, 'A Simple Domain Mapper'); // notification flags dwFlags := SF_NOTIFY_ORDER_DEFAULT or SF_NOTIFY_PREPROC_HEADERS; end; Result := True; end; function HttpFilterProc(var FilterContext: HTTP_FILTER_CONTEXT; NotificationType: DWORD; pvNotification: LPVOID): DWORD; stdcall; export; var Buffer: array[0..4096] of Char; Size: Cardinal; P: Integer; DestFolder, Domain, SubDomain, URL: string; Data: THTTP_FILTER_PREPROC_HEADERS; begin try Result := SF_STATUS_REQ_NEXT_NOTIFICATION; if NotificationType = SF_NOTIFY_PREPROC_HEADERS then begin // we can check whether to map the current sub-domain into a directory Data := THTTP_FILTER_PREPROC_HEADERS(pvNotification^); // get the domain requested by the user Size := SizeOf(Buffer); FillChar(Buffer, Size, 0); TGetServerVariable(FilterContext.GetServerVariable) (FilterContext, 'SERVER_NAME', @Buffer[0], @Size); Domain := StrPas(@Buffer[0]); // get the sub-domain requested P := Pos('.', Domain); if P = 0 then Exit; SubDomain := Copy(Domain, 1, P - 1); // create the destination folder DestFolder := FAbsBaseFolder + SubDomain; if DirectoryExists(ExtractFilePath(DestFolder)) then begin // the sub-domain my be routed - a corresponding folder does exist // get the uri of the document requested Size := SizeOf(Buffer); FillChar(Buffer, Size, 0); TGetHeaderProc(Data.GetHeader)(FilterContext, 'url', Buffer[0], Size); URL := StrPas(Buffer); // add the virtual base folder to the uri if URL = '' then URL := FRelBaseFolder + SubDomain else URL := FRelBaseFolder + SubDomain + URL; // send new uri to IIS StrPCopy(@Buffer[0], URL); TSetHeaderProc(Data.SetHeader)(FilterContext, 'url', @Buffer[0]); end; end; except // on error return request to process next ISAPI message Result := SF_STATUS_REQ_NEXT_NOTIFICATION; end; end; function TerminateFilter(Flags: DWORD): DWORD; stdcall; export; begin // must return 1 (as of IIS 4 and IIS 5) Result := 1; end; exports GetFilterVersion, HttpFilterProc, TerminateFilter; begin end. There is a Delphi Component that makes it easy to write ISAPI Filters with Delphi. It is distributed as source code. It is an excellent starting point for beginners as well as a time saving tool for advanced users. TbcISAPIFilter component is available at: http://www.bestcode.com/html/isapi_filter.html |