Enhancements to ISAPI Support

  • Article

Applies To: Windows Server 2003, Windows Server 2003 with SP1

IIS 6.0 supports both ISAPI extensions and ISAPI filters:

  • ISAPI extensions are DLLs that handle specific requests.

  • ISAPI filters are DLLs that you can register with IIS to modify the behavior of the server.

ISAPI extensions and filters load the first time a client requests resources that are processed by the ISAPIs and are kept in memory to handle future requests. ISAPI extensions handle specific requests from the client.

Like ISAPI extensions, ISAPI filters are programs that respond when the application server receives an HTTP request. Unlike ISAPI extensions, ISAPI filters are driven by Web server events instead of client requests. For example, you can write an ISAPI filter to control which files are mapped to a URL, modify the response sent by the server, and perform other actions to modify the behavior of the server.

IIS 6.0 supports these programmatic enhancements to ISAPI extensions:

  • HSE_REQ_EXEC_URL

  • HSE_REQ_VECTOR_SEND

  • HSE_REQ_REPORT_UNHEALTHY

  • HSE_REQ_SEND_CUSTOM_ERROR

These enhancements are new ServerSupportFunction callback functions, known as support functions. The ServerSupportFunction function, which returns data for several auxiliary functions that are not covered by other callback functions, is supplied in the EXTENSION_CONTROL_BLOCK structure that is associated with HTTP requests. IIS and the ISAPI extensions use the EXTENSION_CONTROL_BLOCK structure to exchange information.

For more information about ISAPI filters and extensions, including the ServerSupportFunction callback functions, see the IIS Web Application Technology Reference on MSDN.

Using HSE_REQ_EXEC_URL to Call Other URLS on the Server

The HSE_REQ_EXEC_URL support function (also known as ExecuteURL) allows ISAPI extensions to rewrite any part of the request, including the entity body, and have IIS reprocess this modified request. As long as the rewritten URL is in the same application pool and uses the same authentication, IIS can successfully reprocess the modified request.

This new support function gives ISAPI developers greater flexibility in transparently rewriting URLs on the server without the clients knowledge, allows an arbitrary number of URLs to be executed in a chain, and supports custom authentication. When used with wildcard application mapping, this support function can replace most read raw data filters by offering easy examination and modification of request entity body prior to request reprocessing. For information about wildcard application mapping, see Setting Application Mappings.

Using HSE_REQ_VECTOR_SEND to Consolidate Multiple Buffers

The HSE_REQ_VECTOR_SEND support function (also known as VectorSend) allows developers to group and send, in order, a list of buffers and file handles. This list is handed to IIS 6.0 and passed on to HTTP.sys, which compiles all the buffers and file handles within the kernel and then directly sends the group in one kernel-mode transition. This new functionality frees ISAPI from building large memory buffers or making multiple WriteClient calls.

In earlier versions of IIS, ISAPI developers have only two possibilities if they have multiple buffers that make up a response: they can either call WriteClient multiple times or assemble the response in one big memory buffer. The first approach causes a performance bottleneck because there is one kernel-mode transition for each WriteClient function call. The second approach also affects performance and uses additional memory. VectorSend is a more all-purpose transmit function for IIS 6.0 customers.

Using HSE_REQ_REPORT_UNHEALTHY to Recycle a Worker Process

The HSE_REQ_REPORT_UNHEALTHY support function (also known as ReportUnhealthy) allows an ISAPI extension to request that its worker process be recycled. Developers can use this new function to request a recycle if their ISAPI application becomes unstable or enters an unknown state. Note that in order to cause a recycle after an ISAPI calls ReportUnhealthy, health monitoring must be enabled for the ISAPI extensions application pool. When calling ReportUnhealthy, the developer can also pass in a string representing the reason why the ISAPI extension is calling ReportUnhealthy. This string is then added to the event that the worker process writes to the application log, which you can view in Windows Server 2003 Event Viewer.

Using HSE_REQ_SEND_CUSTOM_ERROR to Send Custom Error Messages

The HSE_REQ_SEND_CUSTOM_ERROR support function (also known as SendCustomErrors) allows ISAPI developers to send the client a specific IIS-configured custom error message, including all sub-error codes. This support function allows an ISAPI extension to better integrate its error messages with a Web sites custom error configuration.

Using the New Unicode ServerSupportFunctions

In addition to the preceding enhancements, IIS 6.0 allows ISAPI extensions to retrieve server variable values that are encoded as Unicode characters. In particular, ISAPI extensions can retrieve the request URL in Unicode, which can benefit international companies that have multilanguage Web sites for which the URL is not in the same code page as the server.

The following are new ServerSupportFunction callback functions that support values encoded as Unicode characters:

HSE_REQ_EXEC_UNICODE_URL

The HSE_REQ_EXEC_UNICODE_URL support function is functionally identical to HSE_REQ_EXEC_URL except that it expects the URL to be in Unicode instead of ANSI. This support function, when used with the new Unicode GetServerVariable, easily substitutes for HSE_REQ_EXEC_URL.

HSE_REQ_MAP_UNICODE_URL_TO_PATH

Allows your ISAPI extension to map a logical URL path to a physical path.

HSE_REQ_MAP_UNICODE_URL_TO_PATH_EX

Allows your ISAPI extension to map a logical URL path to a physical path, as well as gather several types of attributes that are associated with that physical path, such as access-control or cache-control flags.