A WinHTTP-munkamenetek áttekintése

A Microsoft Windows HTTP Services (WinHTTP) C/C++ függvények készletét teszi elérhetővé, amelyek lehetővé teszik az alkalmazás számára a HTTP-erőforrások webes elérését. Ez a témakör áttekintést nyújt arról, hogyan használják ezeket a függvényeket a HTTP-kiszolgálókkal való interakcióhoz.

• A WinHTTP API használata a webes eléréséhez
• WinHTTP inicializálása
• Kérelem megnyitása
• Kérelemfejlécek hozzáadása
• Kérés küldése
• Adatok küldése a kiszolgálóra
• Kérelem adatainak lekérése
• Erőforrások letöltése a webről

A WinHTTP API használata a weben való hozzáféréshez

Az alábbi ábra azt mutatja be, hogy a WinHTTP-függvények általában milyen sorrendben vannak meghívva EGY HTTP-kiszolgáló használatakor. Az árnyékolt mezők olyan függvényeket jelölnek, amelyek HINTERNET fogópontot hoznak létre, míg az egyszerű mezők azokat a függvényeket jelölik, amelyek ezeket a fogópontokat használják.

-t létrehozó függvények

A WinHTTP inicializálása

A kiszolgálóval való interakció előtt a WinHTTP-t inicializálni kell WinHttpOpenmeghívásával. WinHttpOpen létrehoz egy munkamenet-környezetet a HTTP-munkamenet részleteinek karbantartásához, és visszaad egy munkamenet-leírót. Ezzel a leíróval a WinHttpConnect függvény képes megadni egy cél HTTP- vagy SECURE Hypertext Transfer Protocol-kiszolgálót (HTTPS).

Kérelem megnyitása

A WinHttpOpenRequest függvény http-kérelmet nyit meg egy adott erőforráshoz, és visszaad egy HINTERNET leírót, amelyet a többi HTTP-függvény használhat. WinHttpOpenRequest híváskor nem küldi el a kérést a kiszolgálónak. A WinHttpSendRequest függvény ténylegesen kapcsolatot létesít a hálózaton keresztül, és elküldi a kérést.

Az alábbi példa az alapértelmezett beállításokat használó WinHttpOpenRequest meghívását mutatja be.

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

Kérelemfejlécek hozzáadása

A WinHttpAddRequestHeaders függvény lehetővé teszi, hogy az alkalmazás további szabad formátumú kérelemfejléceket fűzjön a HTTP-kérelem leírójához. Kifinomult alkalmazások számára készült, amelyek pontos ellenőrzést igényelnek a HTTP-kiszolgálónak küldött kérések felett.

A WinHttpAddRequestHeaders függvényhez a WinHttpOpenRequestáltal létrehozott HTTP-kéréskezelő szükséges, amely a fejléceket, a fejlécek hosszát és a módosítókat tartalmazza.

Az alábbi módosítók használhatók WinHttpAddRequestHeaders.

Kérés küldése

A WinHttpSendRequest függvény kapcsolatot létesít a kiszolgálóval, és elküldi a kérést a megadott helyre. Ehhez a függvényhez WinHttpOpenRequestáltal létrehozott HINTERNET leíró szükséges. WinHttpSendRequest további fejléceket vagy opcionális információkat is küldhet. Az opcionális információkat általában olyan műveletekhez használják, amelyek adatokat írnak a kiszolgálóra, például PUT és POST.

Miután a WinHttpSendRequest függvény elküldte a kérést, az alkalmazás használhatja a WinHttpReadData és WinHttpQueryDataAvailable függvényeket a HINTERNET leírón a kiszolgáló erőforrásainak letöltéséhez.

Adatok közzététele a kiszolgálóra

Ha adatokat szeretne közzétenni egy kiszolgálóra, a WinHttpOpenRequest hívásában szereplő HTTP- parancsnak POST vagy PUT értékűnek kell lennie. Ha WinHttpSendRequest van meghívva, a dwTotalLength paramétert bájtban kell beállítani az adatok méretére. Ezután WinHttpWriteData használatával tegye közzé az adatokat a kiszolgálón.

Másik lehetőségként állítsa a WinHttpSendRequestlpOptional paraméterét egy olyan puffer címére, amely adatokat tartalmaz a kiszolgálóra való közzétételhez. A technika használatakor meg kell adnia mind a dwOptionalLength, mind a dwTotalLength paramétert a WinHttpSendRequest esetében, hogy megegyezzenek a közzéteendő adatok méretével. Az WinHttpSendRequest ilyen módon történő meghívása szükségtelenné teszi WinHttpWriteDatameghívását.

Információ megszerzése egy kérésről

A WinHttpQueryHeaders függvény lehetővé teszi, hogy az alkalmazás adatokat kérjen le egy HTTP-kérésről. A függvényhez szükség van egy HINTERNET leíróra, amelyet WinHttpOpenRequesthozott létre, egy információszint-értéket és egy pufferhosszt. WinHttpQueryHeaders is elfogad egy puffert, amely tárolja az információkat és egy nulla alapú fejlécindexet, amely több azonos nevű fejlécet sorol fel.

A Lekérdezési információs jelzők lapon található információszint-értékek bármelyikét használhatja egy módosítóval annak a formátumnak a szabályozásához, amelyben az adatok a WinHttpQueryHeaderslpvBuffer paraméterében találhatók.

Erőforrások letöltése a webről

Miután megnyitott egy kérelmet a WinHttpOpenRequest függvénnyel, WinHttpSendRequest, és előkészíti a kéréskezelőt, hogy választ kapjon WinHttpReceiveResponse, az alkalmazás használhatja a WinHttpReadData és WinHttpQueryDataAvailable függvényeket az erőforrás HTTP-kiszolgálóról való letöltéséhez.

Az alábbi mintakód bemutatja, hogyan tölthet le egy erőforrást biztonságos tranzakció szemantikával. A mintakód inicializálja a WinHTTP alkalmazásprogramozási felületét (API), kiválaszt egy cél HTTPS-kiszolgálót, majd megnyitja és elküldi a biztonságos erőforrásra vonatkozó kérést. WinHttpQueryDataAvailable a kérelemleíróval határozza meg, hogy mennyi adat érhető el a letöltéshez, majd WinHttpReadData használja az adatok olvasására. Ez a folyamat addig ismétlődik, amíg a teljes dokumentum le nem olvasható és meg nem jelenik.

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