Função WinHttpQueryHeaders (winhttp.h)
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 |
|---|---|
|
Não foi possível localizar o cabeçalho solicitado. |
|
A operação solicitada não pode ser executada porque o identificador fornecido não está no estado correto. |
|
O tipo de identificador fornecido está incorreto para esta operação. |
|
Ocorreu um erro interno. |
|
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 |
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. |
Confira também
Sobre os Serviços HTTP do Microsoft Windows (WinHTTP)
Serviços HTTP do Microsoft Windows (WinHTTP)