MFC ISAPI Extensions Hit Light Speed, Part 1

Part 1: Creating ActiveX forms on the Web

You've encountered them many times on the Web--those ubiquitous onlineforms. Home pages feature a variety of such forms for comments and suggestions,order processing, username validation, questionnaires, and searches, to mentiona few. Online forms can fulfill each of these requests. Although such forms canalso take time to process and add to the load on your Web server, with the righttools, you can create forms that don't drain your system.

With Windows NT Server and Microsoft's Visual C++ (VC++) 4.1, you can useInternet Server Application Program Interface (ISAPI) Extensions that will makeyour online forms move at light speed. Unlike forms you create with Perl orshell programming, forms based on ISAPI Extensions can improve NT Server'sperformance and are easy to create using the ISAPI Extension Wizard in the VC++Microsoft Foundation Classes (MFCs). The Wizard walks you through creating anISAPI Extension, a framework based on new MFC ISAPI Extension classes. TheWizard gives you easy programming, debugging, and maintenance all in oneapplication.

To create ISAPI Extensions, you need Hypertext Transfer Protocol (HTTP)server software, VC++ 4.1, and a Common Gateway Interface (CGI)-compatible Webbrowser such as Internet Explorer (IE) or Netscape. The latest MicrosoftDeveloper Network (MSDN) CD-ROM is also helpful for reference, but not required.

This how-to article explains the process of creating a custom ISAPIExtension with the MFC Wizard. You first need to understand CGI, how to create aform with Hypertext Markup Language (HTML) to call the ISAPI Extension, and howto create an ISAPI Extension for your form. Then, you can walk through using theWizard to create the base implementation for an ISAPI Extension. A follow-onarticle will cover additions to the Wizard-generated ISAPI Extension that youneed to produce and process an online form.

Beyond the Gateway
As Web traffic increases, so does the demand for fast and efficientprocessing. ISAPI Extensions can speed up your online forms to meet this demand.

All online forms require CGI. When you select Submit on a form, you triggera CGI request to an HTTP server. The server uses a CGI program to process theCGI request and sends the output back to your Web browser. In turn, your browserinterprets the HTML and displays the results as a Web page.

On an NT server, ISAPI Extensions allow speed and efficiency that blow awayother CGI programs' performance. At the heart of the efficiency is howMicrosoft's Internet Information Server (IIS) uses NT's threading technology andDLL capabilities. Threading increases the server's efficiency: Creating a newthread requires far less system resource than creating a new process, which iswhat traditional CGI does.

ISAPI Extensions are DLLs loaded into the site's IIS process on demand orat server startup. IIS uses threading to speed up CGI requests to an ISAPIExtension. The server creates a new thread for each CGI request, so the servercan handle more than one CGI request at a time.

To handle specific CGI requests, you write a two-line CGI-request tomethod-name a parse map. The parse map specifies a class-method name youmust add to the class the Wizard creates for you. Then, in the online form, youreference the ISAPI Extension filename and class-method name as the form'saction. To illustrate this process, let's look at an example.

Creating a CGI Form
The first step in using an ISAPI Extension to generate and process an onlineform is to prepare the form's HTML. Let's consider an online form that solicitsa comment or suggestion, such as the form in Screen 1.

On the form, you can fill in your name, email address, and comment orsuggestion. After you click either Comment as in Screen 2, or Suggestion, youselect Send to submit your comment or suggestion to the home page's owner or Webmaster.

When you click Send, you trigger the CGI program associated with the form.Then, as Screen 3 shows, the CGI responds by generating another Web page toconfirm receipt of the comment or suggestion. A link on this page connects toanother Web page which you see in Screen 4. It lists all comments andsuggestions, including any you just submitted.

Listing 1 shows the HTML code for the sample comment and suggestion form.The title and header are the first two lines of code. The title, Commentsand Suggestions, appears in the browser title bar, and the header, Commentand Suggestion Fill-out Form, appears at the beginning of the page in thebrowser. (The code for this example is on the Windows NT Magazine Website at www.winntmag.com.)

The form body is standard HTML. The two input fields are WHOISIT, whichappears next to Your Name:, and EMAIL, which appears next to Youremail address:. The form's default value for Your Name: isAnonymous, and the default for Your email address: [email protected].

The form has two mutually exclusive radio buttons, Comment or Suggestion.The CGI request sends a value of 1 for Comment and a value of 0 for Suggestion.The form initially appears with Comment selected. Then, a multiline, text typefield, WISEWORDS, appears below the text, Words of Wisdom:. The fieldhas five rows and 80 columns. Finally, you see two unnamed (because they are noton the command line) buttons: a submit button with a value of Send and a resetbutton with a value of Clear.

The form's first line has the directives ACTION="comment.dll?postComments"

METHOD="POST". The ACTION keyword specifies theCGI script (ISAPI Extension) to execute. You specify the ISAPI Extension ascomment.dll, place a separator ?, and specify the name of the class-method(postComments) that will process the form. (This syntax is specific to MFCimplementation of ISAPI Extensions.)

In addition to the first directive, the MFC Wizard-generated ISAPIExtension requires the METHOD="POST" directive. ThePOST method lets the ?postComments portion pass to the ISAPI Extension intact sothat MFC knows which class-method to call.

MFC ISAPI Wizardry
After you prepare the HTML for the form, you need to create the ISAPIExtension with the Visual C++ ISAPI Extension Wizard. Start Visual C++, selectthe File menu, and click New. Double-click the Project Workspace option. TheNew Project Workspace dialog displays. From the Type list, select ISAPIExtension Wizard. Type comment as the name of your project in the Name text box,as you see in Screen 5. Click Create. The ISAPI Extension Wizard - Step 1 of1 dialog appears, as in Screen 6.

Select Generate a Server Extension object to specify that you wantan MFC-generated class--an ISAPI Extension--to handle ISAPI Extension-CGIrequests. You can also select Generate a Filter object, for filteringall HTTP requests, including CGI requests, coming into the IIS HTTP Server.Among the many uses for these requests are providing better or custom logging,security, and maintenance. Click Finish. The New Project Informationdialog displays, as Screen 7 shows. Click OK to complete the task.

Now compile the DLL, and copy it to the wwwroot directory in which yourIIS is installed. Then, start IE, Netscape, or any other CGI-compatible browser.Type in the Web address yourmachinename/comment.dll? to run the CGI ISAPIExtension (the question mark tells the HTTP server that you're using a CGIprogram).

The Wizard will generate the message, "This default message wasproduced by the Internet Server DLL Wizard. Edit yourCCommentExtension::Default() implementation to change it." To beginmodifying the code, edit the comment.cpp file. Find theCComentExtension::Default method, and change it to match Listing 2. This changecauses the DLL to display "Hello World" instead of "This defaultmessage was produced...".

To add commands that the ISAPI Extension can handle, you must include newmethods and add a few lines to the parse map at the beginning of the comment.cppfile. (For more information about parse maps, see the MSDN CD, an optional, buthighly recommended tool. Search on ISAPI Extensions and Parse Maps,or go to Visual C++ BooksMFC 4.1Programming with MFC: EncyclopediaInternetServer API (ISAPI) ExtensionsISAPI Extensions: Parse Maps.)

Before you can debug your ISAPI Extension, you have to stop the WWW, FTP,and Gopher services. You can stop these services through the Internet ServiceManager (inetsrvadmininetmgr.exe) or through the Services Control Panel.

The next step is to debug your ISAPI Extension. To test the ISAPIExtension, click Build, and open the Setting dialog. Select the Debug tab. Thenin the Executable for debug session text box, type the path toINETINFO.EXE. In the Program arguments text box, type -e W3Svc. Also, goto the Link tab, and set the Output file name to point to the wwwroot directoryfor IIS (for example, activexinetsrvwwwrootcomment.dll).

For more information about debugging an ISAPI Extension, see TN063:Debugging Internet Extension DLLs on the MSDN CD. You can also connect toURL: rampages.onramp.net/~steveg/eyesapi.html for the useful EyeSAPI test tool,which emulates ISAPI Extension--CGI requests from an IIS HTTP server.

The Next Step
Now that you've created an example form and used the Visual C++ ExtensionWizard to create a basic ISAPI Extension, you can create the additions theWizard-generated ISAPI Extension needs to produce and process the example form.The next article describes what additions you need and how to create them.

LISTING 1: Example Form HTML

Commentand Suggestion Fill-out Form

"comment.dll?postComments" METHOD="POST">
Your Name:"WHOISIT" VALUE="Anonymous" SIZE=16 MAXLENGTH=64>
Your email address:"EMAIL" VALUE="[email protected]"SIZE=21 MAXLENGTH=64>

"radio"NAME="COMMENT" VALUE="1"CHECKED> Comment
"radio"NAME="COMMENT" VALUE="0">Suggestion

Words of Wisdom:

"</b>WISEWORDS<b>"</b>ROWS=5 COLS= 80>

"submit"VALUE="Send">
"reset" VALUE="Clear">

LISTING 2: Modifying the comment.cpp file
void CCommentExtension::Default(CHttpServerContext* pCtxt)
{
StartContent(pCtxt);
WriteTitle(pCtxt);
CString strOutput;
strOutput = "Hello World!";
*pCtxt << strOutput;
EndContent(pCtxt);
}