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_EVENTCTRL_LOGOFF_EVENTCTRL_SHUTDOWN_EVENT信号使进程有机会在终止之前进行清理。 HandlerRoutine可以执行任何必要的清理,然后执行下列操作之一:

  • 调用 ExitProcess 函数以终止进程。
  • 返回 FALSE。 如果任何注册的处理程序函数都未返回 TRUE,则默认处理程序将终止进程。
  • 返回 TRUE。 在这种情况下,将不会调用其他处理程序函数,并且系统将终止进程。

进程可以使用 SetProcessShutdownParameters 函数来阻止系统在注销或关闭过程中向用户显示对话框。 在这种情况下,当 HandlerRoutine 返回 TRUE 或超时期限结束时,系统将终止进程。

当控制台应用程序作为服务运行时,它将收到修改后的默认控制台控制处理程序。 处理CTRL_LOGOFF_EVENTCTRL_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)

另请参阅

控制台控件处理程序

控制台函数

ExitProcess

GenerateConsoleCtrlEvent

GetProcessShutdownParameters

SetConsoleCtrlHandler

SetProcessShutdownParameters