Función de devolución de llamada HandlerRoutine
Función definida por la aplicación que se utiliza con la función SetConsoleCtrlHandler. Un proceso de consola puede utilizar esta función para controlar las señales de control que recibe. Cuando se recibe la señal, el sistema crea un nuevo subproceso en el proceso para ejecutar la función.
El tipo PHANDLER_ROUTINE define un puntero a esta función de devolución de llamada. HandlerRoutine es un marcador de posición para el nombre de función definido por la aplicación.
Sintaxis
BOOL WINAPI HandlerRoutine(
_In_ DWORD dwCtrlType
);
Parámetros
dwCtrlType [in]
Tipo de señal de control que recibe el controlador. Este parámetro puede ser uno de los valores siguientes.
| Valor | Significado |
|---|---|
| CTRL_C_EVENT 0 | Se recibió una señal CTRL+C, ya sea desde la entrada de teclado o desde una señal que genera la función GenerateConsoleCtrlEvent. |
| CTRL_BREAK_EVENT 1 | Se recibió una señal CTRL+BREAK, ya sea desde la entrada de teclado o desde una señal que genera GenerateConsoleCtrlEvent. |
| CTRL_CLOSE_EVENT 2 | Señal que el sistema envía a todos los procesos asociados a una consola cuando el usuario la cierra (ya sea haciendo clic en Cerrar en el menú de la ventana de la consola o en el comando del botón Finalizar tarea del Administrador de tareas). |
| CTRL_LOGOFF_EVENT 5 | Señal que el sistema envía a todos los procesos de consola cuando un usuario cierra sesión. Esta señal no indica qué usuario cierra sesión, por lo que no se pueden realizar hipótesis al respecto. Tenga en cuenta que esta señal solo la reciben los servicios. Las aplicaciones interactivas dejan de ejecutarse al cerrar sesión y no están presentes cuando el sistema envía esta señal. |
| CTRL_SHUTDOWN_EVENT 6 | Señal que envía el sistema cuando se apaga. Las aplicaciones interactivas no están presentes en el momento en que el sistema envía esta señal, por lo que solo la pueden recibir los servicios. Los servicios también tienen su propio mecanismo de notificación para los eventos de apagado. Para obtener más información, consulte Handler. |
Valor devuelto
Si la función controla la señal de control, debe devolver TRUE. Si devuelve FALSE, se utiliza la siguiente función de controlador de la lista de controladores para este proceso.
Comentarios
Dado que el sistema crea un nuevo subproceso en el proceso para ejecutar la función de controlador, es posible que otro subproceso del proceso finalice esta función. Asegúrese de sincronizar los subprocesos del proceso con el subproceso de la función de controlador.
Cada proceso de consola tiene su propia lista de funciones HandlerRoutine. Inicialmente, esta lista solo contiene una función de controlador predeterminada que llama a ExitProcess. Un proceso de consola agrega o quita funciones de controlador adicionales mediante una llamada a la función SetConsoleCtrlHandler, que no afecta a la lista de funciones de controlador para otros procesos. Cuando un proceso de consola recibe alguna de las señales de control, se llama a sus funciones de controlador empezando por las últimas registradas, hasta que uno de los controladores devuelve TRUE. Si ninguno de los controladores devuelve TRUE, se llama al controlador predeterminado.
Las señales CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT y CTRL_SHUTDOWN_EVENT ofrecen al proceso la oportunidad de limpiar antes de finalizar. HandlerRoutine puede realizar cualquier limpieza necesaria y, a continuación, efectuar una de las siguientes acciones:
- Llamar a la función ExitProcess para finalizar el proceso.
- Devolver FALSE. Si ninguna de las funciones de controlador registradas devuelve TRUE, el controlador predeterminado finaliza el proceso.
- Devolver TRUE. En este caso, no se llama a ninguna otra función de controlador y el sistema finaliza el proceso.
Un proceso puede utilizar la función SetProcessShutdownParameters para evitar que el sistema muestre un cuadro de diálogo al usuario durante el cierre de sesión o el apagado. En este caso, el sistema finaliza el proceso cuando HandlerRoutine devuelve TRUE o si se agota el tiempo de espera.
Cuando se ejecuta una aplicación de consola como servicio, recibe un controlador de control de consola predeterminado modificado. Este controlador modificado no llama a ExitProcess al procesar las señales CTRL_LOGOFF_EVENT y CTRL_SHUTDOWN_EVENT. Esto permite que el servicio continúe ejecutándose después de que el usuario cierre sesión. Si el servicio instala su propio controlador de control de consola, se llama a este controlador antes que al predeterminado. Si el controlador instalado llama a ExitProcess al procesar la señal CTRL_LOGOFF_EVENT, el servicio se cierra cuando el usuario cierra sesión.
Tenga en cuenta que una DLL o una biblioteca de terceros puede instalar un controlador de control de consola para la aplicación. En este caso, este controlador invalida el controlador predeterminado y es posible que la aplicación se cierre cuando el usuario cierre sesión.
Tiempos de espera
| Evento | Circunstancias | Tiempo de espera |
|---|---|---|
CTRL_CLOSE_EVENT |
cualquiera | parámetro del sistema SPI_GETHUNGAPPTIMEOUT, 5000 ms |
CTRL_LOGOFF_EVENT |
rápido(1) | clave del Registro CriticalAppShutdownTimeout o 500 ms |
CTRL_LOGOFF_EVENT |
ninguna de las anteriores | parámetro del sistema SPI_GETWAITTOKILLTIMEOUT, 5000 ms |
CTRL_SHUTDOWN_EVENT |
proceso de servicio | parámetro del sistema SPI_GETWAITTOKILLSERVICETIMEOUT, 20 000 ms |
CTRL_SHUTDOWN_EVENT |
rápido(1) | clave del Registro CriticalAppShutdownTimeout o 500 ms |
CTRL_SHUTDOWN_EVENT |
ninguna de las anteriores | parámetro del sistema SPI_GETWAITTOKILLTIMEOUT, 5000 ms |
CTRL_C, CTRL_BREAK |
cualquiera | sin tiempo de espera |
(1): los eventos "rápidos" nunca se utilizan, pero sigue habiendo código que los admite.
Requisitos
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Encabezado | ConsoleApi.h (a través de WinCon.h, incluido Windows.h) |