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

參數

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 通知。
模組會建立包含 CHttpModuleOnBeginRequest、 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) 而不是明確宣告每個函式的呼叫慣例。

規格需求

類型	描述
Client	- 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
標頭	Httpserv.h

另請參閱

CHttpModule 類別

共用方式為

CHttpModule：：OnAsyncCompletion 方法

語法

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

其他資源