CHttpModule：：OnAsyncCompletion 方法

项目
07/19/2023

表示将处理异步完成事件的方法，该事件在异步操作完成处理后发生。

语法

virtual REQUEST_NOTIFICATION_STATUS OnAsyncCompletion(  
   IN IHttpContext* pHttpContext,  
   IN DWORD dwNotification,  
   IN BOOL fPostNotification,  
   IN OUT IHttpEventProvider* pProvider,  
   IN IHttpCompletionInfo* pCompletionInfo  
);

parameters

pHttpContext
[IN]指向 IHttpContext 接口的指针。

dwNotification
[IN]一个 DWORD 值，该值包含相关通知的位掩码。

fPostNotification
[IN] true 指示通知用于事件后;否则为 false。

pProvider
[IN]指向 IHttpEventProvider 接口的指针。

pCompletionInfo
[IN]指向 IHttpCompletionInfo 接口的指针。

返回值

REQUEST_NOTIFICATION_STATUS值。

备注

与通过注册特定通知调用的许多其他 CHttpModule 方法不同，IIS 仅在异步操作完成时调用模块的 OnAsyncCompletion 方法。例如，当请求级模块调用 IHttpResponse：：WriteEntityChunks 方法并指定异步完成时，IIS 将在操作完成时调用模块的 OnAsyncCompletion 方法。

当 IIS 调用 OnAsyncCompletion 方法时，它将在参数中 dwNotification 指定通知类型，并使用参数指示通知是针对事件还是针对事件 fPostNotification 后事件。 IIS 还提供 IHttpCompletionInfo 由参数指向的 pCompletionInfo 接口。可以使用此接口检索有关异步完成的其他信息。

示例

下面的代码示例演示如何创建执行以下任务的 HTTP 模块：

模块注册 RQ_BEGIN_REQUEST 和 RQ_MAP_REQUEST_HANDLER 通知。
该模块创建一个 CHttpModule 包含 OnBeginRequest、 OnMapRequestHandler 和 OnAsyncCompletion 方法的类。
当 Web 客户端请求 URL 时，IIS 会调用模块的 OnBeginRequest 方法。此方法执行以下任务：
1. 清除现有响应缓冲区并设置响应的 MIME 类型。
2. 创建一个示例字符串，并将其异步返回给 Web 客户端。
3. 测试错误或异步完成。如果异步完成处于挂起状态，则模块会向集成请求处理管道返回挂起的通知状态。
IIS 调用模块的 OnMapRequestHandler 方法。此方法执行以下任务：
1. 将当前响应缓冲区刷新到 Web 客户端。
2. 测试错误或异步完成。如果异步完成处于挂起状态，则模块会向管道返回挂起的通知状态。
如果需要异步完成，IIS 会调用模块的 OnAsyncCompletion 方法。此方法执行以下任务：
1. 测试有效 IHttpCompletionInfo 接口。如果传递了有效的 IHttpCompletionInfo 接口，该方法将分别调用 GetCompletionBytes 和 GetCompletionStatus 方法来检索已完成的字节并返回异步操作的状态。
2. 创建包含完成信息的字符串，并将信息作为事件写入事件查看器的应用程序日志。
模块从内存中删除类， CHttpModule 然后退出。

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

// Create the module class.
class MyHttpModule : 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;
        // Buffer to store the byte count.
        DWORD cbSent = 0;
        // Buffer to store if asyncronous completion is pending.
        BOOL fCompletionExpected = false;
        // Create an example string to return to the Web client.
        char szBuffer[] = "Hello World!";
        
        // Clear the existing response.
        pHttpContext->GetResponse()->Clear();
        // Set the MIME type to plain text.
        pHttpContext->GetResponse()->SetHeader(
            HttpHeaderContentType,"text/plain",
            (USHORT)strlen("text/plain"),TRUE);
        
        // Create a data chunk.
        HTTP_DATA_CHUNK dataChunk;
        // Set the chunk to a chunk in memory.
        dataChunk.DataChunkType = HttpDataChunkFromMemory;
        // Set the chunk to the buffer.
        dataChunk.FromMemory.pBuffer =
            (PVOID) szBuffer;
        // Set the chunk size to the buffer size.
        dataChunk.FromMemory.BufferLength =
            (USHORT) strlen(szBuffer);
        // Insert the data chunk into the response.
        hr = pHttpContext->GetResponse()->WriteEntityChunks(
            &dataChunk,1,TRUE,TRUE,&cbSent,&fCompletionExpected);

        // Test for a failure.
        if (FAILED(hr))
        {
            // Set the HTTP status.
            pHttpContext->GetResponse()->SetStatus(
                500,"Server Error",0,hr);
            // End additional processing.
            return RQ_NOTIFICATION_FINISH_REQUEST;
        }
        
        // Test for pending asynchronous operations.
        if (fCompletionExpected)
        {
            return RQ_NOTIFICATION_PENDING;
        }

        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }
    
    REQUEST_NOTIFICATION_STATUS
    OnMapRequestHandler(
        IN IHttpContext * pHttpContext,
        IN IMapHandlerProvider * pProvider
    )
    {
        // Create an HRESULT to receive return values from methods.
        HRESULT hr;
        // Buffer to store the byte count.
        DWORD cbSent = 0;
        // Buffer to store if asyncronous completion is pending.
        BOOL fCompletionExpected = false;

        // Flush the response to the client.
        hr = pHttpContext->GetResponse()->Flush(
            TRUE,FALSE,&cbSent,&fCompletionExpected);

        // Test for a failure.
        if (FAILED(hr))
        {
            // Set the HTTP status.
            pHttpContext->GetResponse()->SetStatus(
                500,"Server Error",0,hr);
        }

        // Test for pending asynchronous operations.
        if (fCompletionExpected)
        {
            return RQ_NOTIFICATION_PENDING;
        }

        // End additional processing.
        return RQ_NOTIFICATION_CONTINUE;
    }

    REQUEST_NOTIFICATION_STATUS
        OnAsyncCompletion(
        IN IHttpContext * pHttpContext,
        IN DWORD dwNotification,
        IN BOOL fPostNotification,
        IN IHttpEventProvider * pProvider,
        IN IHttpCompletionInfo * pCompletionInfo
        )
    {        
        if ( NULL != pCompletionInfo )
        {
            // Create strings for completion information.
            char szNotification[256] = "";
            char szBytes[256] = "";
            char szStatus[256] = "";

            // Retrieve and format the completion information.
            sprintf_s(szNotification,255,"Notification: %u",
                dwNotification);
            sprintf_s(szBytes,255,"Completion Bytes: %u",
                pCompletionInfo->GetCompletionBytes());
            sprintf_s(szStatus,255,"Completion Status: 0x%08x",
                pCompletionInfo->GetCompletionStatus());

            // Create an array of strings.
            LPCSTR szBuffer[3] = {szNotification,szBytes,szStatus};
            // Write the strings to the Event Viewer.
            WriteEventViewerLog(szBuffer,3);
        }
        
        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }

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

    ~MyHttpModule(void)
    {
        // Test if the handle for the Event Viewer is open.
        if (NULL != m_hEventLog)
        {
            // Close the handle to the Event Viewer.
            DeregisterEventSource( m_hEventLog );
            m_hEventLog = NULL;
        }
    }

private:

    // Handle for the Event Viewer.
    HANDLE m_hEventLog;

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

// 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 we 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 );

    return pModuleInfo->SetRequestNotifications(
        new MyHttpModuleFactory,
        RQ_BEGIN_REQUEST | RQ_MAP_REQUEST_HANDLER,
        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

另请参阅

CHttpModule 类

通过

CHttpModule：：OnAsyncCompletion 方法

语法

parameters

返回值

备注

示例

要求

另请参阅

反馈

其他资源