CHttpModule-Klasse

Artikel
07/19/2023

Definiert die Basisklasse für HTTP-Module auf Anforderungsebene.

Syntax

class CHttpModule

Methoden

In der folgenden Tabelle sind die Methoden aufgeführt, die von der CHttpModule -Klasse verfügbar gemacht werden.

Name	BESCHREIBUNG
~CHttpModule	Gibt die Zuordnung eines instance der `CHttpModule` -Klasse auf.
CHttpModule	Initialisiert eine neue Instanz der `CHttpModule`-Klasse.
Dispose	Gibt alle von der aktuellen Instanz der `CHttpModule`-Klasse verwendeten Ressourcen frei.
OnAcquireRequestState	Stellt die Methode dar, die ein `AcquireRequestState` Ereignis behandelt, das auftritt, wenn IIS den Zustand für die aktuelle Anforderung abruft.
OnAsyncCompletion	Stellt die Methode dar, die ein asynchrones Abschlussereignis behandelt, das auftritt, nachdem ein asynchroner Vorgang die Verarbeitung abgeschlossen hat.
OnAuthenticateRequest	Stellt die Methode dar, die ein `AuthenticateRequest` Ereignis behandelt, das auftritt, wenn IIS die Identität eines Benutzers festlegt.
OnAuthorizeRequest	Stellt die Methode dar, die ein `AuthorizeRequest` Ereignis behandelt, das auftritt, wenn IIS die Benutzerautorisierung überprüft.
OnBeginRequest	Stellt die Methode dar, die ein `BeginRequest` Ereignis behandelt, das als erstes Ereignis in der integrierten HTTP-Anforderungsverarbeitungspipeline für die aktuelle Anforderung auftritt.
OnCustomRequestNotification	Stellt die Methode dar, die ein benutzerdefiniertes Ereignis behandelt, das auftritt, wenn ein Modul eine benutzerdefinierte Benachrichtigung auslöst.
OnEndRequest	Stellt die Methode dar, die ein `EndRequest` Ereignis behandelt, das als letztes Ereignis in der integrierten HTTP-Anforderungsverarbeitungspipeline für die aktuelle Anforderung auftritt.
OnExecuteRequestHandler	Stellt die Methode dar, die ein `ExecuteRequestHandler` Ereignis behandelt, das auftritt, wenn IIS den Handler für die aktuelle Anforderung ausführt.
OnLogRequest	Stellt die Methode dar, die ein `LogRequest` Ereignis behandelt, das auftritt, wenn IIS die aktuelle Anforderung protokolliert.
OnMapPath	Stellt die Methode dar, die ein `MapPath` Ereignis behandelt, das auftritt, wenn ein Vorgang die Zuordnung des physischen Pfads für die aktuelle Anforderung anfordert.
OnMapRequestHandler	Stellt die Methode dar, die ein `MapRequestHandler` Ereignis behandelt, das auftritt, wenn IIS die aktuelle Anforderung einem Ereignishandler zuordnet.
OnPostAcquireRequestState	Stellt die Methode dar, die ein `AcquireRequestState` Post-Ereignis behandelt, das auftritt, nachdem IIS den Zustand für die aktuelle Anforderung abgerufen hat.
OnPostAuthenticateRequest	Stellt die Methode dar, die ein `AuthenticateRequest` Postereignis behandelt, das auftritt, nachdem IIS die Identität eines Benutzers eingerichtet hat.
OnPostAuthorizeRequest	Stellt die Methode dar, die ein `AuthorizeRequest` Postereignis behandelt, das auftritt, nachdem IIS die Benutzerautorisierung überprüft hat.
OnPostBeginRequest	Stellt die Methode dar, die ein `BeginRequest` Postereignis behandelt, das nach dem ersten Ereignis in der integrierten HTTP-Anforderungsverarbeitungspipeline auftritt.
OnPostEndRequest	Stellt die Methode dar, die ein `EndRequest` Postereignis behandelt, das nach dem letzten Ereignis in der integrierten HTTP-Anforderungsverarbeitungspipeline für die aktuelle Anforderung auftritt.
OnPostExecuteRequestHandler	Stellt die Methode dar, die ein `ExecuteRequestHandler` Postereignis behandelt, das auftritt, nachdem IIS den Handler für die aktuelle Anforderung ausgeführt hat.
OnPostLogRequest	Stellt die Methode dar, die ein `LogRequest` Postereignis behandelt, das auftritt, nachdem IIS die aktuelle Anforderung protokolliert hat.
OnPostMapRequestHandler	Stellt die Methode dar, die ein `MapRequestHandler` Postereignis behandelt, das auftritt, nachdem IIS die aktuelle Anforderung dem entsprechenden Ereignishandler zugeordnet hat.
OnPostPreExecuteRequestHandler	Stellt die Methode dar, die ein `PreExecuteRequestHandler` Post-Ereignis behandelt, das auftritt, bevor IIS einen Anforderungshandler ausführt.
OnPostReleaseRequestState	Stellt die Methode dar, die ein `ReleaseRequestState` Post-Ereignis behandelt, das nach der Freigabe des aktuellen Zustands auftritt.
OnPostResolveRequestCache	Stellt die Methode dar, die ein `ResolveRequestCache` Postereignis behandelt, das auftritt, nachdem IIS eine Anforderung aus dem Cache aufgelöst hat.
OnPostUpdateRequestCache	Stellt die Methode dar, die ein `UpdateRequestCache` Postereignis behandelt, das auftritt, nachdem IIS die Anforderung im Cache gespeichert hat.
OnPreExecuteRequestHandler	Stellt die Methode dar, die ein `PreExecuteRequestHandler` Ereignis behandelt, das auftritt, bevor IIS einen Anforderungshandler ausführt.
OnReadEntity	Stellt die Methode dar, die ein `ReadEntity` Ereignis behandelt, das auftritt, wenn ein Vorgang Daten aus dem Anforderungspuffer liest.
OnReleaseRequestState	Stellt die Methode dar, die ein `ReleaseRequestState` Ereignis behandelt, das auftritt, wenn der aktuelle Zustand freigegeben wird.
OnResolveRequestCache	Stellt die Methode dar, die ein `ResolveRequestCache` Ereignis behandelt, das auftritt, wenn IIS eine Anforderung im Cache auflöst.
OnSendResponse	Stellt die Methode dar, die ein `SendResponse` Ereignis behandelt, das auftritt, wenn IIS den Antwortpuffer sendet.
OnUpdateRequestCache	Stellt die Methode dar, die ein `UpdateRequestCache` Ereignis behandelt, das auftritt, wenn IIS die Anforderung im Cache speichert.

Abgeleitete Klassen

Diese Klasse enthält keine abgeleiteten Klassen.

Bemerkungen

Die CHttpModule -Klasse ist die Basisklasse für HTTP-Module auf Anforderungsebene. Um eine CHttpModuleabgeleitete Klasse zu erstellen, müssen Sie ein HTTP-Modul auf Anforderungsebene erstellen, das eine Klasse enthält, die von CHttpModule erbt, und eine Klasse, die von der IHttpModuleFactory-Schnittstelle abgeleitet wird. Weitere Informationen zum Erstellen von HTTP-Modulen finden Sie unter Entwerfen Native-Code HTTP-Modulen.

Die CHttpModule -Klasse stellt geschützte Konstruktor- und Destruktormethoden sowie eine öffentliche Dispose Methode bereit. Am Ende der Anforderung wird die Dispose -Methode aufgerufen, um die instance der CHttpModule-abgeleiteten Klasse zu löschen.

Die CHttpModule -Klasse definiert auch die benachrichtigungsspezifischen Methoden, die IIS 7 aufruft, wenn Ereignisse auf Anforderungsebene innerhalb der integrierten Anforderungsverarbeitungspipeline verarbeitet werden. Ein HTTP-Modul kann sich für bestimmte Ereignisse registrieren, indem eine Liste von Benachrichtigungen in der exportierten RegisterModule-Funktion eines Moduls definiert wird.

Deterministische Anforderungsereignisse

Die meisten Benachrichtigungsmethoden auf Anforderungsebene werden während des normalen Ablaufs von Ereignissen auf Anforderungsebene innerhalb der integrierten Pipeline chronologisch verarbeitet. Jede der deterministischen Benachrichtigungsmethoden auf Anforderungsebene verfügt über eine entsprechende Benachrichtigung nach dem Ereignis, mit der HTTP-Module verarbeitet werden können, wenn ein Ereignis eintritt oder unmittelbar nach dem Ereignis auftritt.

In der folgenden Tabelle sind die chronologischen Ereignis- und Benachrichtigungsmethoden nach Anforderungsebene in der Reihenfolge ihres Vorkommens in der integrierten Pipeline aufgeführt.

Ereignisbenachrichtigungsmethode	Benachrichtigungsmethode nach dem Ereignis
`OnBeginRequest`	`OnPostBeginRequest`
`OnAuthenticateRequest`	`OnPostAuthenticateRequest`
`OnAuthorizeRequest`	`OnPostAuthorizeRequest`
`OnResolveRequestCache`	`OnPostResolveRequestCache`
`OnMapRequestHandler`	`OnPostMapRequestHandler`
`OnAcquireRequestState`	`OnPostAcquireRequestState`
`OnPreExecuteRequestHandler`	`OnPostPreExecuteRequestHandler`
`OnExecuteRequestHandler`	`OnPostExecuteRequestHandler`
`OnReleaseRequestState`	`OnPostReleaseRequestState`
`OnUpdateRequestCache`	`OnPostUpdateRequestCache`
`OnLogRequest`	`OnPostLogRequest`
`OnEndRequest`	`OnPostEndRequest`

Tritt z. B OnBeginRequest . vor OnAuthenticateRequestauf, OnMapRequestHandler tritt vor OnAcquireRequestStateauf usw. auf.

Hinweis

Benachrichtigungen nach dem Ereignis erfolgen vor der nächsten Benachrichtigung auf chronologischer Anforderungsebene. Tritt z. B OnPostAuthenticateRequest . vor OnAuthorizeRequestauf, OnPostUpdateRequestCache tritt vor OnLogRequestauf usw. auf.

Nicht deterministische Anforderungsereignisse

Die übrigen Benachrichtigungsmethoden auf Anforderungsebene werden nicht in einer bestimmten Reihenfolge verarbeitet. IIS verarbeitet diese Ereignisse stattdessen, wenn ein bestimmtes nicht deterministisches Ereignis auftritt. In der folgenden Tabelle sind das nicht deterministische Ereignis auf Anforderungsebene und alle zugehörigen Benachrichtigungsmethoden nach dem Ereignis aufgeführt.

Ereignisbenachrichtigungsmethode	Benachrichtigungsmethode nach dem Ereignis
`OnAsyncCompletion`	(Keine) ¹
`OnCustomRequestNotification`	(Keine) ²
`OnMapPath`	(Keine)
`OnReadEntity`	(Keine)
`OnSendResponse`	(Keine)

¹ Die OnAsyncCompletion -Methode wird aufgerufen, wenn ein asynchrones Ereignis in einem HTTP-Modul auftritt. Daher können Sie sich nicht mit der exportierten RegisterModule-Funktion eines Moduls für eine asynchrone Benachrichtigung registrieren. Stattdessen stellt Ihr Modul eine OnAsyncCompletion Methode zum Verarbeiten von Benachrichtigungen bereit, die nach dem Aufrufen von Methoden auftreten, die asynchron zurückgegeben werden (z. B. die Methoden IHttpContext::ExecuteRequest und IHttpResponse::WriteEntityChunks ). Wenn IIS aufruft OnAsyncCompletion, übergibt die -Methode Parameter, die den Benachrichtigungstyp angeben und angeben, ob die Benachrichtigung für ein Ereignis oder ein Ereignis nach dem Ereignis war.

² Die OnCustomRequestNotification Methode verfügt nicht über eine entsprechende Benachrichtigungsmethode nach dem Ereignis. Ein HTTP-Modul kann sich mit der exportierten RegisterModule Funktion des Moduls für eine benutzerdefinierte Benachrichtigung registrieren, aber ein Modul kann sich nicht für eine Benachrichtigung registrieren, die nach einer benutzerdefinierten Benachrichtigung erfolgt.

Beispiel

Im folgenden Beispiel wird veranschaulicht, wie ein einfaches HTTP-Modul "Hallo Welt" erstellt wird. Das Modul definiert eine exportierte RegisterModule Funktion, die eine instance einer IHttpModuleFactory Schnittstelle an die IHttpModuleRegistrationInfo::SetRequestNotifications-Methode übergibt und sich für die RQ_BEGIN_REQUEST Benachrichtigung registriert. IIS verwendet die IHttpModuleFactory::GetHttpModule-Methode, um eine instance einer CHttpModule Klasse zu erstellen und eine erfolgreiche status zurück. IIS verwendet auch die IHttpModuleFactory::Terminate-Methode , um die Factory aus dem Arbeitsspeicher zu entfernen.

Wenn eine RQ_BEGIN_REQUEST Benachrichtigung auftritt, ruft IIS die Methode des Moduls OnBeginRequest auf, um die aktuelle Anforderung zu verarbeiten. OnBeginRequest löscht den Antwortpuffer und ändert den MIME-Typ für die Antwort. Die -Methode erstellt dann einen Datenblock, der eine "Hallo Welt"-Zeichenfolge enthält, und gibt die Zeichenfolge an einen Webclient zurück. Schließlich gibt das Modul einen status Indikator zurück, der IIS benachrichtigt, dass alle Benachrichtigungen abgeschlossen sind und dann beendet wird.

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

// Create the module class.
class CHelloWorld : 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;
        
        // Retrieve a pointer to the response.
        IHttpResponse * pHttpResponse = pHttpContext->GetResponse();

        // Test for an error.
        if (pHttpResponse != NULL)
        {
            // Clear the existing response.
            pHttpResponse->Clear();
            // Set the MIME type to plain text.
            pHttpResponse->SetHeader(
                HttpHeaderContentType,"text/plain",
                (USHORT)strlen("text/plain"),TRUE);

            // Create a string with the response.
            PCSTR pszBuffer = "Hello World!";
            // Create a data chunk.
            HTTP_DATA_CHUNK dataChunk;
            // Set the chunk to a chunk in memory.
            dataChunk.DataChunkType = HttpDataChunkFromMemory;
            // Buffer for bytes written of data chunk.
            DWORD cbSent;
            
            // Set the chunk to the buffer.
            dataChunk.FromMemory.pBuffer =
                (PVOID) pszBuffer;
            // Set the chunk size to the buffer size.
            dataChunk.FromMemory.BufferLength =
                (USHORT) strlen(pszBuffer);
            // Insert the data chunk into the response.
            hr = pHttpResponse->WriteEntityChunks(
                &dataChunk,1,FALSE,TRUE,&cbSent);

            // Test for an error.
            if (FAILED(hr))
            {
                // Set the HTTP status.
                pHttpResponse->SetStatus(500,"Server Error",0,hr);
            }

            // End additional processing.
            return RQ_NOTIFICATION_FINISH_REQUEST;
        }

        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }
};

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

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

        // Test for an error.
        if (!pModule)
        {
            // Return an error if the factory 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 );

    // Set the request notifications and exit.
    return pModuleInfo->SetRequestNotifications(
        new CHelloWorldFactory,
        RQ_BEGIN_REQUEST,
        0
    );
}

Ihr Modul muss die RegisterModule Funktion 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

Erstellen von Native-Code HTTP-Modulen
CGlobalModule-Klasse

Freigeben über