IHttpModuleRegistrationInfo::SetRequestNotifications-Methode

Registriert die Benachrichtigungen auf Anforderungsebene für ein Modul.

Syntax

virtual HRESULT SetRequestNotifications(  
   IN IHttpModuleFactory* pModuleFactory,  
   IN DWORD dwRequestNotifications,  
   IN DWORD dwPostRequestNotifications  
) = 0;  

Parameter

pModuleFactory
[IN] Ein Zeiger auf eine IHttpModuleFactory-Schnittstelle .

dwRequestNotifications
[IN] Eine Bitmaske, die die zu registrierenden Anforderungsbenachrichtigungen enthält. (Definiert in Httpserv.h.)

dwPostRequestNotifications
[IN] Ein Bitmaskenwert, der die zu registrierenden Benachrichtigungen nach dem Ereignis enthält. (Definiert in Httpserv.h.)

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.
ERROR_ALREADY_EXISTS	Gibt an, dass das Modul bereits registriert wurde.

Bemerkungen

Die SetRequestNotifications -Methode registriert die Benachrichtigungen auf Anforderungsebene für eine CHttpModule-Klasse . Ein Modul kann sich für zwei Ereignisse für jede Benachrichtigung registrieren: die Ereignisbenachrichtigung, wie durch die Bitmaske im dwRequestNotifications Parameter angegeben, und die Benachrichtigung nach dem Ereignis, wie durch die Bitmaske im dwPostRequestNotifications Parameter angegeben.

Beispielsweise kann sich ein HTTP-Modul für die RQ_AUTHENTICATE_REQUEST-Benachrichtigung und die Benachrichtigung nach dem Ereignis für dieselbe Benachrichtigung registrieren. Dabei könnte das Modul zusätzliche Verarbeitungsfunktionen für die Ereignisbenachrichtigung bereitstellen und alle Verarbeitungsdetails in der Benachrichtigung nach dem Ereignis sauber.

Hinweis

Einige Ereignisse verfügen nicht über eine Benachrichtigung nach dem Ereignis. Verwenden Sie 0 für den dwPostRequestNotifications Parameter, wenn Sie keine Benachrichtigung wünschen oder wenn Benachrichtigungen nach dem Ereignis nicht unterstützt werden.

Hinweis

Die Bitmaskenwerte für Benachrichtigungen auf Anforderungsebene werden in der Datei Httpserv.h definiert.

Die SetRequestNotifications -Methode erfordert einen Zeiger auf eine IHttpModuleFactory-Schnittstelle, die IIS verwendet, um eine instance einer CHttpModule Klasse zu erstellen. Diese Factory muss das Erstellen des instance der -Klasse und das CHttpModule Zurückgeben von Fehlermeldungen verarbeiten, wenn die Klasse nicht erstellt werden kann.

Beispiel

Im folgenden Beispiel wird veranschaulicht, wie Sie ein HTTP-Modul erstellen, das die RegisterModule-Funktion und die folgenden Methoden verwendet, um ein Modul für Benachrichtigungen auf globaler Ebene und auf Anforderungsebene zu registrieren.

• Die SetRequestNotifications -Methode registriert eine CHttpModule Klasse für eine OnBeginRequest-Benachrichtigung auf Anforderungsebene.

• Die SetPriorityForRequestNotification-Methode legt die Priorität des Moduls für Benachrichtigungen auf Anforderungsebene fest.

• Die SetGlobalNotifications-Methode registriert eine CGlobalModule-Klasse für eine OnGlobalPreBeginRequest-Benachrichtigung auf globaler Ebene.

• Die SetPriorityForGlobalNotification-Methode legt die Priorität des Moduls für Benachrichtigungen auf globaler Ebene fest.

  Das Modul reagiert auf die registrierten Benachrichtigungen und schreibt Einträge in das Anwendungsprotokoll im Ereignisanzeige.

Hinweis

In den Einträgen im Ereignisanzeige wird "IISADMIN" als Ereignisquelle angezeigt.

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

// Create a global handle for the Event Viewer.
HANDLE g_hEventLog;

// Define the method that writes to the Event Viewer.
BOOL WriteEventViewerLog(LPCSTR szBuffer[], WORD wNumStrings);

// Create the HTTP module class.
class MyHttpModule : public CHttpModule
{
public:
    REQUEST_NOTIFICATION_STATUS
    OnBeginRequest(
        IN IHttpContext * pHttpContext,
        IN IHttpEventProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pHttpContext );
        UNREFERENCED_PARAMETER( pProvider );

        // Create an array of strings.
        LPCSTR szBuffer[2] = {"MyHttpModule","OnBeginRequest"};
        // Write the strings to the Event Viewer.
        WriteEventViewerLog(szBuffer,2);

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

// Create the module's global class.
class MyGlobalModule : public CGlobalModule
{
public:
    GLOBAL_NOTIFICATION_STATUS
    OnGlobalPreBeginRequest(
        IN IPreBeginRequestProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pProvider );
        
        // Create an array of strings.
        LPCSTR szBuffer[2] = {"MyGlobalModule","OnGlobalPreBeginRequest"};
        // Write the strings to the Event Viewer.
        WriteEventViewerLog(szBuffer,2);

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

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

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

    ~MyGlobalModule()
    {
        // Test whether the handle for the Event Viewer is open.
        if (NULL != g_hEventLog)
        {
            DeregisterEventSource( g_hEventLog );
            g_hEventLog = NULL;
        }
    }
};

// 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 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;
    }
};

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

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

    // Create an HRESULT to receive return values from methods.
    HRESULT hr;

    // Set the request notifications.
    hr = pModuleInfo->SetRequestNotifications(
        new MyHttpModuleFactory,
        RQ_BEGIN_REQUEST, 0 );

    // Test for an error and exit if necessary.
    if (FAILED(hr))
    {
        return hr;
    }

    // Set the request priority.
    hr = pModuleInfo->SetPriorityForRequestNotification(
        RQ_BEGIN_REQUEST,PRIORITY_ALIAS_MEDIUM);

    // Test for an error and exit if necessary.
    if (FAILED(hr))
    {
        return hr;
    }

    // Create an instance of the global module class.
    MyGlobalModule * pGlobalModule = new MyGlobalModule;
 
    // Test for an error.
    if (NULL == pGlobalModule)
    {
        return HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY);
    }
 
    // Set the global notifications.
    hr = pModuleInfo->SetGlobalNotifications(
        pGlobalModule, GL_PRE_BEGIN_REQUEST );

    // Test for an error and exit if necessary.
    if (FAILED(hr))
    {
        return hr;
    }

    // Set the global priority.
    hr = pModuleInfo->SetPriorityForGlobalNotification(
        GL_PRE_BEGIN_REQUEST,PRIORITY_ALIAS_LOW);

    // Test for an error and exit if necessary.
    if (FAILED(hr))
    {
        return hr;
    }

    // Return a success status;
    return S_OK;
}

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 Schalters /EXPORT:RegisterModule 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) Aufrufkonvention verwenden, anstatt die Aufrufkonvention 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 unter 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 unter 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
PFN_REGISTERMODULE-Funktion