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.

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

Voir aussi

À propos des services HTTP Microsoft Windows (WinHTTP)

WinHTTP Versions

WinHttpOpenRequest

WinHttpSendRequest