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
);

Parameters

[in] hRequest

Handle DELL'OGGETTO XMLNET 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 ritorno a capo/avanzamento riga (CR/LF).

[in] dwHeadersLength

Valore intero lungo senza segno che contiene la lunghezza, in caratteri, di lpszHeaders. Se dwHeadersLength è -1L, la funzione presuppone che lpszHeaders sia con terminazione zero (ASCIIZ) e la lunghezza venga calcolata.

Se dwHeadersLength non è -1L, la funzione copia esattamente i caratteri dwHeadersLength . WinHTTP non verificherà se lpszHeaders contiene una stringa con terminazione zero.

[in] dwModifiers

Valore intero long senza segno che contiene i flag utilizzati 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 estese sull'errore, chiamare GetLastError. Tra i codici di errore restituiti sono riportati di seguito.

Remarks

Le intestazioni vengono trasferite tra i reindirizzamenti. Può trattarsi di un problema di sicurezza. Per evitare il trasferimento di intestazioni 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 funziona in modo sincrono. Il valore restituito indica l'esito positivo o negativo. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

La funzione WinHttpAddRequestHeaders aggiunge intestazioni in 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 formate. 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 di richiesta Date: è possibile usare la funzione WinHttpTimeFromSystemTime per creare una 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.

Examples

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

Vedere anche

Informazioni su Microsoft Windows HTTP Services (WinHTTP)

Versioni di WinHTTP

WinHttpOpenRequest

WinHttpSendRequest