SetConsoleCtrlHandler

呼び出し側プロセスのハンドラ関数リストに、アプリケーション定義の HandlerRoutine 関数を追加または削除する。

SetConsoleCtrlHandler HandlerRoutine, Add

HandlerRoutine : [int] 追加または削除するアプリケーション定義の [**HandlerRoutine**](handlerroutine.md) 関数へのポインタ。このパラメータは **NULL** でもよい。
Add : [int] このパラメータが **TRUE** の場合ハンドラが追加され、**FALSE** の場合は削除される。*HandlerRoutine* パラメータが **NULL** の場合、**TRUE** 値は呼び出し側プロセスに CTRL+C 入力を無視させ、**FALSE** 値は CTRL+C 入力の通常処理を復元する。CTRL+C を無視または処理するこの属性は子プロセスに継承される。

(プラグイン / モジュール : kernel32.dll)

解説

呼び出し側プロセスのハンドラ関数リストに、アプリケーション定義の HandlerRoutine 関数を追加または削除する。

[戻り値]
関数が成功した場合、戻り値は非ゼロである。失敗した場合はゼロである。拡張エラー情報を取得するには
[**GetLastError**](/windows/win32/api/errhandlingapi/nf-errhandlingapi-getlasterror)
を呼び出す。

[備考]
この関数は、メッセージポンプを持つグラフィカルアプリケーションに対して
[**WM\_QUERYENDSESSION**](/windows/win32/shutdown/wm-queryendsession)
が提供するものに類似する通知を、コンソールアプリケーションおよびサービスに提供する。グラフィカルアプリケーションからこの関数を使うこともできるが、**WM\_QUERYENDSESSION**
からの通知より先に届く保証はない。各コンソールプロセスは、CTRL+C および CTRL+BREAK
シグナルを処理するアプリケーション定義 [**HandlerRoutine**](handlerroutine.md)
関数の独自リストを持つ。これらのハンドラはユーザーがコンソールを閉じた、ログオフした、システムをシャットダウンした際にシステムが生成するシグナルも処理する。初期状態では、各プロセスのハンドラリストには
[**ExitProcess**](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitprocess)
を呼び出す既定ハンドラのみが登録されている。コンソールプロセスは **SetConsoleCtrlHandler**
を呼び出すことで追加のハンドラを追加・削除でき、他プロセスのハンドラリストには影響しない。コンソールプロセスが制御シグナルを受信すると、そのハンドラ関数は最後に登録されたものから順に呼び出され、いずれかが
`TRUE` を返すまで続く。どのハンドラも `TRUE`
を返さない場合は既定ハンドラが呼ばれる。[**AttachConsole**](attachconsole.md)、[**AllocConsole**](allocconsole.md)、[**FreeConsole**](freeconsole.md)
を呼び出すと、クライアントプロセスの制御ハンドラテーブルが初期状態に戻る。アタッチされたコンソールセッションが変わった際にはハンドラを再登録する必要がある。コンソールプロセスでは
CTRL+C と CTRL+BREAK の組合せは通常シグナル (**CTRL\_C\_EVENT** と
**CTRL\_BREAK\_EVENT**) として扱われる。キーボードフォーカスを持つコンソールウィンドウで CTRL+C または
CTRL+BREAK を受信すると、シグナルはそのコンソールを共有する全プロセスに渡される。CTRL+BREAK
は常にシグナルとして扱われるが、CTRL+C の典型的な動作は次の 3 つの方法で変更でき、その場合ハンドラ関数は呼び出されない: -
[**SetConsoleMode**](setconsolemode.md) 関数でコンソール入力バッファの
**ENABLE\_PROCESSED\_INPUT** モードを無効にすれば、CTRL+C
はシグナルではなくキーボード入力として報告される。- **SetConsoleCtrlHandler** を **NULL** と
**TRUE** の引数で呼び出すと、呼び出し側プロセスは CTRL+C
シグナルを無視するようになる。この属性は子プロセスに継承されるが、既存プロセスに影響せずに任意のプロセスで有効化・無効化できる。-
CTRL+C シグナルが無効化されておらず、かつコンソールプロセスがデバッグ中の場合、システムは **DBG\_CONTROL\_C**
例外を発生させる。この例外はデバッガのためだけに発生するものであり、アプリケーションは例外ハンドラで処理してはならない。デバッガが例外を処理した場合、アプリケーションは
CTRL+C に気づかない (ただし、警告可能な待機は終了する)。デバッガが例外を未処理のまま渡した場合、CTRL+C
はコンソールプロセスに渡され前述のようにシグナルとして扱われる。コンソールプロセスは
[**GenerateConsoleCtrlEvent**](generateconsolectrlevent.md) を使って
CTRL+C/CTRL+BREAK
シグナルをコンソールプロセスグループに送信できる。ユーザーがコンソールを閉じた、ログオフした、システムをシャットダウンした際、システムは
**CTRL\_CLOSE\_EVENT**、**CTRL\_LOGOFF\_EVENT**、**CTRL\_SHUTDOWN\_EVENT**
シグナルを生成し、プロセスが終了前にクリーンアップする機会を与える。これら 3
つのシグナル処理中は、コンソール関数やコンソール関数を呼び出す C
ランタイム関数は信頼できる動作をしない可能性がある。内部のコンソールクリーンアップルーチンの一部または全部が、プロセスのシグナルハンドラ実行前に呼び出されているためである。**Windows
7/8/8.1/10:** コンソールアプリケーションが gdi32.dll または user32.dll
をロードしている場合、**SetConsoleCtrlHandler** で指定した
[**HandlerRoutine**](handlerroutine.md) は **CTRL\_LOGOFF\_EVENT** と
**CTRL\_SHUTDOWN\_EVENT** に対して呼び出されない。OS は gdi32.dll/user32.dll
をロードするプロセスをコンソールアプリケーションではなく Windows
アプリケーションと認識するためである。この動作は、gdi32.dll/user32.dll
の関数を直接呼び出さないが、内部でそれらを呼び出す Shell
関数のような関数を呼び出すコンソールアプリケーションでも発生する。こうした状況下でユーザーのサインアウトやデバイスのシャットダウン時にイベントを受け取るには、コンソールアプリケーション内に非表示ウィンドウを作成し、そのウィンドウが受け取る
[**WM\_QUERYENDSESSION**](/windows/win32/shutdown/wm-queryendsession)
と [**WM\_ENDSESSION**](/windows/win32/shutdown/wm-endsession)
を処理する。非表示ウィンドウは
[**CreateWindowEx**](/windows/win32/api/winuser/nf-winuser-createwindowexa)
を *dwExStyle* に 0 を指定して呼び出すことで作成できる。例は後述の基本ハンドラ例を参照。

情報