HandlerRoutine コールバック関数

SetConsoleCtrlHandler 関数で使用されるアプリケーション定義関数。 コンソール プロセスでは、この関数を使用して、プロセスによって受信されたコントロール 信号を処理します。 信号を受信すると、システムは、関数を実行する新しいスレッドをプロセス内に作成します。

PHANDLER_ROUTINE タイプは、このコールバック関数へのポインターを定義します。 HandlerRoutine は、アプリケーション定義関数名のプレースホルダーです。

構文

BOOL WINAPI HandlerRoutine(
  _In_ DWORD dwCtrlType
);

パラメーター

dwCtrlType [in]
ハンドラーによって受信されるコントロール信号の種類。 このパラメーターには、次の値のいずれかを指定できます。

戻り値

この関数がコントロール信号を処理する場合は、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 は、アプリケーションのコンソール コントロール ハンドラーをインストールできることに注意してください。 その場合、このハンドラーはデフォルトのハンドラーをオーバーライドし、ユーザーがログオフしたときにアプリケーションが終了する可能性があります。

タイムアウト

[1]:「クイック」イベントは使用されませんが、それらをサポートするコードはまだあります。

要件

関連項目

コンソールのコントロール ハンドラー

コンソール関数

ExitProcess

GenerateConsoleCtrlEvent

GetProcessShutdownParameters

SetConsoleCtrlHandler

SetProcessShutdownParameters