Función WinHttpSetStatusCallback (winhttp.h)

Artículo
03/15/2023

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
WINHTTP_CALLBACK_FLAG_ALL_COMPLETIONS	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.
WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS	Se activa tras cualquier notificación de cambio de estado, incluidas las finalizaciones. Consulte WINHTTP_STATUS_CALLBACK para obtener una lista de notificaciones.
WINHTTP_CALLBACK_FLAG_RESOLVE_NAME	Se activa al comenzar y completar la resolución de nombres.
WINHTTP_CALLBACK_FLAG_CONNECT_TO_SERVER	Se activa al comenzar y completar la conexión con el servidor.
WINHTTP_CALLBACK_FLAG_DETECTING_PROXY	Se activa al detectar el servidor proxy.
WINHTTP_CALLBACK_FLAG_DATA_AVAILABLE	Se activa al completar una consulta de datos.
WINHTTP_CALLBACK_FLAG_HEADERS_AVAILABLE	Se activa cuando los encabezados de respuesta están disponibles para su recuperación.
WINHTTP_CALLBACK_FLAG_READ_COMPLETE	Se activa tras la finalización de una operación de lectura de datos.
WINHTTP_CALLBACK_FLAG_REQUEST_ERROR	Se activa cuando se produce un error asincrónico.
WINHTTP_CALLBACK_FLAG_SEND_REQUEST	Se activa al comenzar y completar el envío de un encabezado de solicitud con WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_SENDREQUEST_COMPLETE	Se activa cuando se ha enviado un encabezado de solicitud con WinHttpSendRequest.
WINHTTP_CALLBACK_FLAG_WRITE_COMPLETE	Se activa tras la finalización de una operación de publicación de datos.
WINHTTP_CALLBACK_FLAG_RECEIVE_RESPONSE	Se activa al comenzar y completar la recepción de un recurso desde el servidor HTTP.
WINHTTP_CALLBACK_FLAG_CLOSE_CONNECTION	Se activa al comenzar y completar el cierre de una conexión HTTP.
WINHTTP_CALLBACK_FLAG_HANDLES	Se activa cuando se crea o cierra un identificador HINTERNET .
WINHTTP_CALLBACK_FLAG_REDIRECT	Se activa cuando se redirige la solicitud.
WINHTTP_CALLBACK_FLAG_INTERMEDIATE_RESPONSE	Se activa al recibir un mensaje de código de estado intermedio (100 niveles) del servidor.
WINHTTP_CALLBACK_FLAG_SECURE_FAILURE	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
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_NOT_ENOUGH_MEMORY	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.

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