PFN_REGISTERMODULE 函数

项目
07/19/2023

定义 RegisterModule 本机代码 HTTP 模块的函数原型。

语法

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

parameters

dwServerVersion
包含 DWORD IIS 主版本号的。

pModuleInfo
指向 IHttpModuleRegistrationInfo 接口的指针。

pGlobalInfo
指向 IHttpServer 接口的指针。

返回值

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

值	说明
S_OK	指示操作成功。

注意

模块可以返回任何有效 HRESULT 值，但至少应返回S_OK，以指示 RegisterModule 函数成功。

备注

PFN_REGISTERMODULE 是函数的 RegisterModule 函数原型，需要所有 HTTP 模块为其 DLL 入口点实现该函数。

创建 HTTP 模块时，模块需要添加以下 RegisterModule 方法：

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

所有 HTTP 模块都必须导出其 RegisterModule 函数，以便 IIS 加载模块。可以通过为 DLL 项目创建模块定义 (.def) 文件或使用开关编译模块/EXPORT:RegisterModule来导出RegisterModule函数。

函数 RegisterModule 需要使用 IHttpModuleRegistrationInfo 接口通过 SetRequestNotifications 和 SetGlobalNotifications 方法注册通知。 RegisterModule 还需要使用 IHttpModuleRegistrationInfo 通过 SetPriorityForRequestNotification 和 SetPriorityForGlobalNotification 方法注册模块优先级。

参数 dwServerVersion 包含加载模块的 IIS 版本的主版本号。例如，对于 IIS 7.0，参数 dwServerVersion 将包含 7。

IIS 调用函数 RegisterModule 时，它会提供一个 IHttpServer 接口，模块可以使用该接口来检索服务器级信息。

注意

不应通过 IHttpTraceContext：：QuickTrace 方法或任何其他方式通过函数实现中的 RegisterModuleIHttpServer：：GetTraceContext 方法) (引发跟踪事件。在 RegisterModule 中引发跟踪事件可能会导致访问冲突，因为请求管道中为时过早。

示例

下面的代码示例演示如何创建简单的“Hello World”HTTP 模块。该模块定义一个导出 RegisterModule 的函数，该函数将 IHttpModuleFactory 接口的实例传递到 IHttpModuleRegistrationInfo：：SetRequestNotifications 方法，并注册 RQ_BEGIN_REQUEST 通知。 IIS 使用 IHttpModuleFactory：：GetHttpModule 方法创建 CHttpModule 类的实例并返回成功状态。 IIS 还使用 IHttpModuleFactory：：Terminate 方法从内存中删除工厂。

RQ_BEGIN_REQUEST发生通知时，IIS 会调用模块的 CHttpModule：：OnBeginRequest 方法来处理当前请求。 OnBeginRequest 清除响应缓冲区并修改响应的 MIME 类型。然后，方法创建一个包含“Hello World”字符串的数据区块，并将该字符串返回到 Web 客户端。最后，模块返回一个状态指示器，通知 IIS 所有通知已完成，然后退出。

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

模块必须导出 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 方法
 IHttpModuleRegistrationInfo：：SetRequestNotifications 方法
 IHttpServer 接口

通过

PFN_REGISTERMODULE 函数

语法

parameters

返回值

备注

示例

要求

另请参阅

反馈

其他资源