Función WinHttpSendRequest (winhttp.h)
La función WinHttpSendRequest envía la solicitud especificada al servidor HTTP.
Sintaxis
WINHTTPAPI BOOL WinHttpSendRequest(
[in] HINTERNET hRequest,
[in, optional] LPCWSTR lpszHeaders,
[in] DWORD dwHeadersLength,
[in, optional] LPVOID lpOptional,
[in] DWORD dwOptionalLength,
[in] DWORD dwTotalLength,
[in] DWORD_PTR dwContext
);
Parámetros
[in] hRequest
Un identificador HINTERNET devuelto por WinHttpOpenRequest.
[in, optional] lpszHeaders
Puntero a una cadena que contiene los encabezados adicionales que se van a anexar a la solicitud. Este parámetro puede ser WINHTTP_NO_ADDITIONAL_HEADERS si no hay encabezados adicionales que se van a anexar.
[in] dwHeadersLength
Valor entero largo sin signo que contiene la longitud, en caracteres, de los encabezados adicionales. Si este parámetro es -1L y pwszHeaders no es NULL, esta función supone que pwszHeaders termina en null y se calcula la longitud.
[in, optional] lpOptional
Puntero a un búfer que contiene los datos opcionales que se van a enviar inmediatamente después de los encabezados de solicitud. Este parámetro se usa generalmente para las operaciones POST y PUT. Los datos opcionales pueden ser el recurso o los datos publicados en el servidor. Este parámetro puede ser WINHTTP_NO_REQUEST_DATA si no hay datos opcionales que enviar.
Si el parámetro dwOptionalLength es 0, este parámetro se omite y se establece en NULL.
Este búfer debe permanecer disponible hasta que se cierre el identificador de solicitud o se haya completado la llamada a WinHttpReceiveResponse .
[in] dwOptionalLength
Valor entero largo sin signo que contiene la longitud, en bytes, de los datos opcionales. Este parámetro puede ser cero si no hay datos opcionales que enviar.
Este parámetro debe contener una longitud válida cuando el parámetro lpOptional no es NULL. De lo contrario, lpOptional se omite y se establece en NULL.
[in] dwTotalLength
Valor entero largo sin signo que contiene la longitud, en bytes, de los datos totales enviados. Este parámetro especifica el encabezado Content-Length de la solicitud. Si el valor de este parámetro es mayor que la longitud especificada por dwOptionalLength, se puede usar WinHttpWriteData para enviar datos adicionales.
dwTotalLength no debe cambiar entre llamadas a WinHttpSendRequest para la misma solicitud. Si dwTotalLength debe cambiarse, el autor de la llamada debe crear una nueva solicitud.
[in] dwContext
Puntero a una variable de tamaño de puntero que contiene un valor definido por la aplicación que se pasa, con el identificador de solicitud, a cualquier función de devolución de llamada.
Valor devuelto
Devuelve TRUE si se ejecuta correctamente o FALSE de lo contrario. Para obtener información de error extendida, llame a GetLastError. Los códigos de error se enumeran en la tabla siguiente.
| Código de error | Descripción |
|---|---|
|
Se devuelve si se produjo un error en la conexión al servidor. |
|
El servidor HTTP seguro requiere un certificado de cliente. La aplicación recupera la lista de emisores de certificados llamando a WinHttpQueryOption con la opción WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST .
Si el servidor solicita el certificado de cliente, pero no lo requiere, la aplicación puede llamar alternativamente a WinHttpSetOption con la opción WINHTTP_OPTION_CLIENT_CERT_CONTEXT . En este caso, la aplicación especifica la macro WINHTTP_NO_CLIENT_CERT_CONTEXT en el parámetro lpBuffer de WinHttpSetOption. Para obtener más información, consulte la opción WINHTTP_OPTION_CLIENT_CERT_CONTEXT . Windows Server 2003 con SP1, Windows XP con SP2 y Windows 2000: Este error no se admite. |
|
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. |
|
No se puede llevar a cabo la operación solicitada porque el identificador proporcionado no está en el estado correcto. |
|
El tipo de identificador proporcionado es incorrecto para esta operación. |
|
Se ha producido un error interno. |
|
La dirección URL no es válida. |
|
Error en el intento de inicio de sesión. Cuando se detecta este error, el identificador de solicitud debe cerrarse con WinHttpCloseHandle. Se debe crear un nuevo identificador de solicitud antes de reintentar la función que generó este error originalmente. |
|
No se puede resolver el nombre del servidor. |
|
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. |
|
Se devuelve cuando una respuesta entrante supera un límite interno de tamaño winHTTP. |
|
Se encontraron uno o varios errores en el certificado de Capa de sockets seguros (SSL) enviado por el servidor. Para determinar qué tipo de error se encontró, compruebe a través de una notificación de WINHTTP_CALLBACK_STATUS_SECURE_FAILURE en una función de devolución de llamada de estado. Para obtener más información, consulte WINHTTP_STATUS_CALLBACK. |
|
La compatibilidad con la función WinHTTP se apaga o descarga. |
|
Se ha agotado el tiempo de espera de la solicitud. |
|
La dirección URL especificó un esquema distinto de "http:" o "https:". |
|
No había suficiente memoria disponible para completar la operación solicitada. (Código de error de Windows) Windows Server 2003, Windows XP y Windows 2000: El intervalo de reserva TCP establecido con la opción WINHTTP_OPTION_PORT_RESERVATION no es lo suficientemente grande como para enviar esta solicitud. |
|
La longitud de contenido especificada en el parámetro dwTotalLength no coincide con la longitud especificada en el encabezado Content-Length.
El parámetro lpOptional debe ser NULL y el parámetro dwOptionalLength debe ser cero cuando el encabezado Transfer-Encoding esté presente. El encabezado Content-Length no puede estar presente cuando el encabezado Transfer-Encoding está presente. |
|
La aplicación debe llamar a WinHttpSendRequest de nuevo debido a un desafío de redirección o autenticación.
Windows Server 2003 con SP1, Windows XP con SP2 y Windows 2000: Este error no se admite. |
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. En cualquier caso, si la solicitud se envía correctamente, se vuelve a llamar a la aplicación con el estado de finalización establecido en WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE. 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. Al recibir la devolución de llamada de estado WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE , la aplicación puede empezar a recibir una respuesta del servidor con WinHttpReceiveResponse. Antes de entonces, no se puede llamar a ninguna otra función asincrónica; de lo contrario, se devuelve ERROR_WINHTTP_INCORRECT_HANDLE_STATE .
Una aplicación no debe eliminar ni modificar el búfer al que apunta lpOptional hasta que se cierre el identificador de solicitud o se haya completado la llamada a WinHttpReceiveResponse , ya que se pudo encontrar un desafío de autenticación o redireccionamiento que requería los datos opcionales durante la recepción de la respuesta. Si la operación debe anularse con WinHttpCloseHandle, la aplicación debe mantener el búfer válido hasta que reciba la devolución de llamada WINHTTP_CALLBACK_STATUS_REQUEST_ERROR con un código de error ERROR_WINHTTP_OPERATION_CANCELLED .
Si WinHTTP se usa de forma sincrónica, es decir, cuando WINHTP_FLAG_ASYNC no se estableció en WinHttpOpen, no se llama a una aplicación con un estado de finalización aunque se registre una función de devolución de llamada. Mientras está en este modo, la aplicación puede llamar a WinHttpReceiveResponse cuando WinHttpSendRequest devuelve.
La función WinHttpSendRequest envía la solicitud especificada al servidor HTTP y permite al cliente especificar encabezados adicionales que se enviarán junto con la solicitud.
Esta función también permite al cliente especificar datos opcionales para enviar al servidor HTTP inmediatamente después de los encabezados de solicitud. Esta característica se usa generalmente para operaciones de escritura como PUT y POST.
Una aplicación puede usar el mismo identificador de solicitud HTTP en varias llamadas a WinHttpSendRequest para volver a enviar la misma solicitud, pero la aplicación debe leer todos los datos devueltos de la llamada anterior antes de volver a llamar a esta función.
Se valida el nombre y el valor de los encabezados de solicitud agregados con esta función. Los encabezados deben estar bien formados. Para obtener más información sobre los encabezados HTTP válidos, consulte RFC 2616. Si se usa un encabezado no válido, se produce un error en esta función y GetLastError devuelve ERROR_INVALID_PARAMETER. No se agrega el encabezado no válido.
Windows 2000: Al enviar solicitudes desde varios subprocesos, puede haber una disminución significativa en el rendimiento de la red y la CPU.
Windows XP y Windows 2000: Consulte Requisitos en tiempo de ejecución.
WinHttpSetStatusCallback
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 la solicitud:- WINHTTP_CALLBACK_STATUS_DETECTING_PROXY (no implementado)
- WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE (solo en modo asincrónico)
- WINHTTP_CALLBACK_STATUS_REDIRECT
- WINHTTP_CALLBACK_STATUS_SECURE_FAILURE
- WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESOLVING_NAME
- WINHTTP_CALLBACK_STATUS_NAME_RESOLVED
- WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER
- WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER
- WINHTTP_CALLBACK_STATUS_SENDING_REQUEST
- WINHTTP_CALLBACK_STATUS_REQUEST_SENT
- WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE
- WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED
- WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION
- WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED
Compatibilidad con carga de más de 4 GB
A partir de Windows Vista y Windows Server 2008, WinHttp admite la carga de archivos hasta el tamaño de un LARGE_INTEGER (2^64 bytes) mediante el encabezado Content-Length. Las longitudes de carga especificadas en la llamada a WinHttpSendRequest se limitan al tamaño de un DWORD (2^32 bytes). Para cargar datos en una dirección URL mayor que una DWORD, la aplicación debe proporcionar la longitud en el encabezado Content-Length de la solicitud. En este caso, la aplicación cliente WinHttp llama a WinHttpSendRequest con el parámetro dwTotalLength establecido en WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH.Si el encabezado Content-Length especifica una longitud inferior a 2^32, la aplicación también debe especificar la longitud del contenido en la llamada a WinHttpSendRequest. Si el parámetro dwTotalLength no coincide con la longitud especificada en el encabezado Content-Length, se produce un error en la llamada y devuelve ERROR_INVALID_PARAMETER.
El encabezado Content-Length se puede agregar en la llamada a WinHttpAddRequestHeaders, o bien se puede especificar en el parámetro lpszHeader de WinHttpSendRequest , como se muestra en el ejemplo de código siguiente.
BOOL fRet = WinHttpSendRequest(
hReq,
L"Content-Length: 68719476735\r\n",
-1L,
WINHTTP_NO_REQUEST_DATA,
0,
WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH,
pMyContent);
Encabezado transfer-encoding
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 solicitud WinHttp, el parámetro dwTotalLength de la llamada a WinHttpSendRequest se establece en WINHTTP_IGNORE_REQUEST_TOTAL_LENGTH y la aplicación envía el cuerpo de la entidad en una o varias llamadas a WinHttpWriteData. El parámetro lpOptional de WinHttpSendRequest debe ser NULL y el parámetro dwOptionLength debe ser cero; de lo contrario, se devuelve un error de ERROR_WINHTTP_INVALID_PARAMETER . Para finalizar la transferencia de datos fragmentada, la aplicación genera un fragmento de longitud cero y lo envía en la última llamada a WinHttpWriteData.Ejemplos
En el ejemplo de código siguiente se muestra cómo obtener un identificador HINTERNET , abrir una sesión HTTP, crear un encabezado de solicitud y enviar ese encabezado al servidor.
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,
0, 0);
// Place additional code here.
// Report 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
| 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. |
Consulte también
Acerca de los servicios HTTP de Microsoft Windows (WinHTTP)
WINHTTP_STATUS_CALLBACK