WinHttpAddRequestHeaders, fonction (winhttp.h)
La fonction WinHttpAddRequestHeaders ajoute un ou plusieurs en-têtes de requête HTTP au handle de requête HTTP.
Syntaxe
WINHTTPAPI BOOL WinHttpAddRequestHeaders(
[in] HINTERNET hRequest,
[in] LPCWSTR lpszHeaders,
[in] DWORD dwHeadersLength,
[in] DWORD dwModifiers
);
Paramètres
[in] hRequest
Handle HINTERNET retourné par un appel à la fonction WinHttpOpenRequest .
[in] lpszHeaders
Pointeur vers une variable de chaîne qui contient les en-têtes à ajouter à la demande. Chaque en-tête à l’exception du dernier doit être terminé par un retour chariot/saut de ligne (CR/LF).
[in] dwHeadersLength
Valeur entière longue non signée qui contient la longueur, en caractères, de pwszHeaders. Si ce paramètre a la valeur -1L, la fonction suppose que pwszHeaders est terminé à zéro (ASCIIZ) et que la longueur est calculée.
[in] dwModifiers
Valeur entière longue non signée qui contient les indicateurs utilisés pour modifier la sémantique de cette fonction. Il peut s’agir d’un ou plusieurs des indicateurs suivants.
Valeur retournée
Retourne TRUE en cas de réussite, ou FALSE dans le cas contraire. Pour obtenir des informations d’erreur étendues, appelez GetLastError. Parmi les codes d’erreur retournés figurent les suivants.
| Code d'erreur | Description |
|---|---|
|
Impossible d’effectuer l’opération demandée, car le handle fourni n’est pas dans l’état correct. |
|
Le type de handle fourni est incorrect pour cette opération. |
|
Une erreur interne s'est produite. |
|
La mémoire disponible était insuffisante pour terminer l’opération demandée. |
Remarques
Les en-têtes sont transférés entre les redirections. Il peut s’agir d’un problème de sécurité. Pour éviter que des en-têtes soient transférés lorsqu’une redirection se produit, utilisez le rappel WINHTTP_STATUS_CALLBACK pour corriger les en-têtes spécifiques lorsqu’une redirection se produit.
Même lorsque WinHTTP est utilisé en mode asynchrone (autrement dit, quand WINHTTP_FLAG_ASYNC a été défini dans WinHttpOpen), cette fonction fonctionne de manière synchrone. La valeur de retour indique la réussite ou l’échec. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
La fonction WinHttpAddRequestHeaders ajoute des en-têtes de format libre supplémentaires au handle de requête HTTP et est destinée aux clients sophistiqués qui nécessitent un contrôle détaillé sur la requête exacte envoyée au serveur HTTP.
Le nom et la valeur des en-têtes de requête ajoutés avec cette fonction sont validés. Les en-têtes doivent être bien formés. Pour plus d’informations sur les en-têtes HTTP valides, consultez RFC 2616. Si un en-tête non valide est utilisé, cette fonction échoue et GetLastError retourne ERROR_INVALID_PARAMETER. L’en-tête non valide n’est pas ajouté.
Si vous envoyez un en-tête de requête Date:, vous pouvez utiliser la fonction WinHttpTimeFromSystemTime pour créer la structure de l’en-tête.
Pour les winHttpAddRequestHeaders de base, l’application peut passer plusieurs en-têtes dans une seule mémoire tampon.
Une application peut également utiliser WinHttpSendRequest pour ajouter des en-têtes supplémentaires au handle de requête HTTP avant d’envoyer une requête.
Exemples
L’exemple de code suivant inclut un en-tête If-Modified-Since dans une demande. L’en-tête de réponse est interprété pour déterminer si le document cible a été mis à jour.
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 );
Configuration requise
| Client minimal pris en charge | Windows XP, Windows 2000 Professionnel avec SP3 [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003, Windows 2000 Server avec SP3 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | winhttp.h |
| Bibliothèque | Winhttp.lib |
| DLL | Winhttp.dll |
| Composant redistribuable | WinHTTP 5.0 et Internet Explorer 5.01 ou version ultérieure sur Windows XP et Windows 2000. |