How To: Creating ISAPI Applications

Posted: (EET/GMT+2)

 

How To: Creating ISAPI Applications

Level: Intermediate


With Delphi 3, every Object Pascal developer is now able to create DLLs which run as part of the Microsoft Internet Information Server (IIS). Such DLLs are created using the Information Server API, or ISAPI for short.


The problem with CGI applications

If you are a Web-developer, you have without doubt heard of CGI, and possibly about Win-CGI applications. CGI, or Common Gateway Interface, is a method in which the WWW-server is configured to run an application when the surfer requests a certain URL from the server. The CGI application can then do anything it wants, for example, access a database and return the results of a query in a nice, user-friendly format.

However, the problem with CGI applications is that every time a surfer request the services of a CGI app, it must be loaded into memory from disk. With large programs, this can be a major concern. This is where ISAPI DLLs come in. Because you can create your program as a DLL, IIS loads your DLL on the first request, and then keeps it in memory. This is much faster than the CGI's way of doing things.


Creating a bare-bones DLL

Start by choosing New from Delphi's File menu, and select DLL. You will see a skeleton of a DLL, but you can remove almost everything generated by Delphi. Just make sure you include the unit ISAPI2 in the Uses clause.

An ISAPI DLL requires three entrypoints, which are predefined by Microsoft. These are GetExtensionVersion, TerminateExtension, and HttpExtensionProc. Of those, the second one is not absolutely required, but it is recommended that you include it, as future versions of IIS's might require it.

GetExtensionVersion is a simple function which returns the version of the extension, and TerminateExtension simply returns a value indicating whether it is OK for IIS to unload your DLL. You should always return an OK status from this function.

What makes a ISAPI DLL tick is the HttpExtensionProc. This function receives an "extension control block" parameter from IIS. This record contains information about the HTTP request, and most importantly, addresses to read/write and status functions, which the extension is allowed to call.

For example, if the DLL wants to write out some HTML code, it must do so using the WriteClient function. However, the address of this function is not known a compile-time, so your DLL must use the given function pointer to call it.


How to make the DLL return HTML code

Ultimately, your DLL must return at least something to the user. This text can be a static HTML page, but the reason DLLs are created is that they can return a dynamic page. For example, this page could be a list of records in a database table. 

    Function HttpExtensionProc(Var ECB : TExtension_Control_Block) : DWord; StdCall;
Var
  S     : String;
  Bytes : Integer;

Begin
  S := '<HTML><BODY>'#13#10+
       'Hello from an ISAPI DLL!<P>'#13#10+
       '</BODY></HTML>';
  Bytes := Length(S);
  ECB.WriteClient(ECB.ConnID,PChar(S),Bytes,0);
  Result := hse_Status_Success;
End;
Above, you can see a very simple HttpExtensionProc. It only returns three lines of text using the WriteClient function, but as said, the text you return can be anything.


Configuring IIS to accept your DLL

After you have created and compiled your DLL, you must configure IIS to accept it. This is quite easy, because IIS is configured correctly by default. On the other hand, if you have changed your settings, making everything work requires only a couple of minutes.

First, start Internet Service Manager by choosing Start/Programs/Microsoft Peer Web Services/ Internet Service Manager (ISM).


    The Internet Service Manager main window.



Next, make sure your WWW service is running, so that you can change its properties. To do so, select the WWW service and press the "Play" button. Then just double-click the service name.


    The WWW Service Properties dialog.



The Properties dialog box opens. From here, take a note of the directory path to the virtual Scripts directory. By default, IIS allows you to run your ISAPI applications if you place them in the Scripts directory.

Now all you have to do is copy your DLL to the Scripts directory. Then you are ready to fire up your browser. This is what the result will look like in Netscape:


    The sample ISAPI DLL running.




Conclusion

Now you should have at least somekind of knowledge to write ISAPI DLLs. As you have seen, there is nothing special in this process. For example, it is very easy to add a datamodule to your project, and then make the DLL return any data from your database. Also, you can easily process forms, and the like -- imagination is your limit!

However, to bring you back to Earth, you must understand that you will quickly run into problems that have to do with concurrency. However, I won't be giving information about the solutions out (sorry), but I must tell you one thing: I'm currently solving these problems for money... ;-)