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 | ユーザーがコンソールを閉じるときに (コンソール ウィンドウのウィンドウ メニューの [Close](閉じる) をクリックするか、タスク マネージャーから [End Task](タスクを修了) ボタン コマンドをクリックして) コンソールにアタッチされているすべてのプロセスにシステムが送信する信号。 |
| CTRL_LOGOFF_EVENT 5 | ユーザーがログオフしているときにシステムがすべてのコンソール プロセスに送信する信号。 この信号は、どのユーザーがログオフするかを示していないため、想定を立てません。 この信号はサービスによってのみ受信されることに注意してください。 対話型アプリケーションはログオフ時に終了するため、システムがこの信号を送信したときには存在しません。 |
| CTRL_SHUTDOWN_EVENT 6 | システムがシャットダウンするときにシステムが送信する信号。 対話型アプリケーションは、システムがこの信号を送信する時点までに存在しないため、この状況ではサービスとしてのみ受信できます。 サービスには、シャットダウン イベントに対する独自の通知メカニズムもあります。 詳細については、「ハンドラー」を参照してください。 |
戻り値
この関数がコントロール信号を処理する場合は、TRUE を返す必要があります。 FALSE を返す場合は、このプロセスのハンドラーのリストで次のハンドラー関数が使用されます。
解説
システムは、ハンドラー関数を実行するプロセスに新しいスレッドを作成するため、ハンドラー関数がプロセス内の別のスレッドによって終了される可能性があります。 必ず、プロセス内のスレッドをハンドラー関数のスレッドと同期してください。
各コンソール プロセスには、HandlerRoutine 関数の独自のリストがあります。 初期状態では、各プロセスのハンドラーの一覧には、ExitProcess 関数を呼び出すデフォルトのハンドラー関数だけが含まれています。 コンソール プロセスによって SetConsoleCtrlHandler 関数が呼び出されてハンドラー関数の追加または削除が行われても、他のプロセスのハンドラー関数の一覧には影響しません。 コンソール プロセスが何らかの制御シグナルを受け取ると、そのハンドラー関数が、最後に登録されたものが最初に呼び出される順序で、いずれかのハンドラーが TRUE を返すまで呼び出されます。 どのハンドラーからも TRUE が返されない場合は、デフォルトのハンドラーが呼び出されます。
CTRL_CLOStandard Edition_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、5000 ミリ秒 |
CTRL_LOGOFF_EVENT |
クイック [1] | レジストリ キー CriticalAppShutdownTimeout または 500 ミリ秒 |
CTRL_LOGOFF_EVENT |
上記のどれでもない | システム パラメーター SPI_GETWAITTOKILLTIMEOUT、5000 ミリ秒 |
CTRL_SHUTDOWN_EVENT |
サービス プロセス | システム パラメーター SPI_GETWAITTOKILLSERVICETIMEOUT、20000 ミリ秒 |
CTRL_SHUTDOWN_EVENT |
クイック [1] | レジストリ キー CriticalAppShutdownTimeout または 500 ミリ秒 |
CTRL_SHUTDOWN_EVENT |
上記のどれでもない | システム パラメーター SPI_GETWAITTOKILLTIMEOUT、5000 ミリ秒 |
CTRL_C, CTRL_BREAK |
任意 | タイムアウトなし |
[1]:「クイック」イベントは使用されませんが、それらをサポートするコードはまだあります。
要件
| サポートされている最小のクライアント | Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
| ヘッダー | ConsoleApi.h (WinCon.h 経由、Windows.h をインクルード) |