CHttpModule::OnAsyncCompletion-Methode

Artikel
07/19/2023

Stellt die Methode dar, die ein asynchrones Vervollständigungsereignis verarbeitet, das nach Abschluss der Verarbeitung eines asynchronen Vorgangs auftritt.

Syntax

virtual REQUEST_NOTIFICATION_STATUS OnAsyncCompletion(  
   IN IHttpContext* pHttpContext,  
   IN DWORD dwNotification,  
   IN BOOL fPostNotification,  
   IN OUT IHttpEventProvider* pProvider,  
   IN IHttpCompletionInfo* pCompletionInfo  
);

Parameter

pHttpContext
[IN] Ein Zeiger auf eine IHttpContext-Schnittstelle .

dwNotification
[IN] Ein DWORD Wert, der die Bitmaske für die zugehörige Benachrichtigung enthält.

fPostNotification
[IN] true , um anzugeben, dass die Benachrichtigung für ein Post-Event gilt; falseandernfalls .

pProvider
[IN] Ein Zeiger auf eine IHttpEventProvider-Schnittstelle .

pCompletionInfo
[IN] Ein Zeiger auf eine IHttpCompletionInfo-Schnittstelle .

Rückgabewert

Ein REQUEST_NOTIFICATION_STATUS Wert.

Bemerkungen

Im Gegensatz zu vielen anderen CHttpModule-Methoden , die durch die Registrierung für bestimmte Benachrichtigungen aufgerufen werden, ruft IIS die Methode eines Moduls OnAsyncCompletion nur auf, wenn ein asynchroner Vorgang abgeschlossen ist. Wenn beispielsweise ein Modul auf Anforderungsebene die IHttpResponse::WriteEntityChunks-Methode aufruft und die asynchrone Vervollständigung angibt, ruft IIS die Methode des Moduls OnAsyncCompletion auf, wenn der Vorgang abgeschlossen ist.

Wenn IIS die OnAsyncCompletion -Methode aufruft, wird der Benachrichtigungstyp im dwNotification Parameter angegeben, und es wird angegeben, ob die Benachrichtigung für ein Ereignis oder nach dem Ereignis war, indem sie den fPostNotification -Parameter verwendet. IIS stellt auch eine IHttpCompletionInfo Schnittstelle bereit, auf die der pCompletionInfo -Parameter verweist. Sie können diese Schnittstelle verwenden, um zusätzliche Informationen zur asynchronen Vervollständigung abzurufen.

Beispiel

Im folgenden Codebeispiel wird veranschaulicht, wie Sie ein HTTP-Modul erstellen, das die folgenden Aufgaben ausführt:

Das Modul registriert sich für die RQ_BEGIN_REQUEST und RQ_MAP_REQUEST_HANDLER Benachrichtigungen.
Das Modul erstellt eine CHttpModule Klasse, die OnBeginRequest, OnMapRequestHandler und OnAsyncCompletion Methoden enthält.
Wenn ein Webclient eine URL anfordert, ruft IIS die -Methode des Moduls auf OnBeginRequest . Diese Methode führt die folgenden Tasks aus:
1. Löscht den vorhandenen Antwortpuffer und legt den MIME-Typ für die Antwort fest.
2. Erstellt eine Beispielzeichenfolge und gibt diese asynchron an den Webclient zurück.
3. Testet auf einen Fehler oder eine asynchrone Vervollständigung. Wenn die asynchrone Vervollständigung aussteht, gibt das Modul eine ausstehende Benachrichtigung status an die integrierte Anforderungsverarbeitungspipeline zurück.
IIS ruft die Methode des Moduls auf OnMapRequestHandler . Diese Methode führt die folgenden Tasks aus:
1. Leert den aktuellen Antwortpuffer auf den Webclient.
2. Testet auf einen Fehler oder eine asynchrone Vervollständigung. Wenn die asynchrone Vervollständigung aussteht, gibt das Modul eine ausstehende Benachrichtigung status an die Pipeline zurück.
Wenn eine asynchrone Vervollständigung erforderlich ist, ruft IIS die Methode des Moduls auf OnAsyncCompletion . Diese Methode führt die folgenden Tasks aus:
1. Testet auf eine gültige IHttpCompletionInfo Schnittstelle. Wenn eine gültige IHttpCompletionInfo Schnittstelle übergeben wurde, ruft die Methode die Methoden GetCompletionBytes bzw. GetCompletionStatus auf, um die abgeschlossenen Bytes abzurufen und die status für den asynchronen Vorgang zurückzugeben.
2. Erstellt Zeichenfolgen, die die Vervollständigungsinformationen enthalten, und schreibt die Informationen als Ereignis in das Anwendungsprotokoll des Ereignisanzeige.
Das Modul entfernt die CHttpModule -Klasse aus dem Arbeitsspeicher und wird dann beendet.

#define _WINSOCKAPI_
#include <windows.h>
#include <sal.h>
#include <httpserv.h>
#include <wchar.h>

// Create the module class.
class MyHttpModule : public CHttpModule
{

public:

    REQUEST_NOTIFICATION_STATUS
    OnBeginRequest(
        IN IHttpContext * pHttpContext,
        IN IHttpEventProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pProvider );

        // Create an HRESULT to receive return values from methods.
        HRESULT hr;
        // Buffer to store the byte count.
        DWORD cbSent = 0;
        // Buffer to store if asyncronous completion is pending.
        BOOL fCompletionExpected = false;
        // Create an example string to return to the Web client.
        char szBuffer[] = "Hello World!";
        
        // Clear the existing response.
        pHttpContext->GetResponse()->Clear();
        // Set the MIME type to plain text.
        pHttpContext->GetResponse()->SetHeader(
            HttpHeaderContentType,"text/plain",
            (USHORT)strlen("text/plain"),TRUE);
        
        // Create a data chunk.
        HTTP_DATA_CHUNK dataChunk;
        // Set the chunk to a chunk in memory.
        dataChunk.DataChunkType = HttpDataChunkFromMemory;
        // Set the chunk to the buffer.
        dataChunk.FromMemory.pBuffer =
            (PVOID) szBuffer;
        // Set the chunk size to the buffer size.
        dataChunk.FromMemory.BufferLength =
            (USHORT) strlen(szBuffer);
        // Insert the data chunk into the response.
        hr = pHttpContext->GetResponse()->WriteEntityChunks(
            &dataChunk,1,TRUE,TRUE,&cbSent,&fCompletionExpected);

        // Test for a failure.
        if (FAILED(hr))
        {
            // Set the HTTP status.
            pHttpContext->GetResponse()->SetStatus(
                500,"Server Error",0,hr);
            // End additional processing.
            return RQ_NOTIFICATION_FINISH_REQUEST;
        }
        
        // Test for pending asynchronous operations.
        if (fCompletionExpected)
        {
            return RQ_NOTIFICATION_PENDING;
        }

        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }
    
    REQUEST_NOTIFICATION_STATUS
    OnMapRequestHandler(
        IN IHttpContext * pHttpContext,
        IN IMapHandlerProvider * pProvider
    )
    {
        // Create an HRESULT to receive return values from methods.
        HRESULT hr;
        // Buffer to store the byte count.
        DWORD cbSent = 0;
        // Buffer to store if asyncronous completion is pending.
        BOOL fCompletionExpected = false;

        // Flush the response to the client.
        hr = pHttpContext->GetResponse()->Flush(
            TRUE,FALSE,&cbSent,&fCompletionExpected);

        // Test for a failure.
        if (FAILED(hr))
        {
            // Set the HTTP status.
            pHttpContext->GetResponse()->SetStatus(
                500,"Server Error",0,hr);
        }

        // Test for pending asynchronous operations.
        if (fCompletionExpected)
        {
            return RQ_NOTIFICATION_PENDING;
        }

        // End additional processing.
        return RQ_NOTIFICATION_CONTINUE;
    }

    REQUEST_NOTIFICATION_STATUS
        OnAsyncCompletion(
        IN IHttpContext * pHttpContext,
        IN DWORD dwNotification,
        IN BOOL fPostNotification,
        IN IHttpEventProvider * pProvider,
        IN IHttpCompletionInfo * pCompletionInfo
        )
    {        
        if ( NULL != pCompletionInfo )
        {
            // Create strings for completion information.
            char szNotification[256] = "";
            char szBytes[256] = "";
            char szStatus[256] = "";

            // Retrieve and format the completion information.
            sprintf_s(szNotification,255,"Notification: %u",
                dwNotification);
            sprintf_s(szBytes,255,"Completion Bytes: %u",
                pCompletionInfo->GetCompletionBytes());
            sprintf_s(szStatus,255,"Completion Status: 0x%08x",
                pCompletionInfo->GetCompletionStatus());

            // Create an array of strings.
            LPCSTR szBuffer[3] = {szNotification,szBytes,szStatus};
            // Write the strings to the Event Viewer.
            WriteEventViewerLog(szBuffer,3);
        }
        
        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }

    MyHttpModule(void)
    {
        // Open a handle to the Event Viewer.
        m_hEventLog = RegisterEventSource( NULL,"IISADMIN" );
    }

    ~MyHttpModule(void)
    {
        // Test if the handle for the Event Viewer is open.
        if (NULL != m_hEventLog)
        {
            // Close the handle to the Event Viewer.
            DeregisterEventSource( m_hEventLog );
            m_hEventLog = NULL;
        }
    }

private:

    // Handle for the Event Viewer.
    HANDLE m_hEventLog;

    // Define a method that writes to the Event Viewer.
    BOOL WriteEventViewerLog(LPCSTR * lpStrings, WORD wNumStrings)
    {
        // Test whether the handle for the Event Viewer is open.
        if (NULL != m_hEventLog)
        {
            // Write any strings to the Event Viewer and return.
            return ReportEvent(
                m_hEventLog, EVENTLOG_INFORMATION_TYPE,
                0, 0, NULL, wNumStrings, 0, lpStrings, NULL );
        }
        return FALSE;
    }
};

// Create the module's class factory.
class MyHttpModuleFactory : public IHttpModuleFactory
{
public:
    HRESULT
    GetHttpModule(
        OUT CHttpModule ** ppModule, 
        IN IModuleAllocator * pAllocator
    )
    {
        UNREFERENCED_PARAMETER( pAllocator );

        // Create a new instance.
        MyHttpModule * pModule = new MyHttpModule;

        // Test for an error.
        if (!pModule)
        {
            // Return an error if we cannot create the instance.
            return HRESULT_FROM_WIN32( ERROR_NOT_ENOUGH_MEMORY );
        }
        else
        {
            // Return a pointer to the module.
            *ppModule = pModule;
            pModule = NULL;
            // Return a success status.
            return S_OK;
        }            
    }

    void Terminate()
    {
        // Remove the class from memory.
        delete this;
    }
};

// Create the module's exported registration function.
HRESULT
__stdcall
RegisterModule(
    DWORD dwServerVersion,
    IHttpModuleRegistrationInfo * pModuleInfo,
    IHttpServer * pGlobalInfo
)
{
    UNREFERENCED_PARAMETER( dwServerVersion );
    UNREFERENCED_PARAMETER( pGlobalInfo );

    return pModuleInfo->SetRequestNotifications(
        new MyHttpModuleFactory,
        RQ_BEGIN_REQUEST | RQ_MAP_REQUEST_HANDLER,
        0
    );
}

Ihr Modul muss die Funktion RegisterModule exportieren. Sie können diese Funktion exportieren, indem Sie eine Moduldefinitionsdatei (.def) für Ihr Projekt erstellen, oder Sie können das Modul mithilfe des /EXPORT:RegisterModule Switches kompilieren. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Erstellen eines Request-Level HTTP-Moduls mithilfe von nativem Code.

Sie können den Code optional kompilieren, indem Sie die __stdcall (/Gz) aufrufende Konvention verwenden, anstatt die aufrufende Konvention für jede Funktion explizit zu deklarieren.

Anforderungen

type	BESCHREIBUNG
Client	– IIS 7.0 unter Windows Vista – IIS 7.5 unter Windows 7 – IIS 8.0 unter Windows 8 – IIS 10.0 auf Windows 10
Server	– IIS 7.0 unter Windows Server 2008 – IIS 7.5 unter Windows Server 2008 R2 – IIS 8.0 unter Windows Server 2012 – IIS 8.5 unter Windows Server 2012 R2 – IIS 10.0 auf Windows Server 2016
Produkt	– IIS 7.0, IIS 7.5, IIS 8.0, IIS 8.5, IIS 10.0 - IIS Express 7.5, IIS Express 8.0, IIS Express 10.0
Header	Httpserv.h

Weitere Informationen

CHttpModule-Klasse

Freigeben über