HandlerRoutine callback function
An application-defined function used with the SetConsoleCtrlHandler function. A console process uses this function to handle control signals received by the process. When the signal is received, the system creates a new thread in the process to execute the function.
The PHANDLER_ROUTINE type defines a pointer to this callback function. HandlerRoutine is a placeholder for the application-defined function name.
Syntax
BOOL WINAPI HandlerRoutine(
_In_ DWORD dwCtrlType
);
Parameters
dwCtrlType [in]
The type of control signal received by the handler. This parameter can be one of the following values.
| Value | Meaning |
|---|---|
| CTRL_C_EVENT 0 | A CTRL+C signal was received, either from keyboard input or from a signal generated by the GenerateConsoleCtrlEvent function. |
| CTRL_BREAK_EVENT 1 | A CTRL+BREAK signal was received, either from keyboard input or from a signal generated by GenerateConsoleCtrlEvent. |
| CTRL_CLOSE_EVENT 2 | A signal that the system sends to all processes attached to a console when the user closes the console (either by clicking Close on the console window's window menu, or by clicking the End Task button command from Task Manager). |
| CTRL_LOGOFF_EVENT 5 | A signal that the system sends to all console processes when a user is logging off. This signal does not indicate which user is logging off, so no assumptions can be made. Note that this signal is received only by services. Interactive applications are terminated at logoff, so they are not present when the system sends this signal. |
| CTRL_SHUTDOWN_EVENT 6 | A signal that the system sends when the system is shutting down. Interactive applications are not present by the time the system sends this signal, therefore it can be received only be services in this situation. Services also have their own notification mechanism for shutdown events. For more information, see Handler. |
Return value
If the function handles the control signal, it should return TRUE. If it returns FALSE, the next handler function in the list of handlers for this process is used.
Remarks
Because the system creates a new thread in the process to execute the handler function, it is possible that the handler function will be terminated by another thread in the process. Be sure to synchronize threads in the process with the thread for the handler function.
Each console process has its own list of HandlerRoutine functions. Initially, this list contains only a default handler function that calls ExitProcess. A console process adds or removes additional handler functions by calling the SetConsoleCtrlHandler function, which does not affect the list of handler functions for other processes. When a console process receives any of the control signals, its handler functions are called on a last-registered, first-called basis until one of the handlers returns TRUE. If none of the handlers returns TRUE, the default handler is called.
The CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and CTRL_SHUTDOWN_EVENT signals give the process an opportunity to clean up before termination. A HandlerRoutine can perform any necessary cleanup, then take one of the following actions:
- Call the ExitProcess function to terminate the process.
- Return FALSE. If none of the registered handler functions returns TRUE, the default handler terminates the process.
- Return TRUE. In this case, no other handler functions are called and the system terminates the process.
A process can use the SetProcessShutdownParameters function to prevent the system from displaying a dialog box to the user during logoff or shutdown. In this case, the system terminates the process when HandlerRoutine returns TRUE or when the time-out period elapses.
When a console application is run as a service, it receives a modified default console control handler. This modified handler does not call ExitProcess when processing the CTRL_LOGOFF_EVENT and CTRL_SHUTDOWN_EVENT signals. This allows the service to continue running after the user logs off. If the service installs its own console control handler, this handler is called before the default handler. If the installed handler calls ExitProcess when processing the CTRL_LOGOFF_EVENT signal, the service exits when the user logs off.
Note that a third-party library or DLL can install a console control handler for your application. If it does, this handler overrides the default handler, and can cause the application to exit when the user logs off.
Timeouts
| Event | Circumstances | Timeout |
|---|---|---|
CTRL_CLOSE_EVENT |
any | system parameter SPI_GETHUNGAPPTIMEOUT, 5000ms |
CTRL_LOGOFF_EVENT |
quick[1] | registry key CriticalAppShutdownTimeout or 500ms |
CTRL_LOGOFF_EVENT |
none of the above | system parameter SPI_GETWAITTOKILLTIMEOUT, 5000ms |
CTRL_SHUTDOWN_EVENT |
service process | system parameter SPI_GETWAITTOKILLSERVICETIMEOUT, 20000ms |
CTRL_SHUTDOWN_EVENT |
quick[1] | registry key CriticalAppShutdownTimeout or 500ms |
CTRL_SHUTDOWN_EVENT |
none of the above | system parameter SPI_GETWAITTOKILLTIMEOUT, 5000ms |
CTRL_C, CTRL_BREAK |
any | no timeout |
[1]: "quick" events are never used, but there's still code to support them.
Requirements
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Header | ConsoleApi.h (via WinCon.h, include Windows.h) |