IHttpRequest::SetHeader-Methode

Artikel
07/19/2023

Legt den Wert eines angegebenen HTTP-Anforderungsheaders fest oder fügt den Wert an.

Syntax

virtual HRESULT SetHeader(  
   IN PCSTR pszHeaderName,  
   IN PCSTR pszHeaderValue,  
   IN USHORT cchHeaderValue,  
   IN BOOL fReplace  
) = 0;  
  
virtual HRESULT SetHeader(  
   IN HTTP_HEADER_ID ulHeaderIndex,  
   IN PCSTR pszHeaderValue,  
   IN USHORT cchHeaderValue,  
   IN BOOL fReplace  
) = 0;

Parameter

pszHeaderName
[IN] Ein Zeiger auf eine Zeichenfolge, die den Namen des festzulegenden HTTP-Headers enthält.

ulHeaderIndex
[IN] Die ID eines festzulegenden HTTP-Headers.

pszHeaderValue
[IN] Ein Zeiger auf eine Zeichenfolge, die den Wert des festzulegenden Headers enthält.

cchHeaderValue
[IN] Die Länge des Headerwerts in Zeichen, ohne das Zeichen \0.

fReplace
[IN] true , um den vorhandenen Header zu überschreiben; falseandernfalls .

Rückgabewert

HRESULT. Mögliches Werte (aber nicht die Einzigen) sind die in der folgenden Tabelle.

Wert	BESCHREIBUNG
S_OK	Gibt an, dass der Vorgang erfolgreich war.
ERROR_INVALID_DATA	Gibt an, dass die Daten ungültig sind (z. B. sind die Daten im Header zu lang).
ERROR_INVALID_PARAMETER	Gibt an, dass der angegebene Parameter ungültig ist (z. B. ist der Parameter NULL).
ERROR_NOT_ENOUGH_MEMORY	Gibt an, dass nicht genügend Arbeitsspeicher zum Ausführen des Vorgangs vorhanden ist.

Bemerkungen

Die SetHeader -Methode legt den Wert eines HTTP-Headers für die aktuelle Anforderung fest. Es gibt zwei überladene Versionen der SetHeader -Methode. Mit einer können Sie den Header mithilfe einer Zeichenfolge angeben, die pszHeaderName im Parameter enthalten ist. Die andere Überladung verwendet eine ganze Zahl ohne Vorzeichen, die ulHeaderIndex im -Parameter enthalten ist.

Der durch den Parameter angegebene Headername kann ein benutzerdefinierter Header oder ein Header sein, der pszHeaderName in Request for Comments (RFC) 1945, "Hypertext Transfer Protocol -- HTTP/1.0", oder RFC 2616, "Hypertext Transfer Protocol -- HTTP/1.1" definiert ist.

Hinweis

Der pszHeaderName Parameter kann nicht auf NULL festgelegt werden.

Der ulHeaderIndex Parameter gibt die ID eines HTTP-Headers an, der in der HTTP_HEADER_ID Enumeration aufgeführt ist.

Hinweis

Die HTTP_HEADER_ID Enumeration wird in der Http.h-Headerdatei definiert.

Wenn der fReplace Parameter ist true, ersetzt der angegebene Headerwert den vorhandenen Headerwert, wenn der Header vorhanden ist. Wenn fReplace ist false, sollten Sie den angegebenen Headerwert an den vorhandenen Header anfügen und den Wert vom Header selbst durch ein Komma trennen.

Beispiel

Im folgenden Codebeispiel wird veranschaulicht, wie sie beide Überladungen der SetHeader -Methode verwenden, um ein HTTP-Modul zu erstellen, das die HTTP User-Agent - und Accept-Language Header durch neue Werte ersetzt.


#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 an HRESULT to receive return values from methods.
        HRESULT hr;

        // Specify the "User-Agent" header name.
        char szHeaderName[] = "User-Agent";
        // Specify the "User-Agent" header value.
        char szUserAgent[] = "Test Browser";
        // Specify the "Accept-Language" header value.
        char szAcceptLanguage[] = "en-ie";

        // Retrieve a pointer to the request.
        IHttpRequest * pHttpRequest = pHttpContext->GetRequest();

        // Test for an error.
        if (pHttpRequest != NULL)
        {
            // Replace the "User-Agent" header.
            hr = pHttpRequest->SetHeader(
                szHeaderName,szUserAgent,
                (USHORT)strlen(szUserAgent),true);

            // Test for an error.
            if (FAILED(hr))
            {
                // Set the error status.
                pProvider->SetErrorStatus( hr );
                // End additional processing.
                return RQ_NOTIFICATION_FINISH_REQUEST;
            }

            // Replace the "Accept-language" header.
            hr = pHttpRequest->SetHeader(
                HttpHeaderAcceptLanguage,szAcceptLanguage,
                (USHORT)strlen(szAcceptLanguage),true);

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

// 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;
        }            
    }
/* MERGEFORMAT 16 Aug 07  5:41 PM */
    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
    );
}

Ihr Modul muss die Funktion RegisterModule exportieren. Sie können diese Funktion exportieren, indem Sie eine Moduldefinitionsdatei (.def) für Ihr Projekt erstellen, oder Sie können das Modul mithilfe des /EXPORT:RegisterModule Switches kompilieren. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Erstellen eines Request-Level HTTP-Moduls mithilfe von nativem Code.

Sie können den Code optional kompilieren, indem Sie die __stdcall (/Gz) aufrufende Konvention verwenden, anstatt die aufrufende Konvention für jede Funktion explizit zu deklarieren.

Anforderungen

type	BESCHREIBUNG
Client	– IIS 7.0 unter Windows Vista – IIS 7.5 unter Windows 7 – IIS 8.0 unter Windows 8 – IIS 10.0 auf Windows 10
Server	– IIS 7.0 unter Windows Server 2008 – IIS 7.5 unter Windows Server 2008 R2 – IIS 8.0 unter Windows Server 2012 – IIS 8.5 unter Windows Server 2012 R2 – IIS 10.0 auf Windows Server 2016
Produkt	– 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

Weitere Informationen

IHttpRequest-Schnittstelle
IHttpRequest::D eleteHeader-Methode
IHttpRequest::GetHeader-Methode

Freigeben über