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

Parameters

[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 lpszHeaders. Se dwHeadersLength for -1L, a função assumirá que lpszHeaders é ASCIIZ (terminação zero) e o comprimento será computado.

Se dwHeadersLength não for -1L, a função copiará exatamente caracteres dwHeadersLength . O WinHTTP não verificará se o lpszHeaders contém uma cadeia de caracteres com término zero.

[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 retornado

Retorna TRUE se bem-sucedido 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.

Remarks

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 retorno de chamada WINHTTP_STATUS_CALLBACK 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 em 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. 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 é adicionado.

Se você estiver enviando um cabeçalho de solicitação Data: você pode 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.

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

Requirements

Consulte também

Sobre o Microsoft Windows HTTP Services (WinHTTP)

Versões do WinHTTP

WinHttpOpenRequest

WinHttpSendRequest