WINHTTP_STATUS_CALLBACK función de devolución de llamada (winhttp.h)
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 establecer una conexión segura (HTTPS) al servidor. El parámetro lpvStatusInformation contiene un puntero a un DWORD que es una combinación or bit a bit de valores de error. 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.
[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 segura para subprocesos y reentrantar porque se puede llamar en otro subproceso para una solicitud independiente y volver a escribir en el mismo subproceso para la solicitud actual. Por lo tanto, se debe codificar 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 de 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 solo 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 en 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 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.
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. |