IHttpModuleRegistrationInfo：：SetRequestNotifications 方法

项目
2023-07-19

为模块注册请求级别通知。

语法

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

parameters

pModuleFactory
[IN]指向 IHttpModuleFactory 接口的指针。

dwRequestNotifications
[IN]包含要注册的请求通知的位掩码值。 httpserv.h.) 中定义的 (

dwPostRequestNotifications
[IN]包含要注册的事件后通知的位掩码值。 httpserv.h.) 中定义的 (

返回值

HRESULT。可能的值包括（但并不限于）下表中的项。

值	说明
S_OK	指示操作成功。
ERROR_ALREADY_EXISTS	指示模块已注册。

备注

方法 SetRequestNotifications 为 CHttpModule 类注册请求级通知。模块可以为每个通知注册两个事件：事件通知（由参数中的 dwRequestNotifications 位掩码指示）和事件后通知（由参数中的 dwPostRequestNotifications 位掩码指示）。

例如，HTTP 模块可以注册 RQ_AUTHENTICATE_REQUEST 通知和同一通知的事件后通知。这样做时，模块可以为事件通知提供额外的处理功能，并清理事件后通知中的任何处理详细信息。

注意

某些事件没有事后通知。如果不需要通知或不支持事件后通知，请使用 0 参数 dwPostRequestNotifications 。

注意

请求级别通知的位掩码值在 Httpserv.h 文件中定义。

方法 SetRequestNotifications 需要指向 IHttpModuleFactory 接口的指针，IIS 将使用该指针创建类的 CHttpModule 实例。如果无法创建类，则此工厂必须处理类实例的 CHttpModule 创建和返回任何错误消息。

示例

以下示例演示如何创建一个 HTTP 模块，该模块使用 RegisterModule 函数和以下方法为全局级别和请求级别通知注册模块。

方法SetRequestNotifications为请求级别 OnBeginRequest 通知注册CHttpModule类。
SetPriorityForRequestNotification 方法设置模块请求级通知的优先级。
SetGlobalNotifications 方法为全局级别的 OnGlobalPreBeginRequest 通知注册 CGlobalModule 类。
SetPriorityForGlobalNotification 方法设置模块全局级别通知的优先级。

该模块响应已注册的通知，并将条目写入事件查看器的应用程序日志。

注意

事件查看器中的条目将显示“IISADMIN”作为事件源。

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

模块必须导出 RegisterModule 函数。可以通过为项目创建模块定义 (.def) 文件导出此函数，也可以使用开关编译模块 /EXPORT:RegisterModule 。有关详细信息，请参阅演练：使用本机代码创建Request-Level HTTP 模块。

可以选择使用调用约定编译代码， __stdcall (/Gz) 而不是为每个函数显式声明调用约定。

要求

类型	说明
客户端	- Windows Vista 上的 IIS 7.0 - Windows 7 上的 IIS 7.5 - Windows 8 上的 IIS 8.0 - Windows 10 上的 IIS 10.0
服务器	- Windows Server 2008 上的 IIS 7.0 - Windows Server 2008 R2 上的 IIS 7.5 - Windows Server 2012 上的 IIS 8.0 - Windows Server 2012 R2 上的 IIS 8.5 - Windows Server 2016 上的 IIS 10.0
产品	- 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

另请参阅

IHttpModuleRegistrationInfo 接口
 IHttpModuleRegistrationInfo：：SetGlobalNotifications 方法
 IHttpModuleRegistrationInfo：：SetPriorityForGlobalNotification 方法
 IHttpModuleRegistrationInfo：：SetPriorityForRequestNotification 方法
 PFN_REGISTERMODULE 函数

通过

IHttpModuleRegistrationInfo：：SetRequestNotifications 方法

语法

parameters

返回值

备注

示例

要求

另请参阅

反馈

其他资源