Funzione WinHttpQueryDataAvailable (winhttp.h)

Articolo
03/15/2023

La funzione WinHttpQueryDataAvailable restituisce la quantità di dati, in byte, disponibile per la lettura con WinHttpReadData.

Sintassi

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

Parametri

[in] hRequest

Handle DELL'oggetto VALIDNET restituito da WinHttpOpenRequest. WinHttpReceiveResponse deve essere stato chiamato per questo handle e aver completato prima di chiamare WinHttpQueryDataAvailable .

[out] lpdwNumberOfBytesAvailable

Puntatore a una variabile long integer senza segno che riceve il numero di byte disponibili. Quando WinHTTP viene usato in modalità asincrona, impostare sempre questo parametro su NULL e recuperare i dati nella funzione di callback; non farlo può causare un errore di memoria.

Valore restituito

Restituisce TRUE se la funzione ha esito positivo o FALSE in caso contrario. Per ottenere dati di errore estesi, chiamare GetLastError. Tra i codici di errore restituiti sono riportati di seguito.

Codice di errore	Descrizione
ERROR_WINHTTP_CONNECTION_ERROR	La connessione con il server è stata reimpostata o terminata oppure è stato rilevato un protocollo SSL incompatibile. Ad esempio, WinHTTP versione 5.1 non supporta SSL2 a meno che il client non lo consenta in modo specifico.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	Impossibile completare l'operazione richiesta perché l'handle fornito non è nello stato corretto.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Il tipo di handle fornito non è corretto per questa operazione.
ERROR_WINHTTP_INTERNAL_ERROR	Si è verificato un errore interno.
ERROR_WINHTTP_OPERATION_CANCELLED	L'operazione è stata annullata, in genere perché l'handle su cui era operativa la richiesta è stato chiuso prima del completamento dell'operazione.
ERROR_WINHTTP_TIMEOUT	Timeout della richiesta.
ERROR_NOT_ENOUGH_MEMORY	Memoria insufficiente per completare l'operazione richiesta. (Codice errore di Windows)

Commenti

Anche quando WinHTTP viene usato in modalità asincrona , ovvero quando WINHTTP_FLAG_ASYNC è stato impostato in WinHttpOpen, questa funzione può operare in modo sincrono o asincrono. Se restituisce FALSE, l'errore non è riuscito ed è possibile chiamare GetLastError per ottenere informazioni estese sull'errore. Se restituisce TRUE, usare il WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE completamento per determinare se questa funzione ha avuto esito positivo e il valore dei parametri. Il completamento WINHTTP_CALLBACK_STATUS_REQUEST_ERROR indica che l'operazione è stata completata in modo asincrono, ma non riuscita.

Avviso Quando WinHTTP viene usato in modalità asincrona, impostare sempre il parametro lpdwNumberOfBytesAvailable su NULL e recuperare i byte disponibili nella funzione di callback; in caso contrario, può verificarsi un errore di memoria.

Questa funzione restituisce il numero di byte di dati disponibili per la lettura immediata da una chiamata successiva a WinHttpReadData. Se non sono disponibili dati e la fine del file non è stata raggiunta, si verifica una delle due cose. Se la sessione è sincrona, la richiesta attende fino a quando i dati non diventano disponibili. Se la sessione è asincrona, la funzione restituisce TRUE e, quando i dati diventano disponibili, chiama la funzione di callback con WINHTTP_STATUS_CALLBACK_DATA_AVAILABLE e indica il numero di byte immediatamente disponibili per la lettura chiamando WinHttpReadData.

La quantità di dati rimanenti non viene ricalcolata finché non vengono letti tutti i dati disponibili indicati dalla chiamata a WinHttpQueryDataAvailable .

Usare il valore restituito di WinHttpReadData per determinare quando una risposta è stata completamente letta.

Importante Non usare il valore restituito di WinHttpQueryDataAvailable per determinare se è stata raggiunta la fine di una risposta, perché non tutti i server terminano correttamente le risposte e una risposta terminata in modo non corretto causa winHttpQueryDataAvailable per prevedere più dati.

Per gli handle DELLA RETE GESTITA creati dalla funzione WinHttpOpenRequest e inviati da WinHttpSendRequest, è necessario eseguire una chiamata a WinHttpReceiveResponse sull'handle prima che sia possibile usare WinHttpQueryDataAvailable .

Se è stata installata una funzione di callback di stato con WinHttpSetStatusCallback, le notifiche seguenti impostate nel parametro dwNotificationFlags di WinHttpSetStatusCallback indicano lo stato di avanzamento nel controllo dei dati disponibili:

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

Nota Per altre informazioni su Windows XP e Windows 2000, vedere Requisiti di runtime.

Esempio

L'esempio seguente illustra come usare la semantica della transazione sicura per scaricare una risorsa da un server HTTPS. Il codice di esempio inizializza l'API 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, quindi WinHttpReadData viene usato per leggere i dati. Questo processo si ripete fino a quando non viene recuperato e visualizzato l'intero documento.

Importante

Se vuoi che alcuni dati vengano elaborati e analizzati al momento della ricezione, devi chiamare WinHttpQueryDataAvailable e WinHttpReadData. Se si sta tentando di scaricare l'intera risposta il più rapidamente possibile, chiamare direttamente WinHttpReadData , perché WinHttpReadData tenta di riempire il buffer prima del completamento.

L'esempio di codice seguente alloca anche in ogni iterazione del ciclo. Per il codice di produzione, dove le prestazioni sono importanti, è invece possibile iniziare con un buffer di dimensioni appropriate (ad esempio 1 megabyte) e ridimensionarlo, se necessario. In pratica , WinHttpQueryDataAvailable restituisce non più di 8 kilobyte.


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

Requisiti


Client minimo supportato	Windows XP, Windows 2000 Professional con SP3 [solo app desktop]
Server minimo supportato	Windows Server 2003, Windows 2000 Server con SP3 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winhttp.h
Libreria	Winhttp.lib
DLL	Winhttp.dll
Componente ridistribuibile	WinHTTP 5.0 e Internet Explorer 5.01 o versione successiva in Windows XP e Windows 2000.