IHttpRequest::GetHeader Method

Article
03/09/2018

Returns the value of a specified HTTP header.

Syntax

virtual PCSTR GetHeader(  
   IN PCSTR pszHeaderName,  
   OUT USHORT* pcchHeaderValue = NULL  
) const = 0;  
  
virtual PCSTR GetHeader(  
   IN HTTP_HEADER_ID ulHeaderIndex,  
   OUT USHORT* pcchHeaderValue = NULL  
) const = 0;

Parameters

pszHeaderName
[IN] A pointer to a string that contains the name of the header to return.

ulHeaderIndex
[IN] The ID of the HTTP header to return.

pcchHeaderValue
[OUT] A pointer to an unsigned long integer that receives the length of the returned header value.

Return Value

A pointer to a string that contains the specified header, or 0 if the header was not found.

Remarks

The GetHeader method returns the value of an HTTP header for the current request. There are two overloaded versions of the GetHeader method. One specifies the header by using a string that is contained in the pszHeaderName parameter. The other overload uses an unsigned long integer that is contained in the ulHeaderIndex parameter. After you call the GetHeader method, the pcchHeaderValue parameter will contain the length, in characters, of the header value, not including the terminating character. pcchHeaderValue will be 0 if the header is not found.

The header name specified by the pszHeaderName parameter can be a custom header or a header defined in Request for Comments (RFC) 1945, "Hypertext Transfer Protocol -- HTTP/1.0," or RFC 2616, "Hypertext Transfer Protocol -- HTTP/1.1.

Note

The pszHeaderName parameter cannot be set to null.

The ulHeaderIndex parameter specifies the ID of an HTTP header that is listed in the HTTP_HEADER_ID enumeration.

Note

The HTTP_HEADER_ID enumeration is defined in the Http.h header file.

Example

The following code example demonstrates how to use both versions of the GetHeader method to create an HTTP module that retrieves the User-Agent and Accept-Language HTTP headers for the request.

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

        // Create buffers to store the returned header values.
        PCSTR pszUserAgent;
        PCSTR pszAcceptLanguage;

        // Create buffers to store lengths of the returned header values.
        USHORT cchUserAgent;
        USHORT cchAcceptLanguage;

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

        // Test for an error.
        if (pHttpRequest != NULL)
        {
            // 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);

            // Look for the "User-Agent" header.
            pszUserAgent = pHttpRequest->GetHeader("User-Agent",&cchUserAgent);

            // The header length will be 0 if the header was not found.
            if (cchUserAgent == 0)
            {
                // Return a status message.
                WriteResponseMessage(pHttpContext,
                    "User-Agent: ","(none)");
            }
            else
            {
                // Allocate space to store the header.
                pszUserAgent = (PCSTR) pHttpContext->AllocateRequestMemory( cchUserAgent + 1 );
                
                // Test for an error.
                if (pszUserAgent==NULL)
                {
                    // Set the error status.
                    hr = HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY);
                    pProvider->SetErrorStatus( hr );
                    // End additional processing.
                    return RQ_NOTIFICATION_FINISH_REQUEST;
                }

                // Retrieve the "User-Agent" header.
                pszUserAgent = pHttpRequest->GetHeader("User-Agent",&cchUserAgent);
                // Test for an error.
                if (pszUserAgent!=NULL)
                {
                    // Return the header information.
                    WriteResponseMessage(pHttpContext,
                        "User-Agent: ",pszUserAgent);
                }
            }

            // Look for the "Accept-Language" header.
            pszAcceptLanguage = pHttpRequest->GetHeader(HttpHeaderAcceptLanguage,&cchAcceptLanguage);

            // The header length will be 0 if the header was not found.
            if (cchAcceptLanguage == 0)
            {
                // Return a status message.
                WriteResponseMessage(pHttpContext,
                    "\nAccept-Language: ","(none)");
            }
            else
            {
                // Allocate space to store the header.
                pszAcceptLanguage = (PCSTR) pHttpContext->AllocateRequestMemory( cchAcceptLanguage + 1 );
                
                // Test for an error.
                if (pszAcceptLanguage==NULL)
                {
                    // Set the error status.
                    hr = HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY);
                    pProvider->SetErrorStatus( hr );
                    // End additional processing.
                    return RQ_NOTIFICATION_FINISH_REQUEST;
                }

                // Retrieve the "Accept-Language" header.
                pszAcceptLanguage = pHttpRequest->GetHeader(HttpHeaderAcceptLanguage,&cchAcceptLanguage);                
                
                // Test for an error.
                if (pszAcceptLanguage!=NULL)
                {
                    // Return the header information.
                    WriteResponseMessage(pHttpContext,
                        "\nAccept-Language: ",pszAcceptLanguage);
                }
            }
            // 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
    );
}

Your module must export the RegisterModule function. You can export this function by creating a module definition (.def) file for your project, or you can compile the module by using the /EXPORT:RegisterModule switch. For more information, see Walkthrough: Creating a Request-Level HTTP Module By Using Native Code.

You can optionally compile the code by using the __stdcall (/Gz) calling convention instead of explicitly declaring the calling convention for each function.

Requirements

Type	Description
Client	- IIS 7.0 on Windows Vista - IIS 7.5 on Windows 7 - IIS 8.0 on Windows 8 - IIS 10.0 on Windows 10
Server	- IIS 7.0 on Windows Server 2008 - IIS 7.5 on Windows Server 2008 R2 - IIS 8.0 on Windows Server 2012 - IIS 8.5 on Windows Server 2012 R2 - IIS 10.0 on Windows Server 2016 Technical Preview
Product	- 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

Share via