ISAPI Architecture Overview

ISAPI applications are DLLs that interact with IIS API directly. ISAPI software can be an extension or a filter. ISAPI extensions are DLLs that are called from a qualified request to IIS. ISAPI filters are called indiscriminately from all requests to IIS. HTTP requests may be sent directly to an ISAPI extension using a uniform resource locator (URL) link or using an HTTP post via an HTML form submission. An ISAPI extension can be called indirectly by mapping a file to a particular ISAPI extension in IIS, so that when a file is requested from IIS with a filename that matches the mapping value, the respective ISAPI extension will be called on the file request. The file mapping technique is the same process that ATL Server uses (see Chapter 16) to associate Server Response Files (SRFs) to a particular ISAPI extension. ISAPI filters can be set to respond to requests according to a priority, as compared to other filters loaded in IIS. Filters are good options for specialized applications involving IIS and are usually related to the following tasks:

• Encryption

• Logging

• Authentication

• Data compression

ISAPI extensions are the most common implementation of ISAPI. ISAPI filters are rather difficult to produce and limited in their scope of usage. They are beyond the scope of this chapter and, therefore, will not be covered.

URL Anatomy

A URL defines the entire string used to denote a particular resource on a server located on the Internet. A URL is formed according to the following syntax:

<<scheme>>://<<user>>:<<password>>@<<host>>:<<port>>/<<url-path>>/<<extra-info>>

For example, the following URL requests an ISAPI DLL named SEUX.dll. Parameters named parm1 and parm2 are also specified in the URL. In Table 17-1, this URL is broken down into its parts to show how a typical URL requesting an ISAPI DLL will be identified. Many of the terms for the URL parts will be useful for the purposes of describing server variable values, which are presented later in this chapter. Note that the fields that are not in the example, as noted in the table, are rare to find in a URL. The example used is of a common URL, which you’re more likely to encounter.

http://amd1700v2/simpleisapi/folder1/folder2/SEUX.dll/PATH_INFO? parm1=value1&parm2=value

Table 17-1: Sample URL Parts

URL Part	Value from Example
scheme	http
user	Not present in example URL
password	Not present in example URL
host	amd1700v2
port	Not present in example URL but assumed to be 80
url-path	simpleisapi/folder1/folder2/SEUX.dll/PATH_INFO
extra-info	?parm1=value1&parm2=value

If an ISAPI DLL is requested via a URL link directly, the filename of the ISAPI extension DLL is identified in the url-path section. The parameter = value pairs are located in the extra-info section of the URL, as shown in Table 17-1. Data may be sent in the form of parameter = value pairs, which may be passed to the ISAPI extension using the URL extra-info section or using HTTP posts via an HTML form submission.

ISAPI Extensions Interacting with IIS

When IIS receives the request and deems that it is necessary to use the ISAPI extension, either because a file was requested that was mapped to the ISAPI extension or because the ISAPI extension itself was requested, IIS will pass the HTTP request along to the ISAPI extension. For the ISAPI extension to receive the HTTP request, a certain programmatic interface must be implemented by the ISAPI extension. As expected, your ISAPI application must include the ISAPI header files that define the structures and classes. The ISAPI extension will receive the request through the implemented API, and the HTTP request data will be loaded in the structures and classes that are a part of ISAPI. The ISAPI extension will parse the HTTP request data and could dispatch calls to other software, such as the business layer software, as shown in Figure 17-1. Responses from the business layer will be formed into an HTTP response and returned to the IIS. IIS will take the ISAPI extension response and return it to the web consumer that placed the initial request to IIS.

Figure 17-1: Overview of ISAPI extension architecture

The architecture shown in Figure 17-1 represents two possible ways that an ISAPI extension might be used, but it should not be viewed as an exclusive implementation of the technology. The only definite aspect of the implementation of an ISAPI extension is the call into the ISAPI extension on an HTTP request and the presence of the structures and classes that contain the HTTP request and support the programmatic interaction with the HTTP response and the HTTP request. It is up to you to architect the logic abstraction. Dispatching calls to a business logic DLL may not be necessary if the business logic is inside the ISAPI extension itself. Because ISAPI writes data back to the HTTP request directly, you should consider making an architectural design that abstracts the presentation logic so that you do not have to recompile your ISAPI DLL when the presentation logic is changed.

ISAPI Compared to ATL Server

When comparing ATL Server and ISAPI, a major difference is that ISAPI offers the developer less infrastructure support and provides less of an implied architecture than ATL Server. The ISAPI for extensions (as opposed to filters) consists of a few API functions and a few structures and classes that are the parameters of the API functions. In contrast, ATL Server provides many new support classes, macros, and functions. ATL Server plays much the same role to ISAPI that Microsoft Foundation Classes (MFC) did to the Windows API—ATL Server acts as an additional layer of code to help the developer better utilize the technology. ATL Server helps support the developer who chooses to produce software that interacts with the ISAPI by pointing the developer in a direction that will likely help and offering supporting software. The developer can choose which software to use, but sometimes that, too, can be difficult. In such circumstances, ISAPI may seem like an attractive alternative. Unlike ATL Server, ISAPI offers no abstraction of any type of logic, and not much has been written about how to use ISAPI. You can use ATL Server classes in an ISAPI application without using an ATL Server project template. Alternatively, configuring an ATL Server project template to use a single DLL and no options will provide a project framework that is quite similar to a typical ISAPI project framework.