Microsoft KB Archive/171617: Difference between revisions

Latest revision as of 12:30, 21 July 2020

IIS ISAPI ServerSupportFunction and Keep-Alive Session

Q171617

The information in this article applies to:

Microsoft Internet Server Application Programming Interface (API)
Microsoft Internet Information Server 3.0

SUMMARY

When you create an ISAPI application for Internet Information Server (IIS), this application will require that the session between the client browser and IIS be maintained via the Keep-Alive header.

MORE INFORMATION

To implement Keep-Alive, IIS uses an async I/O read request via a completion port on the session to maintain it. This method requires that the thread that sent the read request still be active when the read request returns, or else the session will be torn down.

When an IIS ISAPI extension implements a WorkerFunction, and then that worker function completes its task, the worker function thread and the associated thread within IIS that issued the read request are torn down. As a result, the session is torn down.

To test if you are running into this situation, you can add a statement ("Sleep ( INFINITE );" ) to the end of your WorkerFunction to delay it so the read request can return.

To verify this is what is taking place, you should take a network trace and check to make sure that the socket number for the session is being maintained when the client hits refresh or some other object on the web page.

The following are examples of how to maintain the session with Keep-Alive, and one example that shows it failing.

SAMPLE ONE:

// **************************************************************
//   Code sample showing Keep-Alive while implementing
//   a worker thread.
// 
//   KeepAlive.c  -> Sample ISAPI Extension demonstrating Keep-Alive.
// ************************************************************** 

#include <windows.h>
#include <httpext.h>
#include <stdio.h>

BOOL WINAPI GetExtensionVersion(HSE_VERSION_INFO *pVer)
{
    pVer->dwExtensionVersion = MAKELONG(HSE_VERSION_MINOR, HSE_VERSION_MAJOR);
    lstrcpyn(pVer->lpszExtensionDesc, "ISAPI Keep-Alive Extension Sample", 
            HSE_MAX_EXT_DLL_NAME_LEN);

    return TRUE;
}

DWORD WINAPI HttpExtensionProc(EXTENSION_CONTROL_BLOCK *pECB)
{
    DWORD dwSize;

// This header will be filled in with the content length

    char szHeader[]="Connection: Keep-Alive\r\nContent-Length: %lu\r\nContent-type:
                                    text/html\r\n\r\n";
    char szContent[]="<html> <form method=get action=KeepAlive.dll><input type=submit>
                                    </form></html>";
    char szBuffer[4096];

// Send outgoing header

    sprintf(szBuffer, szHeader, strlen(szContent));
    dwSize = strlen(szBuffer);
    pECB->ServerSupportFunction(pECB, HSE_REQ_SEND_RESPONSE_HEADER,
                            NULL, &dwSize, (unsigned long *)szBuffer);
    
    // Send content
    dwSize = strlen(szContent);
    pECB->WriteClient(pECB, szContent, &dwSize, 0);

    return HSE_STATUS_SUCCESS_AND_KEEP_CONN;
}

SAMPLE TWO:

    
// *******************************************************************
//  The same code sample as above, but using a worker thread
//    implementing Keep-Alive.
// 
//  KeepAliveT.c  -> Sample ISAPI Extension demonstrating Keep-Alive
//    in a worker thread that terminates immediately which causes the
//  session to NOT be maintained.
//  *******************************************************************

#include <windows.h>
#include <httpext.h>
#include <stdio.h>

DWORD WINAPI WorkerFunction( LPVOID ); 

BOOL WINAPI GetExtensionVersion(HSE_VERSION_INFO *pVer)
{
    pVer->dwExtensionVersion = MAKELONG(HSE_VERSION_MINOR, HSE_VERSION_MAJOR);
    lstrcpyn(pVer->lpszExtensionDesc, "ISAPI Keep-Alive Extension Sample", 
            HSE_MAX_EXT_DLL_NAME_LEN);

    return TRUE;
}

DWORD WINAPI HttpExtensionProc(EXTENSION_CONTROL_BLOCK *pECB)
{
    DWORD dwThreadID;

    CreateThread(NULL, 0, WorkerFunction, pECB, 0, &dwThreadID);

    return HSE_STATUS_PENDING;
}


DWORD WINAPI WorkerFunction(LPVOID vECB)
{
    EXTENSION_CONTROL_BLOCK *pECB;
    DWORD dwState, dwSize;

    //This header will be filled in with the content length
    char szHeader[]="Connection: Keep-Alive\r\nContent-Length: %lu\r\nContent-type: text/html\r\n\r\n";
    char szContent[]="<html> <form method=get action=KeepAliveT.dll><input type=submit> </form></html>";
    char szBuffer[4096];

    pECB = vECB;
    
    // Send outgoing header
    sprintf(szBuffer, szHeader, strlen(szContent));
    dwSize = strlen(szBuffer);
    pECB->ServerSupportFunction(pECB->ConnID, HSE_REQ_SEND_RESPONSE_HEADER,
                NULL, &dwSize, (unsigned long *)szBuffer);
    
    // Send content
    dwSize = strlen(szContent);
    pECB->WriteClient(pECB->ConnID, szContent, &dwSize, 0);
    
    dwState = HSE_STATUS_SUCCESS_AND_KEEP_CONN;
    pECB->ServerSupportFunction(pECB->ConnID, HSE_REQ_DONE_WITH_SESSION, &dwState, NULL, 0);

    return 0;
}

SAMPLE THREE:

// ***************************************************************
// This program demonstates the recommendated method for
// implementing Keep-Alive in a worker function using a thread pool
// and work queue.
// 
// KeepAliveP.c  -> Sample ISAPI Extension demonstrating
//                  Keep-Alive with a thread pool.
// ***************************************************************

#include <windows.h>
#include <httpext.h>
#include <stdio.h>

#define POOL_THREADS 2
#define WORK_QUEUE_ENTRIES 2

typedef struct {
    EXTENSION_CONTROL_BLOCK * pECB;
    DWORD dwNextEntry;
} ECB_QUEUE_ENTRY;

ECB_QUEUE_ENTRY ECBqueue[WORK_QUEUE_ENTRIES];

DWORD dwCurrentEntry, dwLastEntry;
CRITICAL_SECTION csQueueLock;
BOOL fFirstCall;
HANDLE hWorkSem;

BOOL AddWorkQueueEntry(EXTENSION_CONTROL_BLOCK *);
BOOL GetWorkQueueEntry(EXTENSION_CONTROL_BLOCK ** ppECB);
DWORD WINAPI WorkerFunction(LPVOID vThreadNum);

BOOL WINAPI DllMain(IN HINSTANCE hinstDll, IN DWORD fdwReason, IN LPVOID lpvContext OPTIONAL)
{
    BOOL        fReturn = TRUE;
    DWORD       i;
    DWORD       dwThreadID;

    switch (fdwReason )
    {
    case DLL_PROCESS_ATTACH:
        {
            // Create Semaphore in nonsignaled state
            if( (hWorkSem = CreateSemaphore( NULL, 0, 0x7fffffff, NULL )) ==NULL)
                return FALSE;

            InitializeCriticalSection(&csQueueLock );
            
            fFirstCall=TRUE;

            // Create Pool Threads
            for(i=0; i<POOL_THREADS; i++)
            {   
                if(CreateThread(NULL, 0, WorkerFunction, (LPVOID)i, 0, &dwThreadID)==NULL)
                    return FALSE;
            }

            // Clear work queue
            ZeroMemory(ECBqueue, WORK_QUEUE_ENTRIES*sizeof(ECB_QUEUE_ENTRY) );
        }
    }
    
    return fReturn;
}

DWORD WINAPI WorkerFunction( LPVOID ); 

BOOL WINAPI GetExtensionVersion(HSE_VERSION_INFO *pVer)
{
    pVer->dwExtensionVersion = MAKELONG(HSE_VERSION_MINOR, HSE_VERSION_MAJOR);
    lstrcpyn(pVer->lpszExtensionDesc, "ISAPI Keep-Alive Extension Sample", 
            HSE_MAX_EXT_DLL_NAME_LEN);

    return TRUE;
}

DWORD WINAPI HttpExtensionProc(EXTENSION_CONTROL_BLOCK *pECB)
{
    DWORD dwSize;
    char szHeader[]="Connection: Keep-Alive\r\nContent-Length: %lu\r\nContent-type: text/html\r\n\r\n";
    char szContent[]="<html> <form method=get action=KeepAliveP.dll> <input type=submit> " \ 
                     "<br>pECB->ConnID=%lu  <br>Server was too busy. </form></html>";
    char szBuffer[4096];
    char szBuffer2[4096];

    EnterCriticalSection(&csQueueLock);
    if(!AddWorkQueueEntry(pECB)) // if ECB could not be assigned
    {
        LeaveCriticalSection(&csQueueLock);

        sprintf(szBuffer2, szContent, pECB->ConnID);

        // Send outgoing header
        sprintf(szBuffer, szHeader, strlen(szBuffer2));
        dwSize = strlen(szBuffer);
        pECB->ServerSupportFunction(pECB->ConnID, HSE_REQ_SEND_RESPONSE_HEADER,
            NULL, &dwSize, (unsigned long *)szBuffer);
    
        // Send content
        dwSize = strlen(szBuffer2);
        pECB->WriteClient(pECB->ConnID, szBuffer2, &dwSize, 0);

        return HSE_STATUS_SUCCESS_AND_KEEP_CONN;
    }
    else
    {
        ReleaseSemaphore( hWorkSem, 1, NULL );  //Release 1 thread from pool
        LeaveCriticalSection(&csQueueLock);
    }

    return HSE_STATUS_PENDING;
}


BOOL AddWorkQueueEntry(EXTENSION_CONTROL_BLOCK * pECB)
{
    DWORD i;

    for(i=0; i<WORK_QUEUE_ENTRIES; i++)
    {
        if (ECBqueue[i].pECB==NULL)
        {
            if(fFirstCall)
            {
                dwCurrentEntry=i;
                fFirstCall = FALSE;
            }
            else
                ECBqueue[dwLastEntry].dwNextEntry=i;
            ECBqueue[i].pECB=pECB;
            dwLastEntry=i;
            return TRUE;
        }
    }

    // If no NULL queue entry found, indicate failure
    return FALSE;
}

BOOL GetWorkQueueEntry(EXTENSION_CONTROL_BLOCK ** ppECB)
{
    if( (*ppECB=ECBqueue[dwCurrentEntry].pECB) == NULL)
        return FALSE;
    else
    {
        ECBqueue[dwCurrentEntry].pECB = NULL;
        if(dwCurrentEntry == dwLastEntry) // If this is only pending item
            fFirstCall = TRUE;
        else
            dwCurrentEntry = ECBqueue[dwCurrentEntry].dwNextEntry;
    }
    
    return TRUE;
}


DWORD WINAPI WorkerFunction(LPVOID pvThreadNum)
{
    EXTENSION_CONTROL_BLOCK *pECB;
    DWORD dwRet, dwState, dwSize, dwThreadNum;

    //This header will be filled in with the content length
    char szHeader[]="Connection: Keep-Alive\r\nContent-Length: %lu\r\nContent-type: text/html\r\n\r\n";
    char szContent[]="<html> <form method=get action=KeepAliveP.dll><input type=submit> "\ 
                    "<br>pECB->ConnID=%lu  <br>dwThreadNum=%lu</form></html>";
    char szBuffer[4096];
    char szBuffer2[4096];

    dwThreadNum=(DWORD)pvThreadNum;

    while(TRUE)
    {
        dwRet = WaitForSingleObject( hWorkSem, INFINITE );
        if ( dwRet == WAIT_OBJECT_0 )
        {

            EnterCriticalSection(&csQueueLock);

            if( GetWorkQueueEntry(&pECB) )  // This function should always return true
            {
                LeaveCriticalSection(&csQueueLock);
    
                sprintf(szBuffer2, szContent, pECB->ConnID, dwThreadNum);

                // Send outgoing header
                sprintf(szBuffer, szHeader, strlen(szBuffer2));
                dwSize = strlen(szBuffer);
                pECB->ServerSupportFunction(pECB->ConnID, HSE_REQ_SEND_RESPONSE_HEADER,
                    NULL, &dwSize, (unsigned long *)szBuffer);
        
                Sleep(3000);
    
                // Send content
                dwSize = strlen(szBuffer2);
                pECB->WriteClient(pECB->ConnID, szBuffer2, &dwSize, 0);

                dwState = HSE_STATUS_SUCCESS_AND_KEEP_CONN;
                pECB->ServerSupportFunction(pECB->ConnID, HSE_REQ_DONE_WITH_SESSION, &dwState, NULL, 0);
            }
            else
                LeaveCriticalSection(&csQueueLock);
                
        }
        else
            break;
    }

    return 0;
}

Additional query words: iis

Keywords : kbinterop
Issue type : kbhowto
Technology : kbiisSearch kbAudDeveloper kbiis300 kbISAPI kbISAPISearch