Panoramica delle sessioni WinHTTP

Microsoft Windows HTTP Services (WinHTTP) espone un set di funzioni C/C++ che consentono all'applicazione di accedere alle risorse HTTP sul Web. In questo argomento viene fornita una panoramica del modo in cui queste funzioni vengono usate per interagire con un server HTTP.

• Uso dell'API WinHTTP per accedere al Web
• Inizializzazione di WinHTTP
• Apertura di una richiesta
• aggiunta di intestazioni di richiesta
• Invio di una Richiesta
• registrazione dei dati nel server
• ottenere informazioni su una richiesta
• Scaricare risorse dal Web

Uso dell'API WinHTTP per accedere al Web

Il diagramma seguente mostra l'ordine in cui le funzioni WinHTTP vengono in genere chiamate durante l'interazione con un server HTTP. Le caselle ombreggiate rappresentano le funzioni che generano un handle HINTERNET, mentre le caselle semplici rappresentano le funzioni che usano tali handle.

Inizializzazione di WinHTTP

Prima di interagire con un server, WinHTTP deve essere inizializzato chiamando WinHttpOpen. WinHttpOpen crea un contesto di sessione per mantenere i dettagli sulla sessione HTTP e restituisce un handle di sessione. Usando questo handle, la funzione WinHttpConnect è quindi in grado di specificare un server HTTP o HTTPS (Secure Hypertext Transfer Protocol) di destinazione.

Apertura di una richiesta

La funzione WinHttpOpenRequest apre una richiesta HTTP per una determinata risorsa e restituisce un handle che può essere usato dalle altre funzioni HTTP. winHttpOpenRequest non invia la richiesta al server quando viene chiamato. La funzione WinHttpSendRequest stabilisce effettivamente una connessione in rete e invia la richiesta.

L'esempio seguente mostra una chiamata di esempio a WinHttpOpenRequest che usa le opzioni predefinite.

HINTERNET hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL, NULL, NULL, NULL, 0);

Aggiunta di intestazioni di richiesta

La funzione WinHttpAddRequestHeaders consente a un'applicazione di aggiungere altre intestazioni di richiesta in formato libero all'handle di richiesta HTTP. È destinato all'uso da parte di applicazioni sofisticate che richiedono un controllo preciso sulle richieste inviate al server HTTP.

La funzione WinHttpAddRequestHeaders richiede un handle di richiesta HTTP creato da WinHttpOpenRequest, una stringa che contiene le intestazioni, la lunghezza delle intestazioni e qualsiasi modificatore.

I modificatori seguenti possono essere usati con WinHttpAddRequestHeaders.

Invio di una richiesta

La funzionewinHttpSendRequeststabilisce una connessione al server e invia la richiesta al sito specificato. Questa funzione richiede un handle di HINTERNET creato da WinHttpOpenRequest. WinHttpSendRequest può anche inviare intestazioni aggiuntive o informazioni facoltative. Le informazioni facoltative vengono in genere utilizzate per operazioni che scrivono informazioni nel server, ad esempio PUT e POST.

Dopo che la funzionewinHttpSendRequestinvia la richiesta, l'applicazione può usare le funzioni di WinHttpReadData e WinHttpQueryDataAvailable nell'handle DELLA RETE PER scaricare le risorse del server.

Registrazione dei dati nel server

Per pubblicare dati in un server, il verbo HTTP nella chiamata a WinHttpOpenRequest deve essere POST o PUT. Quando viene chiamato WinHttpSendRequest, il parametro dwTotalLength deve essere impostato sulle dimensioni dei dati in byte. Usare quindi WinHttpWriteData per pubblicare i dati nel server.

In alternativa, impostare il parametro lpOptional di WinHttpSendRequest sull'indirizzo di un buffer contenente i dati da pubblicare nel server. Quando si usa questa tecnica, è necessario impostare sia i parametri dwOptionalLength che dwTotalLength di WinHttpSendRequest in modo che corrispondano alle dimensioni dei dati inviati. La chiamata a winHttpSendRequest in questo modo elimina la necessità di chiamare WinHttpWriteData.

Recupero di informazioni su una richiesta

La funzionewinHttpQueryHeadersconsente a un'applicazione di recuperare informazioni su una richiesta HTTP. La funzione richiede un handle di HINTERNET creato da WinHttpOpenRequest, un valore del livello di informazione e una lunghezza del buffer. WinHttpQueryHeaders accetta anche un buffer che archivia le informazioni e un indice di intestazione in base zero che enumera più intestazioni con lo stesso nome.

Utilizzare uno qualsiasi dei valori a livello di informazioni presenti sulla pagina Query Info Flags, insieme a un modificatore, per controllare il formato in cui le informazioni vengono archiviate nel parametro lpvBuffer della funzione WinHttpQueryHeaders.

Download di risorse dal Web

Dopo aver aperto una richiesta con la funzionewinHttpOpenRequest, inviandolo al server con WinHttpSendRequeste preparando l'handle di richiesta per ricevere una risposta con WinHttpReceiveResponse, l'applicazione può usare ilWinHttpReadDatae WinHttpQueryDataAvailable per scaricare la risorsa dal server HTTP.

Il codice di esempio seguente illustra come scaricare una risorsa con semantica di transazione sicura. Il codice di esempio inizializza l'API (Application Programming Interface) WinHTTP, seleziona un server HTTPS di destinazione e quindi apre e invia una richiesta per questa risorsa protetta. WinHttpQueryDataAvailable viene usato con l'handle di richiesta per determinare la quantità di dati disponibili per il download e quindi WinHttpReadData per leggere tali dati. Questo processo viene ripetuto fino a quando l'intero documento non viene recuperato e visualizzato.

  DWORD dwSize = 0;
  DWORD dwDownloaded = 0;
  LPSTR pszOutBuffer;
  BOOL  bResults = FALSE;
  HINTERNET  hSession = NULL, 
             hConnect = NULL,
             hRequest = NULL;

  // Use WinHttpOpen to obtain a session handle.
  hSession = WinHttpOpen( L"WinHTTP Example/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_HTTPS_PORT, 0 );

  // Create an HTTP request handle.
  if( hConnect )
    hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,
                                   NULL, WINHTTP_NO_REFERER, 
                                   WINHTTP_DEFAULT_ACCEPT_TYPES, 
                                   WINHTTP_FLAG_SECURE );

  // Send a request.
  if( hRequest )
    bResults = WinHttpSendRequest( hRequest,
                                   WINHTTP_NO_ADDITIONAL_HEADERS, 0,
                                   WINHTTP_NO_REQUEST_DATA, 0, 
                                   0, 0 );


  // End the request.
  if( bResults )
    bResults = WinHttpReceiveResponse( hRequest, NULL );

  // Keep checking for data until there is nothing left.
  if( bResults )
  {
    do 
    {
      // Check for available data.
      dwSize = 0;
      if( !WinHttpQueryDataAvailable( hRequest, &dwSize ) )
        printf( "Error %u in WinHttpQueryDataAvailable.\n",
                GetLastError( ) );

      // Allocate space for the buffer.
      pszOutBuffer = new char[dwSize+1];
      if( !pszOutBuffer )
      {
        printf( "Out of memory\n" );
        dwSize=0;
      }
      else
      {
        // Read the data.
        ZeroMemory( pszOutBuffer, dwSize+1 );

        if( !WinHttpReadData( hRequest, (LPVOID)pszOutBuffer, 
                              dwSize, &dwDownloaded ) )
          printf( "Error %u in WinHttpReadData.\n", GetLastError( ) );
        else
          printf( "%s", pszOutBuffer );

        // Free the memory allocated to the buffer.
        delete [] pszOutBuffer;
      }
    } while( dwSize > 0 );
  }


  // Report any errors.
  if( !bResults )
    printf( "Error %d has occurred.\n", GetLastError( ) );

  // Close any open handles.
  if( hRequest ) WinHttpCloseHandle( hRequest );
  if( hConnect ) WinHttpCloseHandle( hConnect );
  if( hSession ) WinHttpCloseHandle( hSession );