Overzicht van WinHTTP-sessies

De Microsoft Windows HTTP Services (WinHTTP) maakt een set C/C++-functies beschikbaar waarmee uw toepassing toegang kan krijgen tot HTTP-resources op het web. Dit onderwerp bevat een overzicht van hoe deze functies worden gebruikt voor interactie met een HTTP-server.

• de WinHTTP-API gebruiken voor toegang tot het web
• WinHTTP- initialiseren
• een aanvraag openen
• verzoekheaders toevoegen
• een aanvraag verzenden
• Gegevens posten op de server
• Informatie over een aanvraag ophalen
• Bronnen downloaden van het web

De WinHTTP-API gebruiken voor toegang tot het web

In het volgende diagram ziet u de volgorde waarin WinHTTP-functies doorgaans worden aangeroepen bij interactie met een HTTP-server. De gearceerde vakken vertegenwoordigen functies die een HINTERNET- handle genereren, terwijl de ongestileerde vakken functies vertegenwoordigen die gebruikmaken van deze handles.

WinHTTP initialiseren

Voordat u met een server communiceert, moet WinHTTP worden geïnitialiseerd door WinHttpOpen-aan te roepen. WinHttpOpen maakt een sessiecontext om details over de HTTP-sessie te behouden en retourneert een sessie-handle. Met deze ingang kan de WinHttpConnect--functie vervolgens een HTTP- of Secure Hypertext Transfer Protocol-server (HTTPS) opgeven.

Een aanvraag openen

De functie WinHttpOpenRequest opent een HTTP-aanvraag voor een bepaalde resource en retourneert een ACHTERNET ingang die kan worden gebruikt door de andere HTTP-functies. WinHttpOpenRequest verzendt de aanvraag niet naar de server wanneer deze wordt aangeroepen. De WinHttpSendRequest functie brengt daadwerkelijk een verbinding tot stand via het netwerk en verzendt de aanvraag.

In het volgende voorbeeld ziet u een voorbeeldaanroep voor WinHttpOpenRequest die gebruikmaakt van de standaardopties.

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

Aanvraagheaders toevoegen

Met de functie WinHttpAddRequestHeaders kan een toepassing extra verzoekheaders met vrije opmaak toevoegen aan het HTTP-verwerkingshandvat. Het is bedoeld voor gebruik door geavanceerde toepassingen waarvoor nauwkeurige controle nodig is over de aanvragen die naar de HTTP-server worden verzonden.

Voor de functie WinHttpAddRequestHeaders is een HTTP-aanvraaggreep vereist die is gemaakt door WinHttpOpenRequest-, een tekenreeks die de headers, de lengte van de headers en eventuele modifiers bevat.

De volgende modifiers kunnen worden gebruikt met WinHttpAddRequestHeaders.

Een aanvraag verzenden

De WinHttpSendRequest-functie brengt een verbinding tot stand met de server en verzendt de aanvraag naar de opgegeven site. Voor deze functie is een HINTERNET- handle vereist die is gemaakt door WinHttpOpenRequest. WinHttpSendRequest kan ook extra headers of optionele informatie verzenden. De optionele informatie wordt over het algemeen gebruikt voor bewerkingen die gegevens naar de server schrijven, zoals PUT en POST.

Nadat de WinHttpSendRequest-functie de aanvraag heeft verzonden, kan de toepassing de WinHttpReadData- en WinHttpQueryDataAvailable functies op de ACHTERNET- ingang gebruiken om de resources van de server te downloaden.

Gegevens plaatsen op de server

Als u gegevens naar een server wilt posten, moet het HTTP-werkwoord in de aanroep naar WinHttpOpenRequest- POST of PUT zijn. Wanneer WinHttpSendRequest wordt aangeroepen, moet de parameter dwTotalLength worden ingesteld op de grootte van de gegevens in bytes. Gebruik vervolgens WinHttpWriteData om de gegevens op de server te plaatsen.

U kunt ook de parameter lpOptional van WinHttpSendRequest instellen op het adres van een buffer die gegevens bevat die op de server moeten worden geplaatst. Wanneer u deze techniek gebruikt, moet u zowel de parameters dwOptionalLength als dwTotalLength van WinHttpSendRequest instellen op de grootte van de gegevens die worden gepost. Als u WinHttpSendRequest aanroept, hoeft u WinHttpWriteData-niet meer aan te roepen.

Informatie over een aanvraag ophalen

Met de functie WinHttpQueryHeaders kan een toepassing informatie over een HTTP-aanvraag ophalen. De functie vereist een HINTERNET- handle gemaakt door WinHttpOpenRequest, een informatieniveauwaarde en een bufferlengte. WinHttpQueryHeaders accepteert ook een buffer waarin de informatie en een op nul gebaseerde headerindex worden opgeslagen waarin meerdere headers met dezelfde naam worden opgesomd.

Gebruik een van de waarden op informatieniveau die zijn gevonden op de pagina Query infovlaggen met een wijziging om de indeling te bepalen waarin de informatie is opgeslagen in de parameter lpvBuffer van WinHttpQueryHeaders.

Resources downloaden van het web

Na het openen van een aanvraag met de functie WinHttpOpenRequest, het verzenden naar de server met WinHttpSendRequesten het voorbereiden van de aanvraaghandler voor het ontvangen van een antwoord met WinHttpReceiveResponse-, kan de toepassing de WinHttpReadData- en WinHttpQueryDataAvailable-functies gebruiken om de resource van de HTTP-server te downloaden.

In de volgende voorbeeldcode ziet u hoe u een resource downloadt met semantiek voor beveiligde transacties. De voorbeeldcode initialiseert de WinHTTP-api (Application Programming Interface), selecteert een HTTPS-doelserver en wordt vervolgens geopend en verzendt een aanvraag voor deze beveiligde resource. WinHttpQueryDataAvailable wordt gebruikt met de aanvraaggreep om te bepalen hoeveel gegevens er beschikbaar zijn om te downloaden. Vervolgens wordt WinHttpReadData- gebruikt om die gegevens te lezen. Dit proces wordt herhaald totdat het hele document is opgehaald en weergegeven.

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