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