閱讀英文

共用方式為


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 當系統關閉時,系統傳送的訊號。 當系統傳送此訊號時,互動式應用程式不存在,因此只能在這種情況中收到服務。 服務也有自己的關機事件通知機制。 如需詳細資訊,請參閱 處理程式

傳回值

如果函式處理控件訊號,它應該會傳回 TRUE。 如果傳回 FALSE,則會使用這個處理程式之處理程式清單中的下一個處理程式函式。

備註

由於系統會在進程中建立新的線程來執行處理程式函式,因此處理程式函式可能會由進程中的另一個線程終止。 請務必將進程中的線程與處理程式函式的線程同步處理。

每個控制台進程都有自己的 HandlerRoutine 函式清單。 一開始,此清單只包含呼叫 ExitProcess 的預設處理程式函式。 主控台程序會藉由呼叫 SetConsoleCtrlHandler 函式來新增或移除其他處理常式函式,而這不會影響其他程序的處理常式函式清單。 當主控台進程收到任何控制訊號時,其處理程式函式會以最後一個註冊且先呼叫的方式呼叫,直到其中一個處理程式傳 回 TRUE 為止。 如果沒有任何處理程式傳 回 TRUE,則會呼叫預設處理程式。

CTRL_CLOSE_EVENT、CTRL_LOGOFF_EVENTCTRL_SHUTDOWN_EVENT訊號讓程式有機會在終止之前清除。 HandlerRoutine 可以執行任何必要的清除,然後採取下列其中一個動作:

  • 呼叫 ExitProcess 函式來終止進程。
  • 傳回 FALSE。 如果已註冊的處理程式函式沒有傳 回 TRUE,預設處理程式就會終止進程。
  • 傳回 TRUE。 在此情況下,不會呼叫其他處理程式函式,而且系統會終止進程。

進程可以使用 SetProcessShutdownParameters 函 式,防止系統在註銷或關機期間向使用者顯示對話方塊。 在此情況下,當 HandlerRoutine 傳回 TRUE 或逾時期間經過時,系統會終止進程。

當主控台應用程式以服務的形式執行時,它會收到已修改的預設控制台控件處理程式。 處理CTRL_LOGOFF_EVENT和CTRL_SHUTDOWN_EVENT訊號時,這個修改過的處理程式不會呼叫 ExitProcess。 這可讓服務在用戶註銷之後繼續執行。 如果服務安裝自己的主控控台控制處理程式,則會在預設處理程式之前呼叫此處理程式。 如果已安裝的處理程式在處理CTRL_LOGOFF_EVENT訊號時呼叫 ExitProcess,服務會在使用者註銷時結束。

請注意,第三方連結庫或 DLL 可以安裝應用程式的控制台控制處理程式。 如果這樣做,此處理程式會覆寫默認處理程式,並可能導致應用程式在使用者註銷時結束。

逾時

Event 情況 下 Timeout
CTRL_CLOSE_EVENT any system 參數 SPI_GETHUNGAPPTIMEOUT, 5000ms
CTRL_LOGOFF_EVENT quick[1] 登錄機碼 CriticalAppShutdownTimeout 或 500 毫秒
CTRL_LOGOFF_EVENT 上述專案均無 system 參數 SPI_GETWAITTOKILLTIMEOUT, 5000ms
CTRL_SHUTDOWN_EVENT 服務進程 system 參數 SPI_GETWAITTOKILLSERVICETIMEOUT, 20000ms
CTRL_SHUTDOWN_EVENT quick[1] 登錄機碼 CriticalAppShutdownTimeout 或 500 毫秒
CTRL_SHUTDOWN_EVENT 上述專案均無 system 參數 SPI_GETWAITTOKILLTIMEOUT, 5000ms
CTRL_C, CTRL_BREAK any 無逾時

[1]: 「快速」事件永遠不會使用,但仍有程式代碼可支援它們。

需求

   
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限傳統型應用程式]
頁首 ConsoleApi.h (透過 WinCon.h,包括 Windows.h)

另請參閱

主控台控制處理常式

主控台函式

ExitProcess

GenerateConsoleCtrlEvent

GetProcessShutdownParameters

SetConsoleCtrlHandler

SetProcessShutdownParameters