WINHTTP_STATUS_CALLBACK función de devolución de llamada (winhttp.h)

Artículo
03/15/2023

El tipo de WINHTTP_STATUS_CALLBACK representa una función de devolución de llamada de estado definida por la aplicación.

Sintaxis

WINHTTP_STATUS_CALLBACK WinhttpStatusCallback;

void WinhttpStatusCallback(
  [in] HINTERNET hInternet,
  [in] DWORD_PTR dwContext,
  [in] DWORD dwInternetStatus,
  [in] LPVOID lpvStatusInformation,
  [in] DWORD dwStatusInformationLength
)
{...}

Parámetros

[in] hInternet

Identificador para el que se llama a la función de devolución de llamada.

[in] dwContext

Puntero a un DWORD que especifica el valor de contexto definido por la aplicación asociado al identificador en el parámetro hInternet .

Se puede asignar un valor de contexto a un identificador session, Connect o Request llamando a WinHttpSetOption con la opción WINHTTP_OPTION_CONTEXT_VALUE . Como alternativa, WinHttpSendRequest se puede usar para asociar un valor de contexto a un identificador de solicitud.

[in] dwInternetStatus

Apunta a un DWORD que especifica el código de estado que indica por qué se llama a la función de devolución de llamada. Puede ser uno de los siguientes valores:

WINHTTP_CALLBACK_STATUS_CLOSING_CONNECTION

Cerrando la conexión al servidor. El parámetro lpvStatusInformation es NULL.

WINHTTP_CALLBACK_STATUS_CONNECTED_TO_SERVER

Se ha conectado correctamente al servidor. El parámetro lpvStatusInformation contiene un puntero a un LPWSTR que indica la dirección IP del servidor en notación de puntos.

WINHTTP_CALLBACK_STATUS_CONNECTING_TO_SERVER

Conexión al servidor. El parámetro lpvStatusInformation contiene un puntero a un LPWSTR que indica la dirección IP del servidor en notación de puntos.

WINHTTP_CALLBACK_STATUS_CONNECTION_CLOSED

Se ha cerrado correctamente la conexión al servidor. El parámetro lpvStatusInformation es NULL.

WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE

Los datos están disponibles para recuperarse con WinHttpReadData. El parámetro lpvStatusInformation apunta a un DWORD que contiene el número de bytes de datos disponibles. El propio parámetro dwStatusInformationLength es 4 (el tamaño de un DWORD).

WINHTTP_CALLBACK_STATUS_HANDLE_CREATED

Se ha creado un identificador HINTERNET . El parámetro lpvStatusInformation contiene un puntero al identificador HINTERNET .

WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING

Este valor de identificador se ha terminado. El parámetro lpvStatusInformation contiene un puntero al identificador HINTERNET . No habrá más devoluciones de llamada para este identificador.

WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE

Se ha recibido el encabezado de respuesta y está disponible con WinHttpQueryHeaders. El parámetro lpvStatusInformation es NULL.

WINHTTP_CALLBACK_STATUS_INTERMEDIATE_RESPONSE

Recibió un mensaje de código de estado intermedio (100 niveles) del servidor. El parámetro lpvStatusInformation contiene un puntero a un DWORD que indica el código de estado.

WINHTTP_CALLBACK_STATUS_NAME_RESOLVED

Encontró correctamente la dirección IP del servidor. El parámetro lpvStatusInformation contiene un puntero a un LPWSTR que indica el nombre que se resolvió.

WINHTTP_CALLBACK_STATUS_READ_COMPLETE

Los datos se leyeron correctamente desde el servidor. El parámetro lpvStatusInformation contiene un puntero al búfer especificado en la llamada a WinHttpReadData. El parámetro dwStatusInformationLength contiene el número de bytes leídos.

Cuando se usa en WinHttpWebSocketReceive, el parámetro lpvStatusInformation contiene un puntero a una estructura WINHTTP_WEB_SOCKET_STATUS y el parámetro dwStatusInformationLength indica el tamaño de lpvStatusInformation.

WINHTTP_CALLBACK_STATUS_RECEIVING_RESPONSE

Esperando que el servidor responda a una solicitud. El parámetro lpvStatusInformation es NULL.

WINHTTP_CALLBACK_STATUS_REDIRECT

Una solicitud HTTP está a punto de redirigir automáticamente la solicitud. El parámetro lpvStatusInformation contiene un puntero a un LPWSTR que indica la nueva dirección URL. En este momento, la aplicación puede leer los datos devueltos por el servidor con la respuesta de redireccionamiento y puede consultar los encabezados de respuesta. También puede cancelar la operación cerrando el identificador.

WINHTTP_CALLBACK_STATUS_REQUEST_ERROR

Error al enviar una solicitud HTTP. El parámetro lpvStatusInformation contiene un puntero a una estructura de WINHTTP_ASYNC_RESULT . Su miembro dwResult indica el identificador de la función llamada y dwError indica el valor devuelto.

WINHTTP_CALLBACK_STATUS_REQUEST_SENT

Se ha enviado correctamente la solicitud de información al servidor. El parámetro lpvStatusInformation contiene un puntero a un DWORD que indica el número de bytes enviados.

WINHTTP_CALLBACK_STATUS_RESOLVING_NAME

Buscar la dirección IP de un nombre de servidor. El parámetro lpvStatusInformation contiene un puntero al nombre del servidor que se va a resolver.

WINHTTP_CALLBACK_STATUS_RESPONSE_RECEIVED

Se recibió correctamente una respuesta del servidor. El parámetro lpvStatusInformation contiene un puntero a un DWORD que indica el número de bytes recibidos.

WINHTTP_CALLBACK_STATUS_SECURE_FAILURE

Se encontraron uno o más errores al recuperar un certificado de Capa de sockets seguros (SSL) del servidor. El parámetro lpvStatusInformation contiene una marca. Para obtener más información, vea la descripción de lpvStatusInformation.

WINHTTP_CALLBACK_STATUS_SENDING_REQUEST

Enviando la solicitud de información al servidor. El parámetro lpvStatusInformation es NULL.

WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE

La solicitud se completó correctamente. El parámetro lpvStatusInformation es el valor lpOptional pasado a WinHttpSendRequest (el cuerpo de la solicitud inicial) y el parámetro dwStatusInformationLength indica el número de bytes de cuerpo iniciales escritos correctamente (el valor dwOptionalLength pasado a WinHttpSendRequest).

WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE

Los datos se escribieron correctamente en el servidor. El parámetro lpvStatusInformation contiene un puntero a un DWORD que indica el número de bytes escritos.

Cuando se usa en WinHttpWebSocketSend, el parámetro lpvStatusInformation contiene un puntero a una estructura WINHTTP_WEB_SOCKET_STATUS y el parámetro dwStatusInformationLength indica el tamaño de lpvStatusInformation.

WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE

La operación iniciada por una llamada a WinHttpGetProxyForUrlEx está completa. Los datos están disponibles para recuperarse con WinHttpReadData.

WINHTTP_CALLBACK_STATUS_CLOSE_COMPLETE

La conexión se cerró correctamente a través de una llamada a WinHttpWebSocketClose. El parámetro lpvStatusInformation es NULL.

WINHTTP_CALLBACK_STATUS_SHUTDOWN_COMPLETE

La conexión se cerró correctamente a través de una llamada a WinHttpWebSocketShutdown. El parámetro lpvStatusInformation es NULL.

[in] lpvStatusInformation

Puntero a un búfer que especifica información pertinente para esta llamada a la función de devolución de llamada. El formato de estos datos depende del valor del argumento dwInternetStatus . Para obtener más información, vea dwInternetStatus.

Si el argumento dwInternetStatus es WINHTTP_CALLBACK_STATUS_SECURE_FAILURE, lpvStatusInformation apunta a un DWORD que es una combinación or bit a bit de uno o varios de los valores siguientes.

Valor	Significado
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REV_FAILED	Se ha habilitado la comprobación de revocación de certificación, pero la comprobación de revocación no pudo comprobar si se ha revocado un certificado. Es posible que el servidor usado para comprobar la revocación no sea accesible.
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CERT	El certificado SSL no es válido.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_REVOKED	Se revoca el certificado SSL.
WINHTTP_CALLBACK_STATUS_FLAG_INVALID_CA	La función no está familiarizado con la entidad de certificación que generó el certificado del servidor.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_CN_INVALID	El nombre común del certificado SSL (campo nombre de host) es incorrecto, por ejemplo, si escribió www.microsoft.com y el nombre común en el certificado indica www.msn.com.
WINHTTP_CALLBACK_STATUS_FLAG_CERT_DATE_INVALID	La fecha del certificado SSL que se recibió del servidor es incorrecta. El certificado ha expirado.
WINHTTP_CALLBACK_STATUS_FLAG_SECURITY_CHANNEL_ERROR	La aplicación experimentó un error interno al cargar las bibliotecas SSL.

[in] dwStatusInformationLength

WINHTTP_CALLBACK_STATUS_REDIRECT devoluciones de llamada de estado proporcionan un valor dwStatusInformationLength que corresponde al recuento de caracteres del LPWSTR al que apunta lpvStatusInformation.

Valor devuelto

None

Observaciones

La función de devolución de llamada debe ser threadsafe y reentrant porque se puede llamar a en otro subproceso para una solicitud independiente y volver a escribir en el mismo subproceso para la solicitud actual. Por lo tanto, debe codificarse para controlar la reentrada de forma segura mientras se procesa. Cuando el parámetro dwInternetStatus es igual a WINHTTP_CALLBACK_STATUS_HANDLE_CLOSING, la devolución de llamada no necesita poder controlar la reentrada de la misma solicitud, ya que se garantiza que esta devolución de llamada es la última y no se produce cuando se controlan otros mensajes para esta solicitud.

La función de devolución de llamada de estado recibe actualizaciones sobre el estado de las operaciones asincrónicas mediante marcas de notificación. Las notificaciones que indican que se ha completado una operación determinada se denominan notificaciones de finalización o simplemente finalizaciones. En la tabla siguiente se enumeran las seis marcas de finalización y la función correspondiente que se completa cuando se recibe esta marca.

Marca de finalización	Función
WINHTTP_CALLBACK_STATUS_DATA_AVAILABLE	WinHttpQueryDataAvailable
WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE	WinHttpReceiveResponse
WINHTTP_CALLBACK_STATUS_READ_COMPLETE	WinHttpReadData
WINHTTP_CALLBACK_STATUS_SENDREQUEST_COMPLETE	WinHttpSendRequest
WINHTTP_CALLBACK_STATUS_WRITE_COMPLETE	WinHttpWriteData
WINHTTP_CALLBACK_STATUS_REQUEST_ERROR	Cualquiera de las funciones anteriores cuando se produce un error.

Dado que las devoluciones de llamada se realizan durante el procesamiento de la solicitud, la aplicación debe dedicar el menor tiempo posible a la función de devolución de llamada para evitar degradar el rendimiento de los datos en la red. Por ejemplo, mostrar un cuadro de diálogo en una función de devolución de llamada puede ser una operación tan larga que el servidor finaliza la solicitud.

Se puede llamar a la función de devolución de llamada en un contexto de subproceso diferente del subproceso que inició la solicitud.

Del mismo modo, no hay ninguna afinidad de subproceso de devolución de llamada al llamar a WinHttp de forma asincrónica: una llamada podría iniciarse desde un subproceso, pero cualquier otro subproceso puede recibir la devolución de llamada.

Nota Para obtener más información sobre la implementación en Windows XP y Windows 2000, consulta Requisitos en tiempo de ejecución.

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
Redistribuible	WinHTTP 5.0 e Internet Explorer 5.01 o posterior en Windows XP y Windows 2000.

Consulte también

Versiones winHTTP

WinHttpSetStatusCallback