HandlerRoutine 回调函数
与 SetConsoleCtrlHandler 函数一起使用的应用程序定义的函数。 控制台进程使用此函数来处理由进程接收的控制信号。 收到信号后,系统会在进程中创建一个新线程来执行该函数。
PHANDLER_ROUTINE类型定义指向此回调函数的指针。 HandlerRoutine 是应用程序定义的函数名称的占位符。
语法
BOOL WINAPI HandlerRoutine(
_In_ DWORD dwCtrlType
);
参数
dwCtrlType [in]
处理程序收到的控制信号的类型。 此参数的取值可为下列值之一:
值 | 含义 |
---|---|
CTRL_C_EVENT 0 | 从键盘输入或从GenerateConsoleCtrlEvent函数生成的信号接收到了CTRL+C信号。 |
CTRL_BREAK_EVENT 1 | 从键盘输入或由GenerateConsoleCtrlEvent生成的信号接收到CTRL+BREAK信号。 |
CTRL_CLOSE_EVENT 2 | 当用户关闭控制台时,系统会向附加到控制台的所有进程发送信号, (方法是:单击控制台窗口的窗口菜单上的 " 关闭 " 或单击 "任务管理器") 中的 " 结束任务 " 按钮命令。 |
CTRL_LOGOFF_EVENT 5 | 当用户注销时系统发送给所有控制台进程的信号。 此信号不指示哪个用户正在注销,因此不能进行假设。 请注意,此信号仅由服务接收。 交互式应用程序将在注销时终止,因此当系统发送此信号时,它们不会出现。 |
CTRL_SHUTDOWN_EVENT 6 | 系统关闭时系统发送的信号。 系统发送此信号时不会出现交互式应用程序,因此,在这种情况下,只能接收到服务。 服务还具有用于关闭事件的自己的通知机制。 有关详细信息,请参阅 处理程序。 此信号也可由使用 GenerateConsoleCtrlEvent的应用程序生成。 |
返回值
如果函数处理控制信号,则它应返回 TRUE。 如果它返回 FALSE,则使用此进程的处理程序列表中的下一个处理程序函数。
备注
因为系统会在进程中创建一个新线程来执行处理程序函数,所以,进程中的另一个线程可能会终止处理程序函数。 请确保将进程中的线程与处理程序函数的线程同步。
每个控制台进程都有其自己的 HandlerRoutine 函数列表。 最初,此列表仅包含调用 ExitProcess的默认处理程序函数。 控制台进程通过调用 SetConsoleCtrlHandler 函数来添加或移除其他处理程序函数,这不会影响其他进程的处理函数列表。 当控制台进程接收到任何控制信号时,将在最后一个注册的基础上调用其处理程序函数,直到其中一个处理程序返回 TRUE。 如果所有处理程序均未返回 TRUE,则调用默认处理程序。
CTRL_CLOSE_EVENT、 CTRL_LOGOFF_EVENT和CTRL_SHUTDOWN_EVENT信号使进程有机会在终止之前进行清理。 HandlerRoutine可以执行任何必要的清理,然后执行下列操作之一:
- 调用 ExitProcess 函数以终止进程。
- 返回 FALSE。 如果任何注册的处理程序函数都未返回 TRUE,则默认处理程序将终止进程。
- 返回 TRUE。 在这种情况下,将不会调用其他处理程序函数,并且系统将终止进程。
进程可以使用 SetProcessShutdownParameters 函数来阻止系统在注销或关闭过程中向用户显示对话框。 在这种情况下,当 HandlerRoutine 返回 TRUE 或超时期限结束时,系统将终止进程。
当控制台应用程序作为服务运行时,它将收到修改后的默认控制台控制处理程序。 处理CTRL_LOGOFF_EVENT和CTRL_SHUTDOWN_EVENT信号时,此修改后的处理程序不会调用ExitProcess 。 这样,在用户注销后,服务将继续运行。 如果服务安装自己的控制台控制处理程序,则在默认处理程序之前调用此处理程序。 如果安装的处理程序在处理CTRL_LOGOFF_EVENT信号时调用ExitProcess ,则在用户注销时,服务将退出。
请注意,第三方库或 DLL 可为应用程序安装控制台控制处理程序。 如果是这样,此处理程序将重写默认处理程序,并可能导致应用程序在用户注销时退出。
超时
事件 | 环境 | 超时 |
---|---|---|
CTRL_CLOSE_EVENT |
任意 | system 参数 SPI_GETHUNGAPPTIMEOUT ,5000 ms |
CTRL_LOGOFF_EVENT |
quick[1] | 注册表项 CriticalAppShutdownTimeout 或500毫秒 |
CTRL_LOGOFF_EVENT |
以上都不是 | system 参数 SPI_GETWAITTOKILLTIMEOUT ,5000 ms |
CTRL_SHUTDOWN_EVENT |
服务进程 | system 参数 SPI_GETWAITTOKILLSERVICETIMEOUT ,20000ms |
CTRL_SHUTDOWN_EVENT |
quick[1] | 注册表项 CriticalAppShutdownTimeout 或500毫秒 |
CTRL_SHUTDOWN_EVENT |
以上都不是 | system 参数 SPI_GETWAITTOKILLTIMEOUT ,5000 ms |
CTRL_C , CTRL_BREAK |
任意 | 无超时 |
[1]:从未使用 "快速" 事件,但仍有代码支持它们。
要求
最低受支持的客户端 | Windows 2000 Professional [仅限桌面应用] |
最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
标头 | ConsoleApi.h (via WinCon.h, include Windows.h) |