If you need Web speed, you need Internet Server API (ISAPI) Extensions. An ISAPI Extension DLL lets you replace the slow and resource-hogging Common Gateway Interface (CGI) for such purposes as processing fill-in forms. As Part 1 of this series (October 1996) explained, CGI scripts and executables run in a separate process space. ISAPI runs in the same process space as the HTTP server, so ISAPI allows faster startup and communication than other types of CGI. In addition to faster connections, ISAPI increases the speed of Microsoft's Internet Information Server (IIS) because with ISAPI, IIS can use threading to process more than one request at a time.
To create an ISAPI Extension, you can start from scratch or simply use the Microsoft Foundation Class (MFC) ISAPI Wizard. If you choose MFC wizardry, you'll finish very quickly. In addition, you can use the methodology this article presents to create functional ISAPI Extension CGI replacements quickly and consistently. You'll need IIS or another ISAPI HTTP server installed on a Windows NT server, Microsoft Visual C++ 4.1 or later, and a CGI-compatible Web browser, such as Internet Explorer or Netscape.
Part 1 showed how to create an ISAPI Extension that responds to a fill-in form. The code did not do anything except display a default message. This article shows how to modify an ISAPI Extension that the MFC Wizard generates. I cover the Wizard-generated ISAPI Extension additions you need for the example form in Part 1. The additions let you initially display the Comment and Suggestion form shown in Screen 1 as the default and display the second page with the return email address and link to the all-records page. The HTML that produces the Comment and Suggestion fill-in form is in Listing 1.
ISAPI Wizardry Revisited
After you prepare the HTML for the fill-in form, as in Listing 1, create an
ISAPI Extension with the Visual C++ ISAPI Extension Wizard. The Wizard creates
an ISAPI Extension with the entire MFC ISAPI framework, but little else. We'll
extend this framework to display the Comment and Suggestion form shown in
Screen 1 and handle the CGI request generated when a user enters a comment (as you see in Screen 2) and clicks Send on the form.
To generate the initial ISAPI Wizard, start Visual C++, select the File menu, and click New. Double-click the Project Workspace option. The New Project Workspace dialog appears. From the Type list, select ISAPI Extension Wizard. In the Name text box, type comment as the name of your project. Click Create to pull up the ISAPI Extension Wizard - Step 1 of 1 dialog you see in Screen 3. Select Generate a Server Extension object to specify that you want an MFC-generated class--an ISAPI Extension--to handle ISAPI Extension, or CGI, requests. Click Finish to display the New Project Information dialog. Click OK to complete the task.
Modifying the MFC Wizard ISAPI Extension
So let's walk through a simple, standard methodology to finish the ISAPI
Extension created in Part 1 of this series. The ISAPI Extension will display the
Comment and Suggestion form for a URL that points to the ISAPI Extension with no
arguments (http://spain.winntmag.com/comment.dll?). You must add a method,
postComments, to the class created by the MFC Wizard, CCommentExtension, to
process the values passed to the ISAPI Extension DLL when someone selects Send
on this form. Listing 2 shows the prototype for the
CCommentExtension::postComments method.
The MFC ISAPI framework uses a CGI request-to-method parse map to determine which method of the CCommentExtension class to call and how to map the CGI-request named values to the method's parameters. To set up the parse map for the comment and suggestion form, add the two lines in Listing 3 to the parse map at the top of the comment.cpp file. The parse map, an MFC addition, maps the parameters of a specific method of the CComment Extension class(e.g., LPTSTR whoIsIt) to the named values (e.g., INPUT NAME= "WHOISIT") sent from the fill-in form. The first parse map entry line, ON_ PARSE_COMMAND macro, specifies the method name (postComments), the class (CCommentExtension), and the data type of each of the class method's parameters. The second line specifies the named values passed from the form to the ISAPI Extension. These values correspond to the class method's parameters specified in the first macro. For example, the first parameter for the postComments method is LPTSTRwhoIsIt. In the first macro, ITS_PSTR (a string type) is the type for LPTSTR whoIsIt. In the second macro, WHOISIT is the named value associated with this parameter. MFC uses this parse map to associate incoming form data (named values) with parameters to pass to class methods.
Before we add the postComments class method, we need to store and read long strings of HTML code. More specifically, we want to store as a resource the initial form and portions of the results page that the postComments method generates. Visual C++ 4.1 includes the WWW QUOTE example, which illustrates how to create a new custom resource type for HTML code. To simplify the process of loading long HTML strings from resources, we'll borrow some code and techniques highlighted in the WWW QUOTE example.
First, incorporate two class methods from this example into your ISAPI Extension class: Copy the WritePage Title and LoadLongResource methods from the WWWQUOTE example and change the class names from CWWWQuote to CCommentExtension to match your class name in the method declarations and definitions. You'll use this codelater in this example for reading whole HTML pages from custom HTML resources. You can put this code into a separate file and call it helper.cpp for future use in other ISAPI Extension projects.
Now, go to the ResourceView tab on the project workspace window to create a new custom resource. Select Comment resources, click the right mouse button to get a pop-up menu, and select Insert to display the Insert Resource dialog. Select Custom to display the New Custom Resource dialog. Type HTML, and select OK as shown in Screen 4. Your new resource, HTML, is shown in Screen 5.
Get the HTML code into a resource that you will use to display the full comment and suggestion form: Copy all the HTML code in Listing 1 into the comment.htm file. Now select Comment resources again, click the right mouse button, and select Import to display the Import Resource dialog. Select the file comment.htm, shown in Screen 6, and click OK to bring up the Custom Resource Type dialog shown in Screen 7. Select the HTML resource, and click OK. Screen 8 shows that you have imported the file, idr_html2, into the project as an HTML custom resource that you can edit.
Now change the resource ID to something more meaningful. Select idr_html2, click the right mouse button, and select Properties to display the Custom Resource Properties dialog shown in Screen 9. Select the ID: field, and change the ID to idr_html_comment_form.
To store resources for the two pages that result from clicking Send, you'll need to create two other HTML files and the custom HTML resources for them. Listing 4 shows two HTML strings. Copy the first HTML string into a file named comsent.htm and the second into sugsent.htm. Use the technique described above to import these two other HTML files as custom HTML-type resources (idr_html_comsent_form and idr_html_sugsent_form). Next, add the resources (HTML titles) shown in Table 1 to the string table resource shown in ResourceView.
Now you're ready to add a few bits of code to make this methodology work. First, change the code in the CCommentExtension::Default method to match Listing5 to display the comment and suggestion form by default. When a user enters the URL http://your machine/comment.dll?, the Comment and Suggestion form is displayed.
This routine writes the form title by calling the WritePageTitle() method and then uses the custom HTML resource idr_html_comment_form to call the LoadLongResource() method to load the HTML fill-in form. You also see calls to the StartContent() and EndContent() methods at the beginning and end of this routine. The calls write out the initial CGI line that specifies content type (Content-Type:text/html\r\n) and the end of the HTML (</body></ html>), respectively. For the CCommentExtension::postComments to process the CGI request that the form will produce, you need to add the code in Listing 6.
The postComments method calls the WritePageTitle() method to create the title and then calls the LoadLongResource() method to load the HTML. You see the same technique in the CCommentExtension::Default method (shown in Listing 5 on page 108) to create the HTML for the title and body. The postComments method checks whether this form request was for a comment or a suggestion and sets the two resource IDs for the call to the WritePageTitle() method. The HTML and string-table resource entries for these two resource IDs use the word comment or suggestion to correspond with the button selected.
Once you compile, you've completed the basic tasks for modifying the MFC Wizard-generated ISAPI Extension. Your ISAPI Extension will now display and process the Comment and Suggestion fill-in form.
Adding Complexity to Your Code
Now if you want to try a more complicated extension, you can add a hyperlink
to a page with all the comments and suggestions. Let's add a new method,
AppendToAllReceivedPage(). This method appends the response page to the end of
the All Received HTML file with all the comments and suggestions your
ISAPI Extension DLL has received so far. You'll hyperlink this All Received
HTML page to the HTML that is loaded in postComments, as shown in Screen 10. If
surfers click the hyperlink, they'll see the entire page of comments and
suggestions, as shown in Screen 11.
You add the call to this method, shown in Listing 7 (on page 108), at the end of the postComments method. Make certain that two CGI requests do not try to write to the file at once. Two CGI requests can occur simultaneously because IIS can process more than one request asynchronously by creating a separate thread for each CGI request. Two or more threads attempting to write to the same file at the same time might result in garbled text in the file at the very least. Listing 8 ensures that only one thread executes the code at a time. If a thread is in the middle of this method and a second thread starts to execute it, the second thread hits the EnterCriticalSection() function and waits until the first thread passes the LeaveCriticalSection() function before the second thread can continue.
To allow multithreaded access to the All Received HTML file, you must set up two variables, g_fptr and g_Critical Section, during initialization in the object's constructor method (CComment Extension::CCommentExtension). You use these variables to access the file (g_ fptr) and protect the code that writes to the file (g_CriticalSection). Likewise, when your object is destroyed, you need to clean up by deleting these variables in the object's destructor (CComment Extension::~CCommentExtension). Listing 9 (on page 108) shows the constructor and destructor for the CComment Extension class.
Wrapping It Up
You've modified an ISAPI Extension to append to the All Records
HTML file--and in a safe way. The ISAPI Extension also provides a hyperlink to
this page in its reply to the form request. You can compile this ISAPI
Extension, copy it into the \wwwroot directory, and run a browser with the URL
http://yourmachine/comment? to see it in action, as in Screens 1, 2, 10, and 11.
You can use the example you just completed as a guide for further extensions. ISAPI Extensions are easy to write, extend, and maintain. Try adding another object class method, writing an HTML file with a fill-in form that references the new class method as the default did (dll?method), and experiment. It's a snap!
