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.

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

Vedi anche

Informazioni su Microsoft Windows HTTP Services (WinHTTP)

Versioni WinHTTP

WinHttpOpenRequest

WinHttpSendRequest