IHttpResponse::SetHeader Method

 

Sets or appends the value of a specified HTTP response header.

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;  

Parameters

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

ulHeaderIndex
[IN] The ID of an HTTP header to set.

pszHeaderValue
[IN] A pointer to a string that contains the value of the header to set.

cchHeaderValue
[IN] The length, in characters, of the header value, not including the \0 character.

fReplace
[IN] Specifies whether the existing header should be overwritten.

Return Value

An HRESULT. Possible values include, but are not limited to, those in the following table.

Value	Description
S_OK	Indicates that the operation was successful.
ERROR_INVALID_DATA	Indicates that the data is not valid (for example, the data in the header is too long).
ERROR_INVALID_PARAMETER	Indicates that the specified parameter is not valid (for example, the parameter is set to NULL).
ERROR_NOT_ENOUGH_MEMORY	Indicates that there is insufficient memory to perform the operation.

Remarks

The SetHeader method sets the value of an HTTP header for the current response. There are two overloaded versions of the SetHeader method. The first enables you to specify 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.

Note

You should not use the overload that uses the ulHeaderIndex parameter to set the value of the Server header, because your value will be appended to the existing header value. Use the pszHeaderName parameter instead.

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 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.

If the fReplace parameter is true, the specified header value will replace the existing header value if the header exists. If fReplace is false, the specified header value should be appended to the existing header and separated from the header itself by a comma.

Note

Other modules or handlers may call the SetHeader method to replace your value or append values to the value that you have specified.

Example

The following code example demonstrates how to use both overloads of the SetHeader method to replace the HTTP Content-Type and Server headers with custom values and set the HTTP Refresh header to a specific number of seconds.

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

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

        // Create an HRESULT to receive return values from methods.
        HRESULT hr;
        
        // Set the "Refresh" header name.
        char szRefreshName[] = "Refresh";
        // Set the "Refresh" header value.
        char szRefreshValue[] = "30";
        // Set the "Content-Type" header value.
        char szContentType[] = "text/plain";
        // Set the "Server" header value.
        char szServerValue[] = "MyServer/7.0";

        // Retrieve a pointer to the response.
        IHttpResponse * pHttpResponse = pHttpContext->GetResponse();

        // Test for an error.
        if (pHttpResponse != NULL)
        {

            // Set the "Refresh" header.
            hr = pHttpResponse->SetHeader(
                szRefreshName,szRefreshValue,
                (USHORT)strlen(szRefreshValue),FALSE);

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

            // Set the "Content-Type" header.
            hr = pHttpResponse->SetHeader(
                HttpHeaderContentType,szContentType,
                (USHORT)strlen(szContentType),TRUE);

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

            // Set the "Server" header.
            hr = pHttpResponse->SetHeader(
                "Server",szServerValue,
                (USHORT)strlen(szServerValue),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;
        }            
    }

    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_SEND_RESPONSE,
        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

See Also

IHttpResponse Interface
IHttpResponse::DeleteHeader Method
IHttpResponse::GetHeader Method