Extension Request Processing

Extension Structure

ISAPI extensions can accomplish a wide variety of tasks, but in order to be used by IIS, they must provide a standard interface. Each extension must implement, and export from the DLL, two primary functions: GetExtensionVersion and HttpExtensionProc. A third function, TerminateExtension, is considered optional.

Request Processing Sequence

ISAPI extension request processing is fairly straightforward. The following events occur when IIS receives a request that IIS maps to an ISAPI extension:

  1. IIS loads the DLL, if it is not already in memory. When the DLL is loaded into memory, the optional DLL entry/exit function (usually DllMain) will be called automatically, by Windows. Next, IIS calls the extension's GetExtensionVersion entry-point function.
  2. IIS performs minor preprocessing on the incoming request.
  3. IIS creates and populates an EXTENSION_CONTROL_BLOCK, which IIS will use to pass request data and callback function pointers to the extension.
  4. IIS calls the ISAPI extension's HttpExtensionProc function, passing a pointer to the EXTENSION_CONTROL_BLOCK structure that was created for this request.
  5. The ISAPI extension performs whatever actions it was designed to perform. This can include reading more data from the client, as in a POST operation, or writing headers and data back to the client.
  6. For synchronous operations, the extension indicates to IIS that it has finished processing the request by simply exiting the HttpExtensionProc function. For more information about asynchronous operations, see Asynchronous I/O Processing.
  7. IIS performs cleanup on the connection used for the request, and then closes the connection.
  8. Once the ISAPI extension is no longer needed, IIS calls the TerminateExtension function, if the extension provides one. This function is commonly used by extensions to perform cleanup.

It is important to note that GetExtensionVersion is not called for every request. In contrast, HttpExtensionProc is called exactly once for each and every request for the ISAPI extension. It is also important to note that exactly one EXTENSION_CONTROL_BLOCK structure is used for each incoming request.

If IIS is configured so that IIS extensions are cached, TerminateExtension will not be called until the IIS Web server is shutdown or restarted.