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_EVENT和CTRL_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) |