PFN_REGISTERMODULE-Funktion

Artikel
07/19/2023

Definiert den Funktionsprototyp RegisterModule für HTTP-Module mit nativem Code.

Syntax

typedef HRESULT(WINAPI* PFN_REGISTERMODULE)(  
   DWORD dwServerVersion,  
   IHttpModuleRegistrationInfo* pModuleInfo,  
   IHttpServer* pGlobalInfo  
);

Parameter

dwServerVersion
Eine DWORD , die die IIS-Hauptversionsnummer enthält.

pModuleInfo
Ein Zeiger auf eine IHttpModuleRegistrationInfo-Schnittstelle .

pGlobalInfo
Ein Zeiger auf eine IHttpServer-Schnittstelle .

Rückgabewert

HRESULT. Mögliches Werte (aber nicht die Einzigen) sind die in der folgenden Tabelle.

Wert	BESCHREIBUNG
S_OK	Gibt an, dass der Vorgang erfolgreich war.

Hinweis

Ihr Modul kann einen beliebigen gültigen HRESULT Wert zurückgeben, sollte jedoch mindestens S_OK zurückgeben, um anzugeben, dass Ihre RegisterModule Funktion erfolgreich war.

Bemerkungen

PFN_REGISTERMODULE ist ein Funktionsprototyp für die Funktion, die RegisterModule alle HTTP-Module für ihren DLL-Einstiegspunkt implementieren müssen.

Wenn Sie ein HTTP-Modul erstellen, muss Ihr Modul die folgende RegisterModule Methode hinzufügen:

HRESULT RegisterModule(  
   DWORD dwServerVersion,  
   IHttpModuleRegistrationInfo* pModuleInfo,  
   IHttpServer* pGlobalInfo  
)

Alle HTTP-Module müssen ihre RegisterModule Funktion exportieren, damit IIS das Modul laden kann. Sie können die RegisterModule Funktion exportieren, indem Sie eine Moduldefinitionsdatei (.def) für Ihr DLL-Projekt erstellen oder das Modul mithilfe des /EXPORT:RegisterModule Switches kompilieren.

Ihre RegisterModule Funktion muss die Schnittstelle verwenden, um sich mit den IHttpModuleRegistrationInfoMethoden SetRequestNotifications und SetGlobalNotifications für Benachrichtigungen zu registrieren. RegisterModulemuss auch zum Registrieren von Modulprioritäten mithilfe der Methoden SetPriorityForRequestNotification und SetPriorityForGlobalNotification verwendet IHttpModuleRegistrationInfo werden.

Der dwServerVersion Parameter enthält die Hauptversionsnummer für die IIS-Version, die das Modul lädt. Für IIS 7.0 enthält der dwServerVersion Parameter beispielsweise eine 7.

Wenn IIS Ihre RegisterModule Funktion aufruft, stellt sie eine IHttpServer Schnittstelle bereit, die Ihr Modul zum Abrufen von Informationen auf Serverebene verwenden kann.

Hinweis

Ablaufverfolgungsereignisse sollten innerhalb der Funktionsimplementierung nicht ausgelöst werden (über die IHttpTraceContext::QuickTrace-Methode oder eine andere Methode über die IHttpServer::GetTraceContext-Methode).RegisterModule Das Auslösen von Ablaufverfolgungsereignissen innerhalb von RegisterModule kann zu einer Zugriffsverletzung führen, da es in der Anforderungspipeline zu früh ist.

Beispiel

Im folgenden Codebeispiel 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 CHttpModule::OnBeginRequest-Methode des Moduls 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

IHttpModuleRegistrationInfo-Schnittstelle
IHttpModuleRegistrationInfo::SetGlobalNotifications-Methode
IHttpModuleRegistrationInfo::SetPriorityForGlobalNotification-Methode
IHttpModuleRegistrationInfo::SetPriorityForRequestNotification-Methode
IHttpModuleRegistrationInfo::SetRequestNotifications-Methode
IHttpServer-Schnittstelle

Share via