Função WinHttpQueryHeaders (winhttp.h)

Artigo
08/27/2023

A função WinHttpQueryHeaders recupera informações de cabeçalho associadas a uma solicitação HTTP.

Consulte também WinHttpQueryHeadersEx, que oferece uma maneira de recuperar cadeias de caracteres de valor e nome de cabeçalho analisado.

Sintaxe

WINHTTPAPI BOOL WinHttpQueryHeaders(
  [in]           HINTERNET hRequest,
  [in]           DWORD     dwInfoLevel,
  [in, optional] LPCWSTR   pwszName,
  [out]          LPVOID    lpBuffer,
  [in, out]      LPDWORD   lpdwBufferLength,
  [in, out]      LPDWORD   lpdwIndex
);

Parâmetros

[in] hRequest

Identificador de solicitação HINTERNET retornado por WinHttpOpenRequest. WinHttpReceiveResponse deve ter sido chamado para esse identificador e ter sido concluído antes de WinHttpQueryHeaders ser chamado.

[in] dwInfoLevel

Valor do tipo DWORD que especifica uma combinação de sinalizadores de atributo e modificador listados na página Sinalizadores de Informações de Consulta . Esses sinalizadores de atributo e modificador indicam que as informações estão sendo solicitadas e como elas devem ser formatadas.

[in, optional] pwszName

Ponteiro para uma cadeia de caracteres que contém o nome do cabeçalho. Se o sinalizador em dwInfoLevel não for WINHTTP_QUERY_CUSTOM, defina esse parâmetro como WINHTTP_HEADER_NAME_BY_INDEX.

[out] lpBuffer

Ponteiro para o buffer que recebe as informações. Definir esse parâmetro como WINHTTP_NO_OUTPUT_BUFFER faz com que essa função retorne FALSE. Chamar GetLastError retorna ERROR_INSUFFICIENT_BUFFER e lpdwBufferLength contém o número de bytes necessários para manter as informações solicitadas.

[in, out] lpdwBufferLength

Ponteiro para um valor do tipo DWORD que especifica o comprimento do buffer de dados, em bytes. Quando a função retorna, esse parâmetro contém o ponteiro para um valor que especifica o comprimento das informações gravadas no buffer. Quando a função retorna cadeias de caracteres, as regras a seguir se aplicam.

Se a função for bem-sucedida, lpdwBufferLength especificará o comprimento da cadeia de caracteres, em bytes, menos 2 para o nulo de terminação.
Se a função falhar e ERROR_INSUFFICIENT_BUFFER for retornado, lpdwBufferLength especificará o número de bytes que o aplicativo deve alocar para receber a cadeia de caracteres.

[in, out] lpdwIndex

Ponteiro para um índice de cabeçalho baseado em zero usado para enumerar vários cabeçalhos com o mesmo nome. Ao chamar a função , esse parâmetro é o índice do cabeçalho especificado a ser retornado. Quando a função retorna, esse parâmetro é o índice do próximo cabeçalho. Se o próximo índice não puder ser encontrado, ERROR_WINHTTP_HEADER_NOT_FOUND será retornado. Defina esse parâmetro como WINHTTP_NO_HEADER_INDEX para especificar que apenas a primeira ocorrência de um cabeçalho deve ser retornada.

Retornar valor

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_HEADER_NOT_FOUND	Não foi possível localizar o cabeçalho solicitado.
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. (Código de erro do Windows)

Comentários

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.

Por padrão , WinHttpQueryHeaders retorna uma cadeia de caracteres. No entanto, você pode solicitar dados na forma de uma estrutura SYSTEMTIME ou DWORD incluindo o sinalizador modificador apropriado em dwInfoLevel. A tabela a seguir mostra os possíveis tipos de dados que WinHttpQueryHeaders podem retornar junto com o sinalizador modificador que você usa para selecionar esse tipo de dados.

Tipo de dados	Sinalizador do modificador
LPCWSTR	Padrão. Nenhum sinalizador modificador é necessário.
SYSTEMTIME	WINHTTP_QUERY_FLAG_SYSTEMTIME
DWORD	WINHTTP_QUERY_FLAG_NUMBER

Nota 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 obter um identificador HINTERNET , abrir uma sessão HTTP, criar e enviar um cabeçalho de solicitação e examinar o cabeçalho de resposta retornado.

    DWORD dwSize = 0;
    LPVOID lpOutBuffer = NULL;
    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);

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

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

    // First, use WinHttpQueryHeaders to obtain the size of the buffer.
    if (bResults)
    {
        WinHttpQueryHeaders( hRequest, WINHTTP_QUERY_RAW_HEADERS_CRLF,
                             WINHTTP_HEADER_NAME_BY_INDEX, NULL,
                             &dwSize, WINHTTP_NO_HEADER_INDEX);

        // Allocate memory for the buffer.
        if( GetLastError( ) == ERROR_INSUFFICIENT_BUFFER )
        {
            lpOutBuffer = new WCHAR[dwSize/sizeof(WCHAR)];

            // Now, use WinHttpQueryHeaders to retrieve the header.
            bResults = WinHttpQueryHeaders( hRequest,
                                       WINHTTP_QUERY_RAW_HEADERS_CRLF,
                                       WINHTTP_HEADER_NAME_BY_INDEX,
                                       lpOutBuffer, &dwSize,
                                       WINHTTP_NO_HEADER_INDEX);
        }
    }

    // Print the header contents.
    if (bResults)
        printf("Header contents: \n%S",lpOutBuffer);

    // Free the allocated memory.
    delete [] lpOutBuffer;

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

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

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