Compartilhar via


Função WinHttpAddRequestHeaders (winhttp.h)

A função WinHttpAddRequestHeaders adiciona um ou mais cabeçalhos de solicitação HTTP ao identificador de solicitação HTTP.

Sintaxe

WINHTTPAPI BOOL WinHttpAddRequestHeaders(
  [in] HINTERNET hRequest,
  [in] LPCWSTR   lpszHeaders,
  [in] DWORD     dwHeadersLength,
  [in] DWORD     dwModifiers
);

Parâmetros

[in] hRequest

Um identificador HINTERNET retornado por uma chamada para a função WinHttpOpenRequest .

[in] lpszHeaders

Um ponteiro para uma variável de cadeia de caracteres que contém os cabeçalhos a serem acrescentados à solicitação. Cada cabeçalho, exceto o último, deve ser encerrado por um CR/LF (retorno de carro/alimentação de linha).

[in] dwHeadersLength

Um valor inteiro longo sem sinal que contém o comprimento, em caracteres, de pwszHeaders. Se esse parâmetro for -1L, a função pressupõe que pwszHeaders seja terminado como zero (ASCIIZ) e o comprimento será calculado.

[in] dwModifiers

Um valor inteiro longo sem sinal que contém os sinalizadores usados para modificar a semântica dessa função. Pode ser um ou mais dos sinalizadores a seguir.

Valor Significado
WINHTTP_ADDREQ_FLAG_ADD
Adiciona o cabeçalho se ele não existir. Usado com WINHTTP_ADDREQ_FLAG_REPLACE.
WINHTTP_ADDREQ_FLAG_ADD_IF_NEW
Adiciona o cabeçalho somente se ele ainda não existir; caso contrário, um erro será retornado.
WINHTTP_ADDREQ_FLAG_COALESCE
Mescla cabeçalhos de mesmo nome.
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA
Mescla cabeçalhos de mesmo nome usando uma vírgula. Por exemplo, adicionar "Aceitar: texto/*" seguido por "Aceitar: áudio/*" com esse sinalizador resulta em um único cabeçalho "Aceitar: texto/*, áudio/*". Isso faz com que o primeiro cabeçalho encontrado seja mesclado. O aplicativo de chamada deve garantir um esquema coeso em relação a cabeçalhos mesclados e separados.
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON
Mescla cabeçalhos de mesmo nome usando ponto e vírgula.
WINHTTP_ADDREQ_FLAG_REPLACE
Substitui ou remove um cabeçalho. Se o valor do cabeçalho estiver vazio e o cabeçalho for encontrado, ele será removido. Se o valor não estiver vazio, ele será substituído.

Valor retornado

Retornará TRUE se tiver êxito ou FALSE caso contrário. Para obter informações de erro estendidas, chame GetLastError. Entre os códigos de erro retornados estão os seguintes.

Código do Erro Descrição
ERROR_WINHTTP_INCORRECT_HANDLE_STATE
A operação solicitada não pode ser executada porque o identificador fornecido não está no estado correto.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
O tipo de identificador fornecido está incorreto para esta operação.
ERROR_WINHTTP_INTERNAL_ERROR
Ocorreu um erro interno.
ERROR_NOT_ENOUGH_MEMORY
Não havia memória suficiente disponível para concluir a operação solicitada.

Comentários

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

Mesmo quando WinHTTP é usado no modo assíncrono (ou seja, quando WINHTTP_FLAG_ASYNC foi definido no WinHttpOpen), essa função opera de forma síncrona. O valor retornado indica êxito ou falha. Para obter informações de erro estendidas, chame GetLastError.

A função WinHttpAddRequestHeaders acrescenta cabeçalhos de formato livre adicionais ao identificador de solicitação HTTP e destina-se ao uso por clientes sofisticados que exigem controle detalhado sobre a solicitação exata enviada ao servidor HTTP.

O nome e o valor dos cabeçalhos de solicitação adicionados com essa função 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, essa função falhará e GetLastError retornará ERROR_INVALID_PARAMETER. O cabeçalho inválido não foi adicionado.

Se você estiver enviando um cabeçalho de solicitação Date: , poderá usar a função WinHttpTimeFromSystemTime para criar estrutura para o cabeçalho.

Para WinHttpAddRequestHeaders básicos, o aplicativo pode passar vários cabeçalhos em um único buffer.

Um aplicativo também pode usar WinHttpSendRequest para adicionar cabeçalhos adicionais ao identificador de solicitação HTTP antes de enviar uma solicitação.

Nota Para obter mais informações, consulte Requisitos de tempo de execução.
 

Exemplos

O exemplo de código a seguir inclui um cabeçalho If-Modified-Since em uma solicitação. O cabeçalho de resposta é interpretado para determinar se o documento de destino foi atualizado.


  DWORD dwSize = sizeof(DWORD);
  DWORD dwStatusCode = 0;
  BOOL  bResults = FALSE;
  HINTERNET hSession = NULL,
        hConnect = NULL,
        hRequest = NULL;

  // Use WinHttpOpen to obtain a session handle.
  hSession = WinHttpOpen( L"A WinHTTP Example Program/1.0", 
                          WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                          WINHTTP_NO_PROXY_NAME, 
                          WINHTTP_NO_PROXY_BYPASS,
                          0 );

  // Specify an HTTP server.
  if( hSession )
    hConnect = WinHttpConnect( hSession,
                               L"www.microsoft.com",
                               INTERNET_DEFAULT_HTTP_PORT,
                               0 );

  // Create an HTTP Request handle.
  if( hConnect )
    hRequest = WinHttpOpenRequest( hConnect,
                                   L"GET",
                                   NULL, 
                                   NULL,
                                   WINHTTP_NO_REFERER, 
                                   WINHTTP_DEFAULT_ACCEPT_TYPES,
                                   0 );

  // Add a request header.
  if( hRequest )
    bResults = WinHttpAddRequestHeaders( hRequest, 
                 L"If-Modified-Since: Mon, 20 Nov 2000 20:00:00 GMT",
                                         (ULONG)-1L,
                                         WINHTTP_ADDREQ_FLAG_ADD );

  // Send a Request.
  if( bResults ) 
    bResults = WinHttpSendRequest( hRequest, 
                                   WINHTTP_NO_ADDITIONAL_HEADERS,
                                   0,
                                   WINHTTP_NO_REQUEST_DATA,
                                   0, 
                                   0,
                                   0 );

  // End the request.
  if( bResults )
    bResults = WinHttpReceiveResponse( hRequest, NULL);

  // Use WinHttpQueryHeaders to obtain the header buffer.
  if( bResults )
    bResults = WinHttpQueryHeaders( hRequest, 
                WINHTTP_QUERY_STATUS_CODE | WINHTTP_QUERY_FLAG_NUMBER,
                                    NULL, 
                                    &dwStatusCode,
                                    &dwSize,
                                    WINHTTP_NO_HEADER_INDEX );

  // Based on the status code, determine whether 
  // the document was recently updated.
  if( bResults )
  {
    if( dwStatusCode == 304 ) 
      printf( "Document has not been updated.\n" );
    else if( dwStatusCode == 200 ) 
      printf( "Document has been updated.\n" );
    else 
      printf( "Status code = %u.\n",dwStatusCode );
  }

  // Report any errors.
  if( !bResults )
    printf( "Error %d has occurred.\n", GetLastError( ) );

  // Close open handles.
  if( hRequest ) WinHttpCloseHandle( hRequest );
  if( hConnect ) WinHttpCloseHandle( hConnect );
  if( hSession ) WinHttpCloseHandle( hSession );

Requisitos

   
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]
Plataforma de Destino Windows
Cabeçalho winhttp.h
Biblioteca Winhttp.lib
DLL Winhttp.dll
Redistribuível WinHTTP 5.0 e Internet Explorer 5.01 ou posterior no Windows XP e Windows 2000.

Confira também

Sobre os Serviços HTTP do Microsoft Windows (WinHTTP)

Versões do WinHTTP

WinHttpOpenRequest

WinHttpSendRequest