WinHttpAddRequestHeaders, fonction (winhttp.h)

Article
08/27/2023

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	Signification
WINHTTP_ADDREQ_FLAG_ADD	Ajoute l’en-tête s’il n’existe pas. Utilisé avec WINHTTP_ADDREQ_FLAG_REPLACE.
WINHTTP_ADDREQ_FLAG_ADD_IF_NEW	Ajoute l’en-tête uniquement s’il n’existe pas déjà ; sinon, une erreur est retournée.
WINHTTP_ADDREQ_FLAG_COALESCE	Fusionne les en-têtes du même nom.
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_COMMA	Fusionne les en-têtes du même nom à l’aide d’une virgule. Par exemple, l’ajout de « Accept: text/* » suivi de « Accept: audio/* » avec cet indicateur entraîne un en-tête unique « Accept: text/, audio/ ». Cela entraîne la fusion du premier en-tête. L’application appelante doit garantir un schéma cohérent en ce qui concerne les en-têtes fusionnés et distincts.
WINHTTP_ADDREQ_FLAG_COALESCE_WITH_SEMICOLON	Fusionne les en-têtes du même nom à l’aide d’un point-virgule.
WINHTTP_ADDREQ_FLAG_REPLACE	Remplace ou supprime un en-tête. Si la valeur d’en-tête est vide et que l’en-tête est trouvé, il est supprimé. Si la valeur n’est pas vide, elle est remplacée.

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
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	Impossible d’effectuer l’opération demandée, car le handle fourni n’est pas dans l’état correct.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Le type de handle fourni est incorrect pour cette opération.
ERROR_WINHTTP_INTERNAL_ERROR	Une erreur interne s'est produite.
ERROR_NOT_ENOUGH_MEMORY	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.

Note Pour plus d’informations, consultez Conditions requises au moment de l’exécution.

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.