WinHttpQueryDataAvailable-Funktion (winhttp.h)

Artikel
08/27/2023

Die WinHttpQueryDataAvailable-Funktion gibt die Datenmenge in Bytes zurück, die mit WinHttpReadData gelesen werden kann.

Syntax

WINHTTPAPI BOOL WinHttpQueryDataAvailable(
  [in]  HINTERNET hRequest,
  [out] LPDWORD   lpdwNumberOfBytesAvailable
);

Parameter

[in] hRequest

Ein gültiges HINTERNET-Handle , das von WinHttpOpenRequest zurückgegeben wird. WinHttpReceiveResponse muss für dieses Handle aufgerufen und abgeschlossen sein, bevor WinHttpQueryDataAvailable aufgerufen wird.

[out] lpdwNumberOfBytesAvailable

Ein Zeiger auf eine variable Long-Integer ohne Vorzeichen, die die Anzahl der verfügbaren Bytes empfängt. Wenn WinHTTP im asynchronen Modus verwendet wird, legen Sie diesen Parameter immer auf NULL fest, und rufen Sie Daten in der Rückruffunktion ab. Dies kann zu einem Speicherfehler führen.

Rückgabewert

Gibt TRUE zurück, wenn die Funktion erfolgreich ist, oder andernfalls FALSE . Rufen Sie GetLastError auf, um erweiterte Fehlerdaten zu erhalten. Zu den zurückgegebenen Fehlercodes gehören die folgenden.

Fehlercode	BESCHREIBUNG
ERROR_WINHTTP_CONNECTION_ERROR	Die Verbindung mit dem Server wurde zurückgesetzt oder beendet, oder es wurde ein inkompatibles SSL-Protokoll gefunden. Beispielsweise unterstützt WinHTTP Version 5.1 SSL2 nur, wenn der Client dies ausdrücklich aktiviert.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	Der angeforderte Vorgang kann nicht abgeschlossen werden, da sich das angegebene Handle nicht im richtigen Zustand befindet.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Der Typ des angegebenen Handles ist für diesen Vorgang falsch.
ERROR_WINHTTP_INTERNAL_ERROR	Ein interner Fehler ist aufgetreten.
ERROR_WINHTTP_OPERATION_CANCELLED	Der Vorgang wurde abgebrochen, in der Regel, weil das Handle, für das die Anforderung ausgeführt wurde, vor Abschluss des Vorgangs geschlossen wurde.
ERROR_WINHTTP_TIMEOUT	Timeout für die Anforderung.
ERROR_NOT_ENOUGH_MEMORY	Es war nicht genügend Arbeitsspeicher verfügbar, um den angeforderten Vorgang abzuschließen. (Windows-Fehlercode)

Hinweise

Auch wenn WinHTTP im asynchronen Modus verwendet wird (d. h. wenn WINHTTP_FLAG_ASYNC in WinHttpOpen festgelegt wurde), kann diese Funktion entweder synchron oder asynchron ausgeführt werden. Wenn FALSE zurückgegeben wird, ist ein Fehler aufgetreten, und Sie können GetLastError aufrufen, um erweiterte Fehlerinformationen zu erhalten. Wenn TRUE zurückgegeben wird, verwenden Sie die WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE Abschluss, um zu bestimmen, ob diese Funktion erfolgreich war, und den Wert der Parameter. Die WINHTTP_CALLBACK_STATUS_REQUEST_ERROR Vervollständigung gibt an, dass der Vorgang asynchron abgeschlossen wurde, aber fehlgeschlagen ist.

Warnung Wenn WinHTTP im asynchronen Modus verwendet wird, legen Sie den Parameter lpdwNumberOfBytesAvailable immer auf NULL fest, und rufen Sie die in der Rückruffunktion verfügbaren Bytes ab. Andernfalls kann ein Speicherfehler auftreten.

Diese Funktion gibt die Anzahl der Bytes der Daten zurück, die sofort durch einen nachfolgenden Aufruf von WinHttpReadData gelesen werden können. Wenn keine Daten verfügbar sind und das Ende der Datei nicht erreicht wurde, geschieht eine von zwei Dingen. Wenn die Sitzung synchron ist, wartet die Anforderung, bis Daten verfügbar sind. Wenn die Sitzung asynchron ist, gibt die Funktion TRUE zurück, und wenn Daten verfügbar werden, ruft die Rückruffunktion mit WINHTTP_STATUS_CALLBACK_DATA_AVAILABLE auf und gibt die Anzahl der Bytes an, die durch Aufrufen von WinHttpReadData sofort zum Lesen verfügbar sind.

Die Datenmenge, die verbleibt, wird erst dann neu berechnet, wenn alle verfügbaren Daten gelesen werden, die durch den Aufruf von WinHttpQueryDataAvailable angegeben werden.

Verwenden Sie den Rückgabewert von WinHttpReadData , um zu bestimmen, wann eine Antwort vollständig gelesen wurde.

Wichtig Verwenden Sie nicht den Rückgabewert von WinHttpQueryDataAvailable , um zu bestimmen, ob das Ende einer Antwort erreicht wurde, da nicht alle Server Antworten ordnungsgemäß beenden und eine falsch beendete Antwort winHttpQueryDataAvailable dazu führt, dass mehr Daten erwartet werden.

Für HINTERNET-Handles , die von der WinHttpOpenRequest-Funktion erstellt und von WinHttpSendRequest gesendet werden, muss ein Aufruf von WinHttpReceiveResponse für das Handle erfolgen, bevor WinHttpQueryDataAvailable verwendet werden kann.

Wenn eine status Rückruffunktion mit WinHttpSetStatusCallback installiert wurde, zeigen die Benachrichtigungen der folgenden Benachrichtigungen, die im dwNotificationFlags-Parameter von WinHttpSetStatusCallback festgelegt wurden, den Fortschritt bei der Suche nach verfügbaren Daten an:

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

Hinweis Weitere Informationen zu Windows XP und Windows 2000 finden Sie unter Laufzeitanforderungen.

Beispiele

Das folgende Beispiel zeigt, wie Sie mithilfe der Semantik sicherer Transaktionen eine Ressource von einem HTTPS-Server herunterladen. Der Beispielcode initialisiert die WinHTTP-API, wählt einen HTTPS-Zielserver aus, öffnet und sendet eine Anforderung für diese sichere Ressource.
WinHttpQueryDataAvailable wird mit dem Anforderungshandle verwendet, um zu bestimmen, wie viele Daten zum Herunterladen verfügbar sind. Anschließend wird WinHttpReadData verwendet, um diese Daten zu lesen. Dieser Vorgang wird wiederholt, bis das gesamte Dokument abgerufen und angezeigt wurde.

Wichtig

Wenn Sie einige Daten so schnell wie möglich benötigen (d. h., Sie verarbeiten und analysieren Daten beim Empfang), sollten Sie WinHttpQueryDataAvailable und WinHttpReadData aufrufen. Wenn Sie versuchen, die gesamte Antwort so schnell wie möglich herunterzuladen, rufen Sie WinHttpReadData direkt auf, da WinHttpReadData versucht, den Puffer vor abschluss zu füllen.

Außerdem wird im folgenden Codebeispiel jede Schleifeniteration zugeordnet. Bei Produktionscode, bei dem die Leistung wichtig ist, können Sie stattdessen mit einem Puffer mit angemessener Größe (vielleicht 1 Megabyte) beginnen und die Größe bei Bedarf ändern. In der Praxis gibt WinHttpQueryDataAvailable nicht mehr als 8 KB zurück.


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

    // Continue to verify data until there is nothing left.
    if (bResults)
        do 
        {

            // Verify 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\n", 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 open handles.
    if (hRequest) WinHttpCloseHandle(hRequest);
    if (hConnect) WinHttpCloseHandle(hConnect);
    if (hSession) WinHttpCloseHandle(hSession);

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP, Windows 2000 Professional mit SP3 [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003, Windows 2000 Server mit SP3 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winhttp.h
Bibliothek	Winhttp.lib
DLL	Winhttp.dll
Verteilbare Komponente	WinHTTP 5.0 und Internet Explorer 5.01 oder höher unter Windows XP und Windows 2000.