HandlerRoutine 回调函数

项目
10/26/2023

与 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	当系统关闭时发送的信号。当系统发送此信号时，交互式应用程序不存在，因此这种情况下只能由服务接收它。服务也有自己的关闭事件通知机制。有关详细信息，请参阅处理程序。

返回值

如果函数处理控制信号，它应返回 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`	任意	系统参数 `SPI_GETHUNGAPPTIMEOUT`，5000ms
`CTRL_LOGOFF_EVENT`	quick[1]	注册表项 `CriticalAppShutdownTimeout` 或 500ms
`CTRL_LOGOFF_EVENT`	以上都不是	系统参数 `SPI_GETWAITTOKILLTIMEOUT`，5000ms
`CTRL_SHUTDOWN_EVENT`	服务进程	系统参数 `SPI_GETWAITTOKILLSERVICETIMEOUT`，20000ms
`CTRL_SHUTDOWN_EVENT`	quick[1]	注册表项 `CriticalAppShutdownTimeout` 或 500ms
`CTRL_SHUTDOWN_EVENT`	以上都不是	系统参数 `SPI_GETWAITTOKILLTIMEOUT`，5000ms
`CTRL_C`, `CTRL_BREAK`	任意	无超时

[1]：永远不会使用 "quick" 事件，但仍有代码支持它们。

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
标头	ConsoleApi.h (via WinCon.h, include Windows.h)