Función WinHttpQueryDataAvailable (winhttp.h)

Artículo
03/15/2023

La función WinHttpQueryDataAvailable devuelve la cantidad de datos, en bytes, disponibles para leerse con WinHttpReadData.

Sintaxis

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

Parámetros

[in] hRequest

Identificador HINTERNET válido devuelto por WinHttpOpenRequest. Se debe haber llamado a WinHttpReceiveResponse para este identificador y se ha completado antes de llamar a WinHttpQueryDataAvailable.

[out] lpdwNumberOfBytesAvailable

Puntero a una variable de entero largo sin signo que recibe el número de bytes disponibles. Cuando WinHTTP se usa en modo asincrónico, establezca siempre este parámetro en NULL y recupere datos en la función de devolución de llamada; no hacerlo puede provocar un error de memoria.

Valor devuelto

Devuelve TRUE si la función se realiza correctamente o FALSE en caso contrario. Para obtener datos de error extendidos, llame a GetLastError. Entre los códigos de error devueltos se encuentran los siguientes.

Código de error	Descripción
ERROR_WINHTTP_CONNECTION_ERROR	Se ha restablecido o finalizado la conexión con el servidor, o se encontró un protocolo SSL incompatible. Por ejemplo, WinHTTP versión 5.1 no admite SSL2 a menos que el cliente lo habilite específicamente.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	La operación solicitada no se puede completar porque el identificador proporcionado no está en el estado correcto.
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	El tipo de identificador proporcionado es incorrecto para esta operación.
ERROR_WINHTTP_INTERNAL_ERROR	Se ha producido un error interno.
ERROR_WINHTTP_OPERATION_CANCELLED	La operación se canceló, normalmente porque el identificador en el que estaba funcionando la solicitud se cerró antes de que se completara la operación.
ERROR_WINHTTP_TIMEOUT	La solicitud ha agotado el tiempo de espera.
ERROR_NOT_ENOUGH_MEMORY	No había suficiente memoria disponible para completar la operación solicitada. (Código de error de Windows)

Comentarios

Incluso cuando WinHTTP se usa en modo asincrónico (es decir, cuando WINHTTP_FLAG_ASYNC se ha establecido en WinHttpOpen), esta función puede funcionar de forma sincrónica o asincrónica. Si devuelve FALSE, se produjo un error y puede llamar a GetLastError para obtener información de error extendida. Si devuelve TRUE, use el WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE finalización para determinar si esta función se realizó correctamente y el valor de los parámetros. El WINHTTP_CALLBACK_STATUS_REQUEST_ERROR finalización indica que la operación se completó de forma asincrónica, pero no se pudo realizar.

Advertencia Cuando WinHTTP se usa en modo asincrónico, establezca siempre el parámetro lpdwNumberOfBytesAvailable en NULL y recupere los bytes disponibles en la función de devolución de llamada; de lo contrario, se puede producir un error de memoria.

Esta función devuelve el número de bytes de datos que están disponibles para leer inmediatamente mediante una llamada posterior a WinHttpReadData. Si no hay datos disponibles y no se ha alcanzado el final del archivo, se produce una de estas dos cosas. Si la sesión es sincrónica, la solicitud espera hasta que los datos estén disponibles. Si la sesión es asincrónica, la función devuelve TRUE y, cuando los datos están disponibles, llama a la función de devolución de llamada con WINHTTP_STATUS_CALLBACK_DATA_AVAILABLE e indica el número de bytes disponibles inmediatamente para leer mediante una llamada a WinHttpReadData.

La cantidad de datos que permanece no se vuelve a calcular hasta que se lean todos los datos disponibles indicados por la llamada a WinHttpQueryDataAvailable .

Use el valor devuelto de WinHttpReadData para determinar cuándo se ha leído completamente una respuesta.

Importante No use el valor devuelto de WinHttpQueryDataAvailable para determinar si se ha alcanzado el final de una respuesta, ya que no todos los servidores finalizan correctamente las respuestas y una respuesta terminada incorrectamente hace que WinHttpQueryDataAvailable anticipe más datos.

En el caso de los identificadores HINTERNET creados por la función WinHttpOpenRequest y enviados por WinHttpSendRequest, se debe realizar una llamada a WinHttpReceiveResponse en el identificador antes de que se pueda usar WinHttpQueryDataAvailable .

Si se ha instalado una función de devolución de llamada de estado con WinHttpSetStatusCallback, las de las siguientes notificaciones que se han establecido en el parámetro dwNotificationFlags de WinHttpSetStatusCallback indican el progreso en la comprobación de los datos disponibles:

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

Nota Para obtener más información sobre Windows XP y Windows 2000, consulta Requisitos en tiempo de ejecución.

Ejemplos

En el ejemplo siguiente se muestra cómo usar la semántica de transacciones seguras para descargar un recurso desde un servidor HTTPS. El código de ejemplo inicializa la API winHTTP, selecciona un servidor HTTPS de destino y, a continuación, abre y envía una solicitud para este recurso seguro.
WinHttpQueryDataAvailable se usa con el identificador de solicitud para determinar la cantidad de datos disponibles para su descarga y, a continuación, Se usa WinHttpReadData para leer esos datos. Este proceso se repite hasta que se haya recuperado y mostrado todo el documento.

Importante

Si desea algunos datos lo antes posible (es decir, está procesando y analizando los datos a medida que los recibe), debe llamar a WinHttpQueryDataAvailable y WinHttpReadData. Si intenta descargar toda la respuesta lo antes posible, llame directamente a WinHttpReadData , ya que WinHttpReadData intenta rellenar el búfer antes de completarse.

Además, el ejemplo de código siguiente asigna en cada iteración de bucle. En el caso del código de producción, donde el rendimiento es importante, podría empezar con un búfer de tamaño adecuado (quizás 1 megabyte) y cambiar su tamaño si es necesario. En la práctica, WinHttpQueryDataAvailable no devuelve más de 8 kilobytes.


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

Requisitos


Cliente mínimo compatible	Windows XP, Windows 2000 Professional con SP3 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003, Windows 2000 Server con SP3 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winhttp.h
Library	Winhttp.lib
Archivo DLL	Winhttp.dll
Redistribuible	WinHTTP 5.0 e Internet Explorer 5.01 o posterior en Windows XP y Windows 2000.