Click here to Skip to main content
15,903,175 members
Articles / Programming Languages / C++

What is an ISAPI Extension?

Rate me:
Please Sign up or sign in to vote.
4.93/5 (60 votes)
4 Oct 2001CPOL15 min read 505.5K   3.4K   133   67
Discusses ISAPI extensions in detail and shows how to implement an extension to validate a given credit card#.


Unless you have been a caveman, you have seen a number of web sites that whenever is browsed, the navigation ends up to a DLL file residing in a scripting directory of that dominium! Something like the following pseudo URL:


What does this DLL suppose to do and what does it have to do with today's paper?

These DLLs are created using the Internet Server API, or ISAPI for short. ISAPI is developed to provide a benefit or two, over the shortcomings of Common Gateway Interface, CGI. Although we surprisingly experience new web sites developed exclusively by CGI scripts nowadays, however, ISAPI DLLs have got something to offer that CGI could never bring us this way or that way.

I am going to start off this paper by describing the underlying details that any ISAPI programmer has to know, to be able to develop a better ISAPI extension. From then on, I will go through a development of a useful ISAPI extension step by step. The extension is supposed to validate a given credit card. Yeah! This is also my answer to those people who asked me the algorithm involved validating a credit card over and over again. Gotta go!

What is ISAPI?

Internet Server Application Programming Interface (ISAPI), is an API developed to provide the application developers with a powerful way to extend the functionality of Internet Information Server (IIS). Although ISAPI extensions by no means are limited to IIS, they are extensively used in conjunction with MS-IIS.


Developing a CGI program involves creating an EXE with C, C++, and/or Perl programming languages. This EXE file will be executed and terminated for every request received, causing an excessive memory usage, whenever users hit the same page over and over again!

This excessive memory usage that could bring the server completely down, has been solved under ISAPI extensions. An ISAPI extension is a regular DLL file that exposes 3 special functions that is called by the calling process (i.e., IIS) and therefore, will be loaded to memory once, no matter how many clients are going to use it at the same time. (It would be a good idea if you could take a look at a reference, to see how memory management is done under Windows 2000. The Visual C++ 6.0 Bible, Chapter 18, The Memory Management, describes it well!)

ISAPI fundamentals

Since the ISAPI extension and the calling process (IIS) live at the same address space, they could contact each other, directly. This means a great potential to bring the whole IIS down, and in some cases, the entire web server! Take a look at the following figure:

Image 1

You see whatever problem your extension encounters, it could affect the entire web server process, if it's not handled properly. As illustrated above, communicating between the extension and IIS is done via a pointer to a structure of type ECB, or Extension Control Block that is declared as follows:

   DWORD     cbSize;                 // size of this struct.
   DWORD     dwVersion;              // version info of this spec
   HCONN     ConnID;                 // Context number not to be modified!
   DWORD     dwHttpStatusCode;       // HTTP Status code
   CHAR      lpszLogData[HSE_LOG_BUFFER_LEN];// null terminated log info

   LPSTR     lpszMethod;             // REQUEST_METHOD
   LPSTR     lpszQueryString;        // QUERY_STRING
   LPSTR     lpszPathInfo;           // PATH_INFO
   LPSTR     lpszPathTranslated;     // PATH_TRANSLATED

   DWORD     cbTotalBytes;           // Total bytes indicated from client
   DWORD     cbAvailable;            // Available number of bytes
   LPBYTE    lpbData;                // pointer to cbAvailable bytes

   LPSTR     lpszContentType;        // Content type of client data

   BOOL (WINAPI * GetServerVariable) (HCONN hConn,
   LPSTR      lpszVariableName,
   LPVOID     lpvBuffer,
   LPDWORD    lpdwSize );

   BOOL (WINAPI * WriteClient)  (HCONN ConnID,
   LPVOID     Buffer,
   LPDWORD    lpdwBytes,
   DWORD      dwReserved );

   BOOL (WINAPI * ReadClient)  (HCONN ConnID,
   LPVOID     lpvBuffer,
   LPDWORD    lpdwSize );

   BOOL (WINAPI * ServerSupportFunction)( HCONN hConn,
   DWORD      dwHSERequest,
   LPVOID     lpvBuffer,
   LPDWORD    lpdwSize,
   LPDWORD    lpdwDataType ); 


Whatever information either the calling process or the extension wants to pass to the other, is done through this control block. We will shortly have a look at this ECB structure. For now, let's see how IIS works in conjunction with your extension, to serve the visitor of your web site.

Whenever an extension is accessed (e.g., & Tx=870250AZT6), IIS checks to see whether the example.dll is loaded into memory. If it is not, then it initiates the loading process. Once the DLL is loaded into memory, a worker thread starts running to manage our extension, and thereafter the entry point (DLLMain function) is called. When the DLLMain finishes, the server makes a call to GetExtensionVersion function to perform two tasks:

  1. Exchange version information
  2. Get a short text description of the extension

The server then calls the HttpExtensionProc function passing a copy of the ECB's pointer to start the actual ISAPI extension. This is the function that makes writing data back to the client, possible! We will examine this, shortly.

The third and the last entry point in an ISAPI extension DLL is the TerminateExtension function that is called whenever the extension is going to be unloaded from the memory. All the cleanup code can be done in this function.

In brief, an ISAPI extension is a regular DLL that exposes 3 functions to interact with the server:

  1. GetExtensionVersion
  2. HttpExtensionProc
  3. TerminateExtension (optional)

Having this information in hand, let's start with the DLLMain, the entry point of any DLL!

DLLMain, the entry point

As indicated by Microsoft, "the DllMain function is an optional entry point into a dynamic-link library (DLL). If the function is used, it is called by the system when processes and threads are initialized and terminated, or upon calls to the LoadLibrary and FreeLibrary functions", that is prototyped as follows:

BOOL APIENTRY DllMain(HANDLE hModule, DWORD dwCallReason, 
                                            LPVOID lpReserved);

If you provide your extension with this function, it will be called upon the initialization and the termination process of your extension. The state is indicated by the dwCallReason parameter that could be one the following predefined values:


Describing each of these parameters in detail is beyond the scope of this paper, so I simply refer you to Microsoft's Developer Network to read more about this function.

Anyhow, we could save the hModule parameter for later use in our extension (if this suites us) and simply return TRUE from this function. We usually do not have anything to do in this function, while developing an extension!

GetExtensionVersion, the actual entry point

This function is actually the first entry point that is called by IIS to determine the information about the extension. To understand this better, let's have a look at it's prototype:

BOOL WINAPI GetExtensionVersion(HSE_VERSION_INFO *pVer);

Upon the activation of this function, we are supposed to fill out the extension information within the pVer parameter passed to the function. This pointer is of type HSE_VERSION_INFO that is declared as follows:

typedef struct _HSE_VERSION_INFO
   DWORD dwExtensionVersion;
   CHAR lpszExtensionDesc[HSE_MAX_EXT_DLL_NAME_LEN];

where dwExtensionVersion is the extension version and lpszExtensionDescription is the description of the extension. If we return TRUE from this function, we notify IIS that our extension is ready to be used. Otherwise, IIS will not use the extension.

HttpExtensionProc, the main entry point

The amazing part of any ISAPI extension starts when the extension procedure (HttpExtensionProc) is called. As far as you could remember, this is the procedure that makes writing data back to the client possible! To see how this happens, lets start by having a look at the prototype of HttpExtensionProc:


where pECB is a pointer to an extension control block, that makes the intercommunication between the server and the extension possible. You decide what the web page should contain and how to present it to the user in this entry point. But how?

Do you recall the members of the ECB's structure? ECB contains a method, prototyped as follows:

BOOL WriteClient(HCONN ConnID, LPVOID Buffer, LPDWORD lpdwBytes, 
                                                        DWORD dwSync);

Using this member function, you can send the data present in the given Buffer to the client that is identified by its ConnID, the one that made the request. For example, to send A BIG RED ROSE to a client, you could simply make the following calls:

char szBigRedRos[] = 
  "<font color='#FF0000' size='3'><b>A BIG RED ROSE</b></font>";
DWORD dwSize = strlen(szBigRedRos);
pECB->WriteClient(pECB->ConnID, szBigRedRose, dwSize, 0);

Neat, huh? I think you already have got the minimum underlying knowledge to develop your first ISAPI extension. So, let's start...

Project requirements

  1. A little bit patience!
  2. MS-VC++ 6.0+ compiler
  3. MS-Windows 2000 Advanced Server with MS-IIS installed
  4. A web browser


We are going to develop a non-MFC ISAPI extension, using plain Win32 API calls that is supposed to validate a given Master Card. We name the extension validate.dll and it simply writes the client a string telling the client, whether the given credit card number is valid. Of course, we should examine what happens if a user wants to browse the page through the following URL:




or some sort of such invalid URLs, of course, from the purpose of our extension's view (these URLs are valid for your browser, though!).

In such circumstances, we simply echo the following text to the client: What you have entered is an invalid Master Card #.

And that's all what our extension does!

Why not MFC?

Although MFC amazingly simplifies the parsing process of query strings, it will dramatically increase the file size of our extension! On the other hand, if you know the subtle nuance of a non-MFC extension, you are a step further towards creating a better MFC extension. So, I decided to avoid using MFC for our first ISAPI extension.

Luhn algorithm

Now, the question is how can we check whether a given credit card number is valid. The algorithm involved in this checking is called Luhn algorithm (AKA Sum10 algorithm, AFAIK). Consider a number, say, 5168254236021548. To understand if this is a valid cc#, you should follow 4 easy guidelines:

  1. Starting from the leftmost digit, we simply multiply alternating numbers by two. i.e., we multiply shown bold numbers by two:
    5 * 2 = 10
    6 * 2 = 12
    2 * 2 = 4
    4 * 2 = 8
    3 * 2 = 6
    0 * 2 = 0
    1 * 2 = 2
    4 * 2 = 8
  2. Add the separate digits of all the products, as follows:
    1 + 0 + 1 + 2 + 4 + 8 + 6 + 0 + 2 + 8 = 32
  3. Add the unaffected digits to the product, i.e.,
    1 + 8 + 5 + 2 + 6 + 2 + 5 + 8 = 37
  4. Add the result of the step 2 and 3 and divide it by 10
    32 + 37 = 69
    69 % 10 = 9
  5. If the answer is 0, this is a valid cc#, otherwise, it is not!

So 5168254236021548 is an invalid cc# (since 69 % 10 is 9 not 0).

Further checking

Having completed the Luhn checking, we could go a step forward by checking the type of the CC, according to the following table:

Credit CardPrefixLength (digits)
Master Card51-5516
VISA413, 16
American Express34, 3715

However, for our example, we just assume that the given cc# is a Master card, so we check the card against the conditions for Master Cards, i.e., we could simply check if the given number has got 16 digits. If it's not, we simply echo that the give number is not a valid Master card number. You could extend the functionality, if you want.

How to implement Luhn checking in C?

Here, I've tried to program a procedure so that it simply returns 0 if the given string is a valid Master Card#. Otherwise, it will return a non-zero number indicating the error code:

#define ERR_NOT_A_MASTERCARD         2
#define ERR_INVALID_CC               3
#define ERR_INVALID_INPUT            4

BYTE CheckCC(const char *pszNumber)
  if(strlen(pszNumber) != 16)

  for(int i = 0; i < 16; i++)
      return ERR_INVALID_INPUT;

  if(pszNumber[0] != '5' || pszNumber[1] < '1' || pszNumber[1] > '5')

  int nSum;
  for(i = 0, nSum = 0; i < 16; i += 2)
    int nDigit = (pszNumber[i] - 48) * 2;
    nSum += (nDigit < 10 ? nDigit : nDigit / 10 + nDigit % 10) 
                + (pszNumber[i + 1] - 48);

  if(nSum % 10)
    return ERR_INVALID_CC;

  return 0;

And therefore, checking a master card is simply calling the following function:

BYTE byRet = CheckCC("1269875230210254");
  //this is a valid master card #
  //An invalid master card#, byRet shows the error code!

Starting our extension

With this information in hand, it's now time to develop our ISAPI extension. Launch your VC++ compiler. From the File menu, select the New command. Having the Projects tab selected, left-click on Win32 Dynamic-Link Library. Within the Project Name space, type validate and click ok to continue. Within the Win32 Dynamic-Link Library box, select the second option, A simple DLL project and press the Finish button. At this point, we've got a DLL project ready to be implemented.

Since we are not interested either in ul_reason_for_call or hModule parameters, we skip them simply and we just return TRUE in this entry point. So we have got the DllMain function implemented as follows:

       DWORD ul_reason_for_call, LPVOID lpReserved)
   return TRUE;

Now, let's gear from DllMain to the first actual entry point, GetExtensionVersion. As far as you could remember, we have to implement this function in order to serve two things described before. So let's add it to our project:

   pVer->dwExtensionVersion = HSE_VERSION;
      "Validate ISAPI Extension", HSE_MAX_EXT_DLL_NAME_LEN);
   return TRUE;

where HSE_VERSION is defined in the httpext.h header file as follows:


So add the mentioned header file to the top of the validate.cpp file. Pay a close attention, please! We return TRUE to indicate that IIS is permitted to run our extension!

What's next, then? It's now time to find a way to get the query string back from IIS. But how? You probably remember that IIS can communicate with our DLL through the ECB's pointer, passed as the only parameter to the HttpExtensionProc function:


where pECB contains a data member, say, lpszQueryString, that points to the query string. In other words, if the user tries to access our validate.dll via the URL, pECB->lpszQueryString is equal to 12345, the string followed by the ? mark.

Another thing we should overcome before going on, is to learn how we could use pECB to echo a string (including HTML, JavaScript and etc.) to the client. This is done via the WriteClient method of the ECB block, which is prototyped as follows:

BOOL (WINAPI *WriteClient)(HCONN ConnID, LPVOID Buffer, 
                            LPDWORD lpdwBytes, DWORD dwReserved);

where ConnID is the connection identifier of the client to which the response data should be sent, Buffer points to the data to be sent, lpdwBytes is the length of the mentioned Buffer, and dwReserved as it sounds, is reserved.

With this information in hand, let's implement our HttpExtensionProc:


   BYTE byRet = CheckCC(pECB->lpszQueryString);
      //this is a valid master card, echo a suitable string to the client
          "<p><b><font face='Verdana' 
          "</b></p><p><font size='2' face='Verdana'>");
          "%s is a valid master card #</font></p>\r\n", 
      //this is an invalid master card, echo a proper string to the client!
          "<p><b><font face='Verdana' 
          "<p><font size='2' face='Verdana'>What you have entered is an ");
          "invalid master card#</font></p>\r\n");



And what about StartContext, EndContext, and WriteContext functions? WriteContext is a function to simplify the process of echoing a string to the client, implemented as follows:

void WriteContext(EXTENSION_CONTROL_BLOCK *pECB, char *pszFormat, ...)
   char szBuffer[1024];
   va_list arg_ptr;
   va_start(arg_ptr, pszFormat); 
   vsprintf(szBuffer, pszFormat, arg_ptr);

   DWORD dwSize = strlen(szBuffer);
   pECB->WriteClient(pECB->ConnID, szBuffer, &dwSize, 0);

This way, we don't need to pass the length of the string or other non-useful information over and over again, while echoing a string. Moreover, we could use it like the MFC's CString::Format(...) function, for example:

WriteContext(pECB, "5 + 6 = %d", 5 + 6);

that echoes the 5 + 6 = 11 string to the client.

On the other hand StartContext is provided to echo necessary heading or startup HTML code to the client. It's counterpart, EndContext, also echoes the footer to the client:

   WriteContext(pECB, "<html>\r\n<body>\r\n");

   WriteContext(pECB, "</body>\r\n</html>");

Now set the active project configuration to Release mode and compile the program. It is now time to see how to install and use our extension.

Assuming you are running Windows 2000, select the Internet Services Manager from the Administrative Tools of the Programs menu to bring the Internet Information Services snap-in to life. From the left panel, navigate your way through the available leaves of the web sites to the proper directory, where you plan to use the already created extension. This is usually done in scripts directory of that dominium. For this purpose, I've created a scripts directory under the articles folder:

Image 2

Right click on the scripts directory and select properties to open up the following box:

Image 3

Make the necessary changes to the box, so that it looks like the above picture and then apply the changes. Now, copy the validate.dll file from the release directory to the scripts directory you already configured. Launch your favorite web browser, and try to access the DLL, passing a number as its query string:


Please pay attention that you have to change the above-mentioned URL to match the specific needs of your dominium.

Doing so, you'll see a damn familiar web page:

Image 4

Oooooops! What went wrong, causing this damn page to appear?! If you think a little bit, you would probably remember that we have to expose those 3 (in our case 2) entry points we have used in our program, GetExtensionVersion and HttpExtensionProc. So let's go back to the project to fix things.

While in VC++ environment, create a blank file named validate.def and implement it this way:

; Validate.def : Declares the module parameters for the DLL.

LIBRARY "Validate"
DESCRIPTION 'Validate ISAPI Extension'

   ; Explicit exports can go here

   HttpExtensionProc @1
   GetExtensionVersion @2

Then, from the project menu, select add to project, and then select the files item. Add the already created def file to the project. Rebuild the DLL. Let's copy the file from the release directory to the scripts directory again and browse the page again. This time, you will get the following page:

Image 5

Now try to access the page using a valid master card number, and you'll get the congratulations page. Then try to delete the validate.dll located in the scripts directory! What happens? Yep! You'll get an error indicating that the DLL is already in use and cannot be deleted. So what we have to do, if we want to update our DLL? Shall we restart the computer, close the client, or ...? Nope! Not at all!

All you have to do is to stop IIS. This is done through the Internet Information Services snap-in! Launch it, and right click on the server's name. From the context menu, select restart IIS. In the "what do you want IIS to do?" combo box, select "stop Internet services on server" and press the ok button. Wait for seconds, and it's done! Now you can delete and/or modify your extension! Neat, huh?

The final word

This is what ISAPI extensions are supposed to do. They extend the functionality of IIS. Through this article, I repeated the word extension over and over again. It's now time to say that ISAPI programs are divided into two categories: ISAPI extensions and ISAPI filters.

ISAPI filters, unlike the ISAPI extensions would be called for any hit made to the web server! In other words, they magnificently slow down the process, since they are called over and over again. However, they could be absolutely useful when creating a logging service, or doing some specific jobs. Since describing ISAPI filters in detail deserves another paper, let me leave it here to you to understand the subtle nuances of how they work.

Anyhow, this was the simplest ISAPI extension that we developed today, just to show you what the heck an extension is and how it works. It was a synchronous, single-threaded DLL that is the most easiest DLL to develop! Real-world applications are not this easy to implement though, since you have to face the multi-threaded issues, as well as connection pools and other advanced topics. It's all up to you to learn how to play them magnificently, though, and this paper is just a starting point! That's all, folks. Aloha!

How to contact the author

I, as ever before, would love to hear your comments, questions and/or suggestions. So, please do not hesitate to send them to me,


  1. Professional Visual C++ ISAPI Programming, by Michael Tracy
  2. Microsoft Developer Network, MSDN


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Written By
United States United States
Mehdi Mousavi is a professional computer programmer. He has written many programs using C, C++, MFC, Win32, COM, DCOM, JavaScript, ASP, HTML, DHTML, SQL, C# and MC++.

Comments and Discussions

QuestionCreate Static page from the *pECB structure Pin
Member 1127687531-Aug-15 3:46
Member 1127687531-Aug-15 3:46 
GeneralGreat article! Pin
Moagiz9-Feb-11 23:15
Moagiz9-Feb-11 23:15 
GeneralThank You Pin
Member 36190975-Oct-09 21:24
Member 36190975-Oct-09 21:24 
Generalasapi extension dll not loaded Pin
YuvalMel23-Apr-09 3:51
YuvalMel23-Apr-09 3:51 
GeneralRe: asapi extension dll not loaded Pin
mingch24-Apr-09 8:39
mingch24-Apr-09 8:39 
GeneralRe: asapi extension dll not loaded Pin
mingch24-Apr-09 10:07
mingch24-Apr-09 10:07 
GeneralISAPI filter Pin
m-khansari16-Dec-08 0:00
m-khansari16-Dec-08 0:00 
GeneralRe: ISAPI filter Pin
Mehdi Mousavi21-Dec-08 4:27
Mehdi Mousavi21-Dec-08 4:27 
Questioncs-username field IIS log files with ISAPI Pin
Member 243232330-Jun-08 18:04
Member 243232330-Jun-08 18:04 
QuestionISAPI Rewrite Pin
Robertino4-Jun-08 9:18
Robertino4-Jun-08 9:18 
GeneralISAPI for windows CE web server Pin
Member 83331222-May-08 8:06
Member 83331222-May-08 8:06 
GeneralThank You Pin
James DC27-Feb-08 22:57
James DC27-Feb-08 22:57 
GeneralRe: Thank You Pin
Portatofe2-Oct-08 6:10
Portatofe2-Oct-08 6:10 
QuestionISAPI Extension vs HTTP Server API Pin
hagarwal11-Feb-08 20:10
hagarwal11-Feb-08 20:10 
QuestionCustom extension .mspx Pin
Kaushik Gadani19-Jul-07 3:12
Kaushik Gadani19-Jul-07 3:12 
AnswerRe: Custom extension .mspx Pin
Mehdi Mousavi20-Jul-07 21:00
Mehdi Mousavi20-Jul-07 21:00 
QuestionDebug the ISAPI? Pin
vidhyapathy23-Jan-07 22:21
vidhyapathy23-Jan-07 22:21 
AnswerRe: Debug the ISAPI? Pin
Mehdi Mousavi24-Jan-07 19:53
Mehdi Mousavi24-Jan-07 19:53 
QuestionISAPI extensions for IIS 6.0 Pin
intelligent_pb19-Jun-06 20:20
intelligent_pb19-Jun-06 20:20 
AnswerRe: ISAPI extensions for IIS 6.0 Pin
zhaojicheng9-Jul-06 18:00
zhaojicheng9-Jul-06 18:00 
GeneralRe: ISAPI extensions for IIS 6.0 Pin
Karl-Johan Sjgren27-Jul-06 8:27
Karl-Johan Sjgren27-Jul-06 8:27 
GeneralGood one... Pin
Laxman Auti8-Jun-06 0:51
Laxman Auti8-Jun-06 0:51 
QuestionDWORD WINAPI HttpExtensionProc (...) Pin
mbtwos23-May-06 4:28
mbtwos23-May-06 4:28 
GeneralExcellent work for ISAPI beginners Pin
Anonymous6-Aug-04 20:37
Anonymous6-Aug-04 20:37 
GeneralISAPI Mapping Extensions Pin
Anonymous29-Mar-04 11:52
Anonymous29-Mar-04 11:52 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.