Freigeben über


CHttpModule-Klasse

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) 1
OnCustomRequestNotification (Keine) 2
OnMapPath (Keine)
OnReadEntity (Keine)
OnSendResponse (Keine)

1 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.

2 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