WinHttpQueryDataAvailable, fonction (winhttp.h)

Article
08/27/2023

La fonction WinHttpQueryDataAvailable retourne la quantité de données, en octets, pouvant être lues avec WinHttpReadData.

Syntaxe

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

Paramètres

[in] hRequest

Handle HINTERNET valide retourné par WinHttpOpenRequest. WinHttpReceiveResponse doit avoir été appelé pour ce handle et avoir terminé avant l’appel de WinHttpQueryDataAvailable .

[out] lpdwNumberOfBytesAvailable

Pointeur vers une variable entière longue non signée qui reçoit le nombre d’octets disponibles. Lorsque WinHTTP est utilisé en mode asynchrone, définissez toujours ce paramètre sur NULL et récupérez les données dans la fonction de rappel ; le fait de ne pas le faire peut provoquer une erreur de mémoire.

Valeur retournée

Retourne TRUE si la fonction réussit, ou FALSE dans le cas contraire. Pour obtenir des données d’erreur étendues, appelez GetLastError. Parmi les codes d’erreur retournés figurent les suivants.

Code d'erreur	Description
ERROR_WINHTTP_CONNECTION_ERROR	La connexion au serveur a été réinitialisée ou terminée, ou un protocole SSL incompatible a été rencontré. Par exemple, WinHTTP version 5.1 ne prend pas en charge SSL2, sauf si le client l’active spécifiquement.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	L’opération demandée ne peut pas se terminer, car le handle fourni n’est pas dans l’état correct.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	Le type de handle fourni est incorrect pour cette opération.
ERROR_WINHTTP_INTERNAL_ERROR	Une erreur interne s'est produite.
ERROR_WINHTTP_OPERATION_CANCELLED	L’opération a été annulée, généralement parce que le handle sur lequel la demande fonctionnait a été fermé avant la fin de l’opération.
ERROR_WINHTTP_TIMEOUT	Le délai d'attente de la requête a expiré.
ERROR_NOT_ENOUGH_MEMORY	La mémoire disponible n’était pas suffisante pour effectuer l’opération demandée. (Code d’erreur Windows)

Remarques

Même lorsque WinHTTP est utilisé en mode asynchrone (c’est-à-dire, lorsque WINHTTP_FLAG_ASYNC a été défini dans WinHttpOpen), cette fonction peut fonctionner de manière synchrone ou asynchrone. S’il retourne FALSE, il a échoué et vous pouvez appeler GetLastError pour obtenir des informations d’erreur étendues. S’il retourne TRUE, utilisez la saisie semi-automatique WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE pour déterminer si cette fonction a réussi et la valeur des paramètres. La WINHTTP_CALLBACK_STATUS_REQUEST_ERROR’achèvement indique que l’opération s’est terminée de manière asynchrone, mais a échoué.

Avertissement Lorsque WinHTTP est utilisé en mode asynchrone, définissez toujours le paramètre lpdwNumberOfBytesAvailable sur NULL et récupérez les octets disponibles dans la fonction de rappel ; sinon, une erreur de mémoire peut se produire.

Cette fonction retourne le nombre d’octets de données disponibles pour la lecture immédiatement par un appel suivant à WinHttpReadData. Si aucune donnée n’est disponible et que la fin du fichier n’a pas été atteinte, l’une des deux choses se produit. Si la session est synchrone, la requête attend que les données soient disponibles. Si la session est asynchrone, la fonction retourne TRUE et, lorsque les données deviennent disponibles, appelle la fonction de rappel avec WINHTTP_STATUS_CALLBACK_DATA_AVAILABLE et indique le nombre d’octets immédiatement disponibles en lecture en appelant WinHttpReadData.

La quantité de données restante n’est pas recalculée tant que toutes les données disponibles indiquées par l’appel à WinHttpQueryDataAvailable n’ont pas été lues.

Utilisez la valeur de retour de WinHttpReadData pour déterminer quand une réponse a été entièrement lue.

Important N’utilisez pas la valeur de retour de WinHttpQueryDataAvailable pour déterminer si la fin d’une réponse a été atteinte, car tous les serveurs ne terminent pas correctement les réponses, et une réponse incorrectement terminée fait en sorte que WinHttpQueryDataAvailable anticipe davantage de données.

Pour les handles HINTERNET créés par la fonction WinHttpOpenRequest et envoyés par WinHttpSendRequest, un appel à WinHttpReceiveResponse doit être effectué sur le handle avant que WinHttpQueryDataAvailable puisse être utilisé.

Si une fonction de rappel status a été installée avec WinHttpSetStatusCallback, celles des notifications suivantes qui ont été définies dans le paramètre dwNotificationFlags de WinHttpSetStatusCallback indiquent la progression de la vérification des données disponibles :

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

Note Pour plus d’informations sur Windows XP et Windows 2000, consultez Exigences au moment de l’exécution.

Exemples

L’exemple suivant montre comment utiliser la sémantique de transaction sécurisée pour télécharger une ressource à partir d’un serveur HTTPS. L’exemple de code initialise l’API WinHTTP, sélectionne un serveur HTTPS cible, puis ouvre et envoie une demande pour cette ressource sécurisée.
WinHttpQueryDataAvailable est utilisé avec le handle de demande pour déterminer la quantité de données disponibles en téléchargement, puis WinHttpReadData est utilisé pour lire ces données. Ce processus se répète jusqu’à ce que l’intégralité du document ait été récupérée et affichée.

Important

Si vous souhaitez obtenir des données aussi rapidement que possible (c’est-à-dire que vous traitez et analysez les données au fur et à mesure de leur réception), vous devez appeler WinHttpQueryDataAvailable et WinHttpReadData. Si vous essayez de télécharger l’ensemble de la réponse le plus rapidement possible, appelez WinHttpReadData directement, car WinHttpReadData tente de remplir votre mémoire tampon avant de terminer.

En outre, l’exemple de code ci-dessous alloue à chaque itération de boucle. Pour le code de production, où les performances sont importantes, vous pouvez commencer par une mémoire tampon de taille appropriée (peut-être 1 mégaoctet) et la redimensionner si nécessaire. En pratique, WinHttpQueryDataAvailable ne retourne pas plus de 8 kilo-octets.


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

Configuration requise


Client minimal pris en charge	Windows XP, Windows 2000 Professionnel avec SP3 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003, Windows 2000 Server avec SP3 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winhttp.h
Bibliothèque	Winhttp.lib
DLL	Winhttp.dll
Composant redistribuable	WinHTTP 5.0 et Internet Explorer 5.01 ou version ultérieure sur Windows XP et Windows 2000.