Funzione WinHttpAddRequestHeaders (winhttp.h)
La funzione WinHttpAddRequestHeaders aggiunge una o più intestazioni di richiesta HTTP all'handle di richiesta HTTP.
Sintassi
WINHTTPAPI BOOL WinHttpAddRequestHeaders(
[in] HINTERNET hRequest,
[in] LPCWSTR lpszHeaders,
[in] DWORD dwHeadersLength,
[in] DWORD dwModifiers
);
Parametri
[in] hRequest
Handle HINTERNET restituito da una chiamata alla funzione WinHttpOpenRequest .
[in] lpszHeaders
Puntatore a una variabile stringa contenente le intestazioni da aggiungere alla richiesta. Ogni intestazione tranne l'ultima deve essere terminata da un feed restituito/riga a capo (CR/LF).
[in] dwHeadersLength
Valore intero lungo senza segno che contiene la lunghezza, in caratteri, di pwszHeaders. Se questo parametro è -1L, la funzione presuppone che pwszHeaders sia con terminazione zero (ASCIIZ) e la lunghezza viene calcolata.
[in] dwModifiers
Valore intero lungo senza segno che contiene i flag usati per modificare la semantica di questa funzione. Può essere uno o più dei flag seguenti.
Valore restituito
Restituisce TRUE se ha esito positivo o FALSE in caso contrario. Per informazioni sull'errore estese, chiamare GetLastError. Tra i codici di errore restituiti sono i seguenti.
| Codice di errore | Descrizione |
|---|---|
|
Impossibile eseguire l'operazione richiesta perché l'handle fornito non è nello stato corretto. |
|
Il tipo di handle fornito non è corretto per questa operazione. |
|
Si è verificato un errore interno. |
|
Memoria insufficiente per completare l'operazione richiesta. |
Commenti
Le intestazioni vengono trasferite tra reindirizzamenti. Questo può essere un problema di sicurezza. Per evitare di avere intestazioni trasferite quando si verifica un reindirizzamento, usare il callback WINHTTP_STATUS_CALLBACK per correggere le intestazioni specifiche quando si verifica un reindirizzamento.
Anche quando WinHTTP viene usato in modalità asincrona, ovvero quando WINHTTP_FLAG_ASYNC è stato impostato in WinHttpOpen, questa funzione opera in modo sincrono. Il valore restituito indica l'esito positivo o negativo. Per informazioni dettagliate sull'errore, chiamare GetLastError.
La funzione WinHttpAddRequestHeaders aggiunge intestazioni di formato libero aggiuntive all'handle di richiesta HTTP ed è destinata all'uso da parte di client sofisticati che richiedono un controllo dettagliato sulla richiesta esatta inviata al server HTTP.
Il nome e il valore delle intestazioni di richiesta aggiunte con questa funzione vengono convalidati. Le intestazioni devono essere ben formatte. Per altre informazioni sulle intestazioni HTTP valide, vedere RFC 2616. Se viene usata un'intestazione non valida, questa funzione ha esito negativo e GetLastError restituisce ERROR_INVALID_PARAMETER. L'intestazione non valida non viene aggiunta.
Se si invia un'intestazione Date: richiesta, è possibile usare la funzione WinHttpTimeFromSystemTime per creare la struttura per l'intestazione.
Per WinHttpAddRequestHeaders di base, l'applicazione può passare più intestazioni in un singolo buffer.
Un'applicazione può anche usare WinHttpSendRequest per aggiungere intestazioni aggiuntive all'handle di richiesta HTTP prima di inviare una richiesta.
Esempio
L'esempio di codice seguente include un'intestazione If-Modified-Since in una richiesta. L'intestazione della risposta viene interpretata per determinare se il documento di destinazione è stato aggiornato.
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 );
Requisiti
| Client minimo supportato | Windows XP, Windows 2000 Professional con SP3 [solo app desktop] |
| Server minimo supportato | Windows Server 2003, Windows 2000 Server con SP3 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winhttp.h |
| Libreria | Winhttp.lib |
| DLL | Winhttp.dll |
| Componente ridistribuibile | WinHTTP 5.0 e Internet Explorer 5.01 o versione successiva in Windows XP e Windows 2000. |