Función WinHttpReadData (winhttp.h)

Artículo
08/27/2023

La función WinHttpReadData lee los datos de un identificador abierto por la función WinHttpOpenRequest .

Sintaxis

WINHTTPAPI BOOL WinHttpReadData(
  [in]  HINTERNET hRequest,
  [out] LPVOID    lpBuffer,
  [in]  DWORD     dwNumberOfBytesToRead,
  [out] LPDWORD   lpdwNumberOfBytesRead
);

Parámetros

[in] hRequest

Identificador HINTERNET válido devuelto de una llamada anterior a WinHttpOpenRequest. Se debe haber llamado a WinHttpReceiveResponse o WinHttpQueryDataAvailable para este identificador y debe haberse completado antes de llamar a WinHttpReadData. Aunque llamar a WinHttpReadData inmediatamente después de la finalización de WinHttpReceiveResponse evita el gasto de una copia de búfer, esto requiere que la aplicación use un búfer de longitud fija para la lectura.

[out] lpBuffer

Puntero a un búfer que recibe los datos leídos. Asegúrese de que este búfer sigue siendo válido hasta que WinHttpReadData se haya completado.

[in] dwNumberOfBytesToRead

Valor entero largo sin signo que contiene el número de bytes que se van a leer.

[out] lpdwNumberOfBytesRead

Puntero a una variable de entero largo sin signo que recibe el número de bytes leídos. WinHttpReadData establece este valor en cero antes de realizar cualquier comprobación de errores o trabajo. Cuando se usa WinHTTP de forma asincrónica, establezca siempre este parámetro en NULL y recupere la información de la función de devolución de llamada; no hacerlo puede provocar un error de memoria.

Valor devuelto

Devuelve TRUE si se ejecuta correctamente o FALSE de lo contrario. Para obtener información de error extendida, llame a GetLastError. En la tabla siguiente se identifican los códigos de error que se devuelven.

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 5.1 no admite SSL2 a menos que el cliente lo habilite específicamente.
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	No se puede llevar a cabo la operación solicitada 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_RESPONSE_DRAIN_OVERFLOW	Se devuelve cuando una respuesta entrante supera un límite interno de tamaño winHTTP.
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

A partir de Windows Vista y Windows Server 2008, WinHttp permite a las aplicaciones realizar codificación de transferencia fragmentada en los datos enviados al servidor. Cuando el encabezado Transfer-Encoding está presente en la respuesta WinHttp, WinHttpReadData quita la información de fragmentación antes de proporcionar los datos a la aplicación.

Incluso cuando WinHTTP se usa en modo asincrónico (es decir, cuando se ha establecido WINHTTP_FLAG_ASYNC en WinHttpOpen), esta función puede funcionar de forma sincrónica o asincrónica. Si esta función devuelve FALSE, se produjo un error en esta función y puede llamar a GetLastError para obtener información de error extendida. Si esta función devuelve TRUE, use el WINHTTP_CALLBACK_STATUS_READ_COMPLETE finalización para determinar si esta función se realizó correctamente y el valor de los parámetros. La finalización del WINHTTP_CALLBACK_STATUS_REQUEST_ERROR 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 lpdwNumberOfBytesRead en NULL y recupere los bytes leídos en la función de devolución de llamada; de lo contrario, se puede producir un error de memoria.

Cuando el búfer de lectura es muy pequeño, WinHttpReadData puede completarse de forma sincrónica. Si el WINHTTP_CALLBACK_STATUS_READ_COMPLETE finalización desencadena otra llamada a WinHttpReadData, la situación puede dar lugar a un desbordamiento de pila. En general, es mejor usar un búfer de lectura que sea comparable en tamaño o mayor que el búfer de lectura interno usado por WinHTTP, que es de 8 KB.

Si usa WinHttpReadData de forma sincrónica y el valor devuelto es TRUE y el número de bytes leídos es cero, la transferencia se ha completado y no hay más bytes para leer en el identificador. Esto es análogo a llegar al final del archivo en un archivo local. Si usa la función de forma asincrónica, se llama a la devolución de llamada WINHTTP_CALLBACK_STATUS_READ_COMPLETE con el parámetro dwStatusInformationLength establecido en cero cuando se encuentra el final de una respuesta.

WinHttpReadData intenta rellenar el búfer al que apunta lpBuffer hasta que no haya más datos disponibles en la respuesta. Si no han llegado suficientes datos desde el servidor, el búfer no se rellena.

Para 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 WinHttpReadData .

Los caracteres de un solo byte recuperados con WinHttpReadData no se convierten en caracteres de varios bytes.

Cuando el búfer de lectura es muy pequeño, WinHttpReadData puede completarse de forma sincrónica y, si el WINHTTP_CALLBACK_STATUS_READ_COMPLETE finalización desencadena otra llamada a WinHttpReadData, puede producirse un desbordamiento de pila. Es mejor usar un búfer de lectura que tenga un tamaño de 8 kilobytes o mayor.

Si no han llegado suficientes datos desde el servidor, WinHttpReadData no rellena completamente el búfer al que apunta lpBuffer. El búfer debe ser lo suficientemente grande como para contener los encabezados HTTP en la primera lectura y, al leer entradas de directorio codificadas HTML, debe ser lo suficientemente grande como para contener al menos una entrada completa.

Si se ha instalado una función de devolución de llamada de estado mediante 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_CONNECTION_CLOSED
WINHTTP_CALLBACK_STATUS_READ_COMPLETE

Nota Para Windows XP y Windows 2000, consulta la sección Requisitos en tiempo de ejecución de la página de inicio de WinHttp.

Ejemplos

En el ejemplo siguiente se muestra cómo usar la semántica de transacciones seguras para descargar un recurso desde un servidor de Protocolo de transferencia de hipertexto seguro (HTTPS). El código de ejemplo inicializa la interfaz de programación de aplicaciones (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, WinHttpReadData se usa para leer esos datos. Este proceso se repite hasta que se haya recuperado y mostrado todo el documento.

    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());
                break;
            }
            
            // No more available data.
            if (!dwSize)
                break;

            // Allocate space for the buffer.
            pszOutBuffer = new char[dwSize+1];
            if (!pszOutBuffer)
            {
                printf("Out of memory\n");
                break;
            }
            
            // 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;

            // This condition should never be reached since WinHttpQueryDataAvailable
            // reported that there are bits to read.
            if (!dwDownloaded)
                break;
                
        } while (dwSize > 0);
    }
    else
    {
        // Report any errors.
        printf( "Error %d has occurred.\n", GetLastError() );
    }

    // Close any open handles.
    if (hRequest) WinHttpCloseHandle(hRequest);
    if (hConnect) WinHttpCloseHandle(hConnect);
    if (hSession) WinHttpCloseHandle(hSession);

Requisitos

Requisito	Value
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.