For years, client/server computing has relied on custom applications for solving business and computing problems. These solutions have often been written in a high-level language such as Visual C++ or rapid development tools such as Visual Basic or Delphi.
One of the reasons for designing custom applications was to create a unique and different approach to solving the problem at hand. The solution was often to create a nifty user interface that provided easy data storage and access methods to application data.
Let's take a simple example such as a company personnel database. It would be easy, and in some cases practical, to use a tool such as Microsoft Access to attach to the given database tables and display a grid of all personnel and their associated information.
The user could enter SQL statements to do searches and to display the information wanted. Although this approach certainly solves the generic problem of viewing database records, it is neither an easy-to-use nor an effective method.
To solve this problem, we could design a custom application to retrieve the information efficiently and with a user-friendly interface. A custom application would also deal with different data types such as binary large objects (BLOBs) for storing, retrieving, and presenting photo or signature information.
Developing Web sites presents some of the same challenges as developing client/server applications. How can I customize my site to provide the extended function needed for the information that I want to give Web users?
Microsoft released the Internet Information Server (IIS) with the understanding that although HTML is the language of choice for publishing browser content, we would need ways to access information not in HTML format. Microsoft also realized that Web site developers would want to provide custom additions to their sites to build new and exciting Web pages.
Such Web pages would provide information from diverse data sources not readable by browser applications. So the task would be to convert this information to HTML format for browser viewing. We would also need to be able to create custom functions such as user authentication and usage logs.
IIS was released with an application program interface (API), called the Internet server API (ISAPI), that could be used to build additional capabilities into the server. These capabilities could be added through ISAPI extensions (also called server applications).
ISAPI is an open specification for communication between Web browsers (clients) and Web servers. It is not a proprietary Microsoft specification. Any Web vendors can use the ISAPI interface in their Web server.
Although ISAPI is predominately used for enhancing client/server interactions, ISAPI is an open specification originally developed by Process Software in collaboration with Microsoft, and specifies how DLLs can extend the function of the server.
![]()
In this chapter, you learn:
ISAPI extensions give you the power to add dynamic interactivity to any Web site. In a traditional Web site, a browser accesses Web pages that consist of HTML data. HTML data is predominately static. An example of HTML static data is the title of a Web page.
Static data in HTML format has its uses. It can supply, for example, product or company information, news bulletins, or product releases. But we may want to build applications for Web sites that provide more timely information and also provide other media such as audio and digital video.
To build dynamic and interactive applications, we need a vehicle that can respond to browser queries regardless what kind of information is needed or where it is stored. This vehicle is an ISAPI extension.
ISAPI extensions are separate applications that can be queried for specific information by the browser. ISAPI extensions are implemented as DLLs that are loaded by the server on request.
Input parameters such as request information can be passed into the extension. The extension can then access the information needed, for example from a database, and return it to the browser in the form of an HTML page.
Uses of ISAPI extensions include searching a database for information, accessing files located on a company intranet, or accessing other applications using interprocess communication techniques.
ISAPI was designed to as a programming interface that developers could use to extend the capabilities of a hypertext transport protocol (HTTP) server. ISAPI does this through extensions. You can use ISAPI to develop different kinds of extensions. For example:
The goal of an ISAPI extension is custom development capabilities for any Web site. ISAPI, with IIS, provides a structured approach for extending the capabilities of a Web site.
How are ISAPI extensions accessed? The most common method is for the Web site to supply a fill-in form, like a dialog box in conventional programs, for users to enter criteria about the information they want to access.
Server extensions can also be accessed through other means such as HTTP GETs. Figure 5.1 is a sample fill-in form used by a Web search engine for retrieving information from the Internet.
Fill-in form used by the Yahoo search engine.
The user fills in the form and presses a button. This causes the form to invoke the server extension. The form sends an HTTP request to the extension in the following format.
HTTP://www.xyz.com/scripts/extension.dll?Foo=bar
As you can see, the fill-in form is programmed to invoke a specific server extension on a Web site. The information entered into the fill-in form is passed to the extension as parameters. This is like accessing a CGI application except that the extension on a CGI application would be EXE executable.
Once the request is made to the ISAPI extension, the server loads the extension into memory (if it is not already loaded) and passes the input parameters to the extension. The input parameters are analogous to the input parameters passed into a CGI application through standard input (stdin).
The extension takes the input parameters and does the operations to comply with the client request. This could mean opening a connection to a database such as an SQL server and doing a database search. It could also mean opening a file on a company intranet and returning the contents for the browser to display.
After the extension finishes processing the client request, it must return a result to the client. Results are typically returned to the client as HTML pages. The job of the extension is to convert the data obtained during a client request into a form that can be interpreted by the client.
For example, if an extension is retrieving records from a database during a client request, the client can't directly process the raw database records. The extension must interpret the database results and translate the results into HTML, which is sent to the client. The client displays the HTML page to the user.
Although HTML is the most common data format used for exchanging information between the browser and Web server, your extensions are not limited to HTML. If the browser and the server can agree on another data format, you can use it. However, using nonstandard data formats may limit the accessibility of your Web sites.
![]()
There are many compelling reasons for using ISAPI extensions, to begin with because they supply fast interactive capabilities to a Web site. ISAPI extensions also offer some advantages over traditional techniques such as CGI applications.
Because of ISAPI's similarity to CGI applications, most of the Web servers that work with ISAPI also work with ISAPI extensions. This may not be the case with ISAPI filters.
ISAPI filters are a specific mechanism used for applying intelligent message-filtering to all HTTP requests. Filters are used for protections such as custom authentication schemes, compression, encryption, logging, and traffic analysis.
There is no CGI type equivalent to ISAPI filters. As a result, many Web servers may not work with ISAPI filters.
ISAPI extensions have much lower overhead than ISAPI filters. An ISAPI filter is a replaceable, dynamic-link library (DLL) the server calls for every HTTP request.
When the filter is loaded, it tells the server what kinds of notifications it accepts. After that, whenever a selected event occurs, the filter is called to process the event.
In contrast, ISAPI extensions are only loaded into memory and called when a request is received specifically for the extension.
ISAPI filters register to receive incoming events. All events in the HTTP server that the filter is registered for are sent to the filter.
These events are typically the result of a client request. A filter is a mechanism for intercepting all client requests before the HTTP server processes the request. Depending on the options chosen by the filter, it can act on several server functions.
These include reading raw data from the client, processing the headers, and communicating over a secure port-for example, using private communication technology (PCT) and the secure sockets layer (SSL), or at several other stages in processing the HTTP request.
ISAPI filters are like Windows hook functions for the events that they process. ISAPI filters get the first opportunity to process events sent to a server. The filters can process the events, throw them away, or pass them on to the HTTP server for processing.
An ISAPI extension and an ISAPI filter have different goals. The extension's goal is to retrieve information requested by the client and return the results to the client when a client issues a specific request to the extension.
Filters, by contrast, intercede with these requests without the client's knowledge.
This difference makes it harder for filters to return client-specific information to the client on a given request.
For the experienced Web developer, a notable feature of ISAPI extensions is their similarity to CGI applications. This similarity allows programmers with CGI experience to quickly and easily convert existing CGI scripts to ISAPI extensions.
The following outlines the basic steps for converting CGI applications to ISAPI server applications.
There is no better way to be introduced to IASPI extensions than to build, install, and request one. As with your first C program, we use the traditional "Hello, World!" model to develop the first ISAPI extension.
The "Hello, World!" extension is a basic ISAPI extension that, when requested, returns an HTML page with the string "Hello, World!" on it. Larger extensions are developed in later chapters.
The "Hello, World!" extension was developed using Visual C++ 4.2. All the project files are on the CD-ROM in this book.
![]()
The "Hello, World!" ISAPI extension provides a framework for building larger extensions. When a request is issued to the "Hello, World!" extension, the extension creates a new HTML page and inserts the "Hello, World!" text into the page.
The source code for this example is shown in Listing 5.1.
Listing 5.1 "Hello, World!" Source Code
/*++
Module Name:
hello.c
Abstract:
This module is an example of the Hello World ISAPI Application.
Revision History:
--*/
#include <windows.h>
#include "hello.h"
/*++
Routine Description:
This function DllLibMain() is the main initialization function [ic:ccc]
for
this DLL. It initializes local variables and prepares it to be [ic:ccc]
invoked
subsequently.
Arguments:
hinstDll Instance Handle of the DLL
fdwReason Reason why NT called this DLL
lpvReserved Reserved parameter for future use.
Return Value:
Returns TRUE is successful; otherwise FALSE is returned.
--*/
BOOL WINAPI DllMain(IN HINSTANCE hinstDll, IN DWORD fdwReason, [ic:ccc]
IN LPVOID lpvContext OPTIONAL )
{
BOOL fReturn = TRUE;
switch (fdwReason )
{
//
// Initialize various data and modules.
//
case DLL_PROCESS_ATTACH:
break;
case DLL_PROCESS_DETACH:
break;
default:
break;
} /* switch */
return ( fReturn);
} /* DllLibMain() */
/*++
Routine Description:
This is the first function that is called when this ISAPI DLL [ic:ccc]
is loaded.
We should fill in the version information in the structure [ic:ccc]
passed in.
Arguments:
pVer - pointer to Server Extension Version Information [ic:ccc]
structure.
Returns:
TRUE for success and FALSE for failure.
On success the valid version information is stored in *pVer.
--*/
BOOL WINAPI GetExtensionVersion (HSE_VERSION_INFO * pver )
{
pver->dwExtensionVersion = MAKELONG( HSE_VERSION_MINOR, [ic:ccc]
HSE_VERSION_MAJOR );
strcpy( pver->lpszExtensionDesc,
"Hello World ISAPI Server Application." );
return TRUE;
}
/*++
Routine Description:
This is the main function that is called for this ISAPI [ic:ccc]
Extension.
This function processes the request and sends out appropriate [ic:ccc]
response.
Arguments:
pecb - pointer to EXTENSION_CONTROL_BLOCK, which contains [ic:ccc]
most of the
required variables for the extension called. In [ic:ccc]
addition,
it contains the various callbacks as appropriate.
Returns:
HSE_STATUS code indicating the success/failure of this call.
--*/
DWORD WINAPI HttpExtensionProc( EXTENSION_CONTROL_BLOCK * pecb )
{
// Create a basic HTML page
HtmlCreatePage (pecb, TEXT("Hello World Reply"));
WriteString (pecb, TEXT("Hello, World!"));
WriteString (pecb, TEXT("\r\n"));
HtmlEndPage (pecb);
return HSE_STATUS_SUCCESS;
}
//
// WriteString writes an ASCII string to the web browser
//
void WriteString (EXTENSION_CONTROL_BLOCK *pECB, LPCTSTR lpsz)
{
DWORD dwBytesWritten;
dwBytesWritten = lstrlen (lpsz);
pECB->WriteClient (pECB->ConnID, (PVOID) lpsz, &dwBytesWritten, [ic:ccc]
0);
}
//
// HtmlCreatePage adds <HTML> and a title
//
void HtmlCreatePage (EXTENSION_CONTROL_BLOCK *pECB, LPCTSTR [ic:ccc]
lpszTitle)
{
// IIS does this for us
//WriteString (pECB, TEXT("Content-Type: text/html\r\n"));
WriteString (pECB, TEXT("<HTML>\r\n\r\n"));
if (lpszTitle)
{
WriteString (pECB, TEXT("<HEAD><TITLE>"));
WriteString (pECB, lpszTitle);
WriteString (pECB, TEXT("</TITLE></HEAD>\r\n\r\n"));
}
WriteString (pECB, TEXT("<BODY>\r\n\r\n"));
}
void HtmlEndPage (EXTENSION_CONTROL_BLOCK *pECB)
{
WriteString (pECB, TEXT("</BODY>\r\n\r\n"));
WriteString (pECB, TEXT("</HTML>\r\n"));
}
This example includes two functions that are needed for any ISAPI extension: GetExtensionVersion and HttpExtensionProc.
GetExtensionVersion returns a string to the server. The string contains the ISAPI version that the extension conforms to and a short description of the extension.
HttpExtensionProc is the main processing body of the extension. The "Hello, World!" example offers simple function and writes HTML text back to the client through the use of some helper functions in the extension.
Three helper functions are included in the extension: HtmlCreatePage, HtmlEndPage, and WriteString. All of these functions use the ISAPI WriteClient function to send information back to the client that called the extension.
As with all CGI applications, ISAPI extensions must reside in directory that browsers can access and for which browsers have execute permission within that directory. Server directories can be set up through IIS Service Manager.
When IIS is first installed, the default execute directory for all CGI applications and ISAPI extensions is the \scripts directory located off of the home page directory.
For the "Hello, World!" extension to be accessed and executed, it must reside in a directory with execute permission. Put the hello.dll file in the \scripts directory or in another directory for which the browser has execute permission.
Once the server application is in a directory with execute permission, the next step is to request the extension. Since there is no fill-in form to process a client request and call the server application, we call the extension directly.
The server application can be directly accessed by using any Web browser at your disposal. To access the "Hello, World!" extension, type in the following HTTP request:
HTTP://server/scripts/hello.dll
in which the server is the URL to your Web site holding the ISAPI server, and scripts is the directory holding the "Hello, World!" extension.
When it gets the HTTP request for the "Hello, World!" extension, the ISAPI server loads the extension into memory and returns an HTML page with the "Hello, World!" string inserted on it. Figure 5.2 shows a successful call to the "Hello, World!" extension.
A successful call to the "Hello, World!" ISAPI extension.
Congratulations! You have just built, installed, and requested your first ISAPI server application!
This chapter introduces you to the world of ISAPI extensions. You learn what ISAPI extensions are and how they can add dynamic capabilities to your Web site.
You also see why ISAPI extensions are effective replacements for CGI applications. The "Hello, World!" extension shows you how extensions are built, installed, and called.