IHttpResponse：：SetStatus 方法

發行項
07/19/2023

設定回應的 HTTP 狀態。

語法

virtual HRESULT SetStatus(  
   IN USHORT statusCode,  
   IN PCSTR pszReason,  
   IN USHORT uSubStatus = 0,  
   IN HRESULT hrErrorToReport = S_OK,  
   IN INativeSectionException* pException = NULL  
) = 0;

參數

statusCode
[IN]要設定的 HTTP 狀態碼。

pszReason
[IN]字串的指標，其中包含要設定的 HTTP 狀態文字。

uSubStatus
[IN]要設定的選擇性 HTTP 子狀態碼。

hrErrorToReport
[IN]與回應狀態碼相關聯的選擇性 Win32 錯誤。

pException
[IN]選擇性 INativeSectionException 介面的指標。

傳回值

HRESULT。可能的值包括 (但不限於) 下表中的這些值。

值	描述
S_OK	表示作業成功。
ERROR_INVALID_DATA	表示資料無效 (例如，狀態文字中的資料太長) 。
ERROR_NOT_ENOUGH_MEMORY	表示記憶體不足，無法執行作業。

備註

方法 SetStatus 會設定 HTTP 回應狀態，其中包含狀態碼、子狀態碼、狀態文字、Win32 錯誤 (如果有與回應相關聯的) ，以及選擇性的 INativeSectionException 介面。

範例

下列程式碼範例示範如何使用 GetStatus 方法來建立擷取 HTTP 回應狀態的 HTTP 模組。範例模組會將 HTTP 回應狀態的內容傳回給用戶端，然後呼叫 SetStatus 方法，將回應狀態設定為「200 OK」，讓用戶端一律會收到結果。

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

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

        // Create buffers for the HTTP status fields.
        USHORT uStatusCode;
        USHORT uSubStatus;
        PCSTR  pszReason;
        USHORT chReason;
        PCWSTR pszModule;
        DWORD  pdwNotification;

        // 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)
        {
            // Retrieve the current HTTP status.
            pHttpResponse->GetStatus(
                &uStatusCode,&uSubStatus,&pszReason,&chReason,
                &hr,&pszModule,&pdwNotification,NULL);

            // Test for an error.
            if (NULL != pszReason)
            {
                // 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 buffer for the return message.
                char szBuffer[256];

                // Format the HTTP status.
                sprintf_s(szBuffer,255,"%u.%u %s",
                    uStatusCode,uSubStatus,pszReason);
                // Return the status to the client.
                WriteResponseMessage(pHttpContext,
                    "HTTP Status: ",szBuffer);

                // Set the HTTP status code.
                uStatusCode = 200;
                // Set the HTTP substatus code.
                uSubStatus = 0;
                // Set the HTTP status message.
                strcpy_s(szBuffer,255,"OK");
                
                // Set the HTTP status.
                hr = pHttpResponse->SetStatus(uStatusCode,
                    szBuffer,uSubStatus,S_OK);
                
                // Test for an error.
                if (FAILED(hr))
                {
                    // Set the error status.
                    pProvider->SetErrorStatus( hr );
                }

                // End additional processing.
                return RQ_NOTIFICATION_FINISH_REQUEST;
            }
        }

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

private:

    // Create a utility method that inserts a name/value pair into the response.
    HRESULT WriteResponseMessage(
        IHttpContext * pHttpContext,
        PCSTR pszName,
        PCSTR pszValue
    )
    {
        // Create an HRESULT to receive return values from methods.
        HRESULT hr;
        
        // 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 first buffer.
        dataChunk.FromMemory.pBuffer =
            (PVOID) pszName;
        // Set the chunk size to the first buffer size.
        dataChunk.FromMemory.BufferLength =
            (USHORT) strlen(pszName);
        // Insert the data chunk into the response.
        hr = pHttpContext->GetResponse()->WriteEntityChunks(
            &dataChunk,1,FALSE,TRUE,&cbSent);
        // Test for an error.
        if (FAILED(hr))
        {
            // Return the error status.
            return hr;
        }

        // Set the chunk to the second buffer.
        dataChunk.FromMemory.pBuffer =
            (PVOID) pszValue;
        // Set the chunk size to the second buffer size.
        dataChunk.FromMemory.BufferLength =
            (USHORT) strlen(pszValue);
        // Insert the data chunk into the response.
        hr = pHttpContext->GetResponse()->WriteEntityChunks(
            &dataChunk,1,FALSE,TRUE,&cbSent);
        // Test for an error.
        if (FAILED(hr))
        {
            // Return the error status.
            return hr;
        }

        // Return a success status.
        return S_OK;
    }
};

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

// 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 MyHttpModuleFactory,
        RQ_BEGIN_REQUEST,
        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

另請參閱

IHttpResponse 介面
 IHttpResponse：：GetStatus 方法

共用方式為

IHttpResponse：：SetStatus 方法

語法

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

其他資源