Función WinHttpWriteData (winhttp.h)

Artículo
03/15/2023

La función WinHttpWriteData escribe datos de solicitud en un servidor HTTP.

Sintaxis

WINHTTPAPI BOOL WinHttpWriteData(
  [in]  HINTERNET hRequest,
  [in]  LPCVOID   lpBuffer,
  [in]  DWORD     dwNumberOfBytesToWrite,
  [out] LPDWORD   lpdwNumberOfBytesWritten
);

Parámetros

[in] hRequest

Identificador HINTERNET válido devuelto por WinHttpOpenRequest. Espere hasta que WinHttpSendRequest se haya completado antes de llamar a esta función.

[in] lpBuffer

Puntero a un búfer que contiene los datos que se van a enviar al servidor. Asegúrese de que este búfer permanece válido hasta que WinHttpWriteData se complete.

[in] dwNumberOfBytesToWrite

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

[out] lpdwNumberOfBytesWritten

Puntero a una variable de entero largo sin signo que recibe el número de bytes escritos en el búfer. La función WinHttpWriteData establece este valor en cero antes de realizar cualquier comprobación de errores o trabajo. Cuando se usa WinHTTP de forma asincrónica, este parámetro debe establecerse en NULL y recuperar la información de la función de devolución de llamada. Si no lo hace, se puede producir 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. Entre los códigos de error devueltos se encuentran:

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	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_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 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, puede llamar a GetLastError para obtener información de error extendida. Si esta función devuelve TRUE, use el WINHTTP_CALLBACK_STATUS_WRITE_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 se usa WinHTTP de forma asincrónica, establezca siempre el parámetro lpdwNumberOfBytesWritten en NULL y recupere los bytes escritos en la función de devolución de llamada; de lo contrario, se puede producir un error de memoria.

Cuando la aplicación envía datos, puede llamar a WinHttpReceiveResponse para finalizar la transferencia de datos. Si se llama a WinHttpCloseHandle , se anula la transferencia de datos.

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 el envío de datos al servidor:

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
WINHTTP_CALLBACK_STATUS_DATA_WRITTEN
WINHTTP_CALLBACK_STATUS_SENDING_REQUEST
WINHTTP_CALLBACK_STATUS_REQUEST_SENT
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE

Pueden surgir dos problemas al intentar realizar datos POST (o PUT) en servidores proxy o servidores que se ponen en prueba mediante la autenticación NTLM o Negotiate. En primer lugar, estos servidores proxy o servidores pueden enviar desafíos 401/407 y cerrar la conexión antes de que todos los datos se puedan publicar, en cuyo caso no solo se produce un error de WinHttpWriteData , sino que también WinHTTP no puede controlar los desafíos de autenticación. NTLM y Negotiate requieren que todos los protocolos de enlace de autenticación se intercambien en la misma conexión de socket, por lo que se produce un error en la autenticación si la conexión se interrumpe prematuramente.

En segundo lugar, NTLM y Negotiate pueden requerir varios protocolos de enlace para completar la autenticación, lo que requiere que los datos se vuelvan a publicar para cada segmento de autenticación. Esto puede ser muy ineficaz para cargas de datos de gran tamaño.

Para solucionar estos dos problemas, una solución consiste en enviar una solicitud de preparación idempotente, como HEAD a la autenticación v-dir primero, controlar los desafíos de autenticación asociados a esta solicitud y, a continuación, solo los datos POST. Siempre que se vuelva a usar el mismo socket para controlar el post'ing, no se deben encontrar más desafíos de autenticación y se pueden cargar todos los datos a la vez. Puesto que un socket autenticado solo se puede reutilizar para las solicitudes posteriores dentro de la misma sesión, POST debe salir en el mismo socket siempre que el socket no esté agrupado con solicitudes simultáneas que compiten por él.

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 este ejemplo se muestra el código que escribe datos en un servidor HTTP. El nombre del servidor proporcionado en el ejemplo, www.wingtiptoys.com, es ficticio y debe reemplazarse por el nombre de un servidor para el que tiene acceso de escritura.

    PCSTR pszData = "WinHttpWriteData Example";
    DWORD dwBytesWritten = 0;
    BOOL  bResults = FALSE;
    HINTERNET hSession = NULL,
              hConnect = NULL,
              hRequest = NULL;

    // Use WinHttpOpen to obtain a session handle.
    hSession = WinHttpOpen(  L"A WinHTTP Example Program/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.wingtiptoys.com",
                                   INTERNET_DEFAULT_HTTP_PORT, 0);

    // Create an HTTP Request handle.
    if (hConnect)
        hRequest = WinHttpOpenRequest( hConnect, L"PUT", 
                                       L"/writetst.txt", 
                                       NULL, WINHTTP_NO_REFERER, 
                                       WINHTTP_DEFAULT_ACCEPT_TYPES, 
                                       0);

    // Send a Request.
    if (hRequest) 
        bResults = WinHttpSendRequest( hRequest, 
                                       WINHTTP_NO_ADDITIONAL_HEADERS,
                                       0, WINHTTP_NO_REQUEST_DATA, 0, 
                                       (DWORD)strlen(pszData), 0);

    // Write data to the server.
    if (bResults)
        bResults = WinHttpWriteData( hRequest, pszData, 
                                     (DWORD)strlen(pszData), 
                                     &dwBytesWritten);

    // End the request.
    if (bResults)
        bResults = WinHttpReceiveResponse( hRequest, NULL);

    // Report any errors.
    if (!bResults)
        printf("Error %d has occurred.\n",GetLastError());


    // Close any 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.