Método IWinHttpRequest::SetRequestHeader

O método SetRequestHeader adiciona, altera ou exclui um cabeçalho de solicitação HTTP.

Sintaxe

HRESULT SetRequestHeader(
  [in] BSTR Header,
  [in] BSTR Value
);

Parâmetros

Cabeçalho [in]

Especifica o nome do cabeçalho a ser definido, por exemplo, "depth". Esse parâmetro não deve conter dois-pontos e deve ser o texto real do cabeçalho HTTP.

Valor [in]

Especifica o valor do cabeçalho, por exemplo, "infinito".

Valor retornado

Caso contrário, o valor retornado será S_OK com êxito ou um valor de erro.

Comentários

Os cabeçalhos são transferidos entre redirecionamentos. Isso pode criar uma vulnerabilidade de segurança. Para evitar que cabeçalhos sejam transferidos se ocorrer um redirecionamento, use o WINHTTP_STATUS_CALLBACK retorno de chamada para corrigir os cabeçalhos específicos quando ocorrer um redirecionamento.

O método SetRequestHeader permite que o aplicativo de chamada adicione ou exclua um cabeçalho de solicitação HTTP antes de enviar a solicitação. O nome do cabeçalho é fornecido em Cabeçalho e o token ou valor do cabeçalho é fornecido em Valor. Para adicionar um cabeçalho, forneça um nome de cabeçalho e um valor. Se outro cabeçalho já existir com esse nome, ele será substituído. Para excluir um cabeçalho, defina Cabeçalho como o nome do cabeçalho a ser excluído e defina Value como NULL.

O nome e o valor dos cabeçalhos de solicitação adicionados com esse método são validados. Os cabeçalhos devem estar bem formados. Para obter mais informações sobre cabeçalhos HTTP válidos, consulte RFC 2616. Se um cabeçalho inválido for usado, ocorrerá um erro e o cabeçalho não será adicionado.

Observação

Para Windows XP e Windows 2000, consulte a seção Requisitos de tempo de execução da página inicial do WinHTTP.

Exemplos

O exemplo a seguir mostra como abrir uma conexão HTTP, definir um cabeçalho de solicitação, enviar uma solicitação HTTP e ler o texto da resposta. Este exemplo deve ser executado em um prompt de comando.

#include <windows.h>
#include <stdio.h>
#include <objbase.h>

#include "httprequest.h"

#pragma comment(lib, "ole32.lib")
#pragma comment(lib, "oleaut32.lib")

// IID for IWinHttpRequest.
const IID IID_IWinHttpRequest =
{
  0x06f29373,
  0x5c5a,
  0x4b54,
  {0xb0, 0x25, 0x6e, 0xf1, 0xbf, 0x8a, 0xbf, 0x0e}
};

int main()
{
    // Variable for return value
    HRESULT    hr;

    // Initialize COM.
    hr = CoInitialize( NULL );

    IWinHttpRequest *  pIWinHttpRequest = NULL;

    BSTR            bstrResponse = NULL;
    VARIANT         varFalse;
    VARIANT         varEmpty;

    CLSID           clsid;

    VariantInit(&varFalse);
    V_VT(&varFalse)   = VT_BOOL;
    V_BOOL(&varFalse) = VARIANT_FALSE;

    VariantInit(&varEmpty);
    V_VT(&varEmpty) = VT_ERROR;

    hr = CLSIDFromProgID(L"WinHttp.WinHttpRequest.5.1", &clsid);

    if (SUCCEEDED(hr))
    {
        hr = CoCreateInstance(clsid, NULL,
                              CLSCTX_INPROC_SERVER,
                              IID_IWinHttpRequest,
                              (void **)&pIWinHttpRequest);
    }
    if (SUCCEEDED(hr))
    {    // Open WinHttpRequest.
        BSTR bstrMethod  = SysAllocString(L"GET");
        BSTR bstrUrl = SysAllocString(L"https://microsoft.com");
        hr = pIWinHttpRequest->Open(bstrMethod, bstrUrl, varFalse);
        SysFreeString(bstrMethod);
        SysFreeString(bstrUrl);
    }
    if (SUCCEEDED(hr))
    {    // Set request header.
        BSTR bstrName  = SysAllocString(L"Date");
        BSTR bstrValue = SysAllocString(L"Fri, 16 Mar 2001 00:25:54 GMT");
        hr = pIWinHttpRequest->SetRequestHeader(bstrName, bstrValue);
        SysFreeString(bstrName);
        SysFreeString(bstrValue);
    }
    if (SUCCEEDED(hr))
    {    // Send Request.
        hr = pIWinHttpRequest->Send(varEmpty);
    }
    if (SUCCEEDED(hr))
    {    // Get Response headers.
        hr = pIWinHttpRequest->GetAllResponseHeaders(&bstrResponse);
    }
    if (SUCCEEDED(hr))
    {    // Print the response to a console.
        wprintf(L"%.256s",bstrResponse);
    }

    // Release memory.
    if (pIWinHttpRequest)
        pIWinHttpRequest->Release();
    if (bstrResponse)
        SysFreeString(bstrResponse);

    CoUninitialize();
    return 0;
}

O exemplo de script a seguir mostra como abrir uma conexão HTTP, definir um cabeçalho de solicitação e enviar uma solicitação HTTP.

// Instantiate a WinHttpRequest object.
var WinHttpReq = new ActiveXObject("WinHttp.WinHttpRequest.5.1");

// Initialize an HTTP request.  
WinHttpReq.Open("GET", "https://www.microsoft.com", false);

// Add/replace a request header.
WinHttpReq.SetRequestHeader("Date", Date());

// Send the HTTP request.
WinHttpReq.Send();

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP, Windows 2000 Professional com SP3 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003, Windows 2000 Server com SP3 [somente aplicativos da área de trabalho]
Redistribuível	WinHTTP 5.0 e Internet Explorer 5.01 ou posterior no Windows XP e Windows 2000.
IDL	HttpRequest.idl
Biblioteca	Winhttp.lib
DLL	Winhttp.dll

Confira também

IWinHttpRequest

WinHttpRequest

Versões do WinHTTP