Función WinHttpSetStatusCallback (winhttp.h)
La función WinHttpSetStatusCallback configura una función de devolución de llamada a la que WinHTTP puede llamar a medida que se realiza el progreso durante una operación.
Sintaxis
WINHTTPAPI WINHTTP_STATUS_CALLBACK WinHttpSetStatusCallback(
[in] HINTERNET hInternet,
[in] WINHTTP_STATUS_CALLBACK lpfnInternetCallback,
[in] DWORD dwNotificationFlags,
[in] DWORD_PTR dwReserved
);
Parámetros
[in] hInternet
IDENTIFICADOR HINTERNET para el que se va a establecer la devolución de llamada.
[in] lpfnInternetCallback
Puntero a la función de devolución de llamada que se va a llamar cuando se realiza el progreso. Establézcalo en NULL para quitar la función de devolución de llamada existente. Para obtener más información sobre la función de devolución de llamada, consulte WINHTTP_STATUS_CALLBACK.
[in] dwNotificationFlags
Valor entero largo sin signo que especifica marcas para indicar qué eventos activan la función de devolución de llamada.
Los valores posibles son los siguientes.
| Valor | Significado |
|---|---|
|
Se activa tras cualquier notificación de finalización. Esta marca especifica que se usan todas las notificaciones necesarias para las operaciones de lectura o escritura. Consulte WINHTTP_STATUS_CALLBACK para obtener una lista de finalizaciones. |
|
Se activa tras cualquier notificación de cambio de estado, incluidas las finalizaciones. Consulte WINHTTP_STATUS_CALLBACK para obtener una lista de notificaciones. |
|
Se activa al comenzar y completar la resolución de nombres. |
|
Se activa al comenzar y completar la conexión con el servidor. |
|
Se activa al detectar el servidor proxy. |
|
Se activa al completar una consulta de datos. |
|
Se activa cuando los encabezados de respuesta están disponibles para su recuperación. |
|
Se activa tras la finalización de una operación de lectura de datos. |
|
Se activa cuando se produce un error asincrónico. |
|
Se activa al comenzar y completar el envío de un encabezado de solicitud con WinHttpSendRequest. |
|
Se activa cuando se ha enviado un encabezado de solicitud con WinHttpSendRequest. |
|
Se activa tras la finalización de una operación de publicación de datos. |
|
Se activa al comenzar y completar la recepción de un recurso desde el servidor HTTP. |
|
Se activa al comenzar y completar el cierre de una conexión HTTP. |
|
Se activa cuando se crea o cierra un identificador HINTERNET . |
|
Se activa cuando se redirige la solicitud. |
|
Se activa al recibir un mensaje de código de estado intermedio (100 niveles) del servidor. |
|
Se activa tras un error de conexión segura. |
[in] dwReserved
Este parámetro está reservado y debe ser NULL.
Valor devuelto
Si se ejecuta correctamente, devuelve un puntero a la función de devolución de llamada de estado definida anteriormente o NULL si no había ninguna función de devolución de llamada de estado definida previamente. Devuelve WINHTTP_INVALID_STATUS_CALLBACK si no se pudo instalar la función de devolución de llamada. Para obtener información de error extendida, llame a GetLastError. Entre los códigos de error devueltos se encuentran los siguientes.
| Código de error | Descripción |
|---|---|
|
El tipo de identificador proporcionado es incorrecto para esta operación. |
|
Se ha producido un error interno. |
|
No había suficiente memoria disponible para completar la operación solicitada. (Código de error de Windows) |
Comentarios
Si establece la devolución de llamada en el identificador de sesión antes de crear el identificador de solicitud, el identificador de solicitud hereda el puntero de la función de devolución de llamada de su sesión primaria.
Incluso cuando WinHTTP se usa en modo asincrónico (es decir, cuando se ha establecido WINHTTP_FLAG_ASYNC en WinHttpOpen), esta función funciona de forma sincrónica. El valor devuelto indica éxito o error. Para obtener información de error extendida, llame a GetLastError.
Tanto las funciones sincrónicas como asincrónicas usan la función de devolución de llamada para indicar el progreso de la solicitud, como resolver un nombre, conectarse a un servidor, etc. La función de devolución de llamada es necesaria para una operación asincrónica.
Una función de devolución de llamada se puede establecer en cualquier identificador y se hereda por identificadores derivados. Se puede cambiar una función de devolución de llamada mediante WinHttpSetStatusCallback, siempre que no haya solicitudes pendientes que necesiten usar el valor de devolución de llamada anterior. Sin embargo, el cambio de la función de devolución de llamada en un identificador no cambia las devoluciones de llamada en identificadores derivados, como los devueltos por WinHttpConnect. Debe cambiar la función de devolución de llamada en cada nivel.
Muchas funciones winHTTP realizan varias operaciones en la red. Cada operación puede tardar tiempo en completarse y cada una puede producir un error.
Después de iniciar la función WinHttpSetStatusCallback , se puede acceder a la función de devolución de llamada desde WinHTTP para supervisar las operaciones de red que consumen mucho tiempo.
Al final del procesamiento asincrónico, la aplicación puede establecer la función de devolución de llamada en NULL. Esto impide que la aplicación cliente reciba notificaciones adicionales.
El siguiente fragmento de código muestra el método recomendado para establecer la función de devolución de llamada en NULL.
WinHttpSetStatusCallback( hOpen,
NULL,
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS,
NULL );
Sin embargo, tenga en cuenta que WinHTTP no sincroniza WinHttpSetStatusCallback con subprocesos de trabajo. Si una devolución de llamada que se origina en otro subproceso está en curso cuando una aplicación llama a WinHttpSetStatusCallback, la aplicación sigue recibiendo una notificación de devolución de llamada incluso después de que WinHttpSetStatusCallback establezca correctamente la función de devolución de llamada en NULL y devuelve.
Ejemplos
En el ejemplo siguiente se muestra cómo instalar una función de devolución de llamada para funciones WinHTTP asincrónicas. En el ejemplo se supone que se ha implementado previamente una función WINHTTP_STATUS_CALLBACK denominada "AsyncCallback( )":
// Use WinHttpOpen to obtain an HINTERNET handle.
HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0",
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
WINHTTP_NO_PROXY_NAME,
WINHTTP_NO_PROXY_BYPASS, 0);
if (hSession)
{
// Install the status callback function.
WINHTTP_STATUS_CALLBACK isCallback = WinHttpSetStatusCallback( hSession,
(WINHTTP_STATUS_CALLBACK)AsyncCallback,
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS,
NULL);
// Place additional code here.
// When finished, release the HINTERNET handle.
WinHttpCloseHandle(hSession);
}
else
{
printf("Error %u in WinHttpOpen.\n", GetLastError());
}
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. |