Fungsi SetConsoleCtrlHandler

Artikel
12/13/2023

Menambahkan atau menghapus fungsi HandlerRoutine yang ditentukan aplikasi dari daftar fungsi handler untuk proses panggilan.

Jika tidak ada fungsi handler yang ditentukan, fungsi mengatur atribut yang dapat diwariskan yang menentukan apakah proses panggilan mengabaikan sinyal CTRL+C.

Sintaks

BOOL WINAPI SetConsoleCtrlHandler(
  _In_opt_ PHANDLER_ROUTINE HandlerRoutine,
  _In_     BOOL             Add
);

Parameter

HandlerRoutine [in, opsional]
Penunjuk ke fungsi HandlerRoutine yang ditentukan aplikasi untuk ditambahkan atau dihapus. Parameter ini bisa NULL.

Tambahkan [in]
Jika parameter ini TRUE, handler ditambahkan; jika FALSE, handler akan dihapus.

Jika parameter HandlerRoutine adalah NULL, nilai TRUE menyebabkan proses panggilan mengabaikan input CTRL+C, dan nilai FALSE memulihkan pemrosesan normal input CTRL+C. Atribut mengabaikan atau memproses CTRL+C ini diwariskan oleh proses anak.

Nilai hasil

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Fungsi ini menyediakan pemberitahuan serupa untuk aplikasi dan layanan konsol yang WM_QUERYENDSESSION sediakan untuk aplikasi grafis dengan pompa pesan. Anda juga dapat menggunakan fungsi ini dari aplikasi grafis, tetapi tidak ada jaminan itu akan tiba sebelum pemberitahuan dari WM_QUERYENDSESSION.

Setiap proses konsol memiliki daftar fungsi HandlerRoutine yang ditentukan aplikasi sendiri yang menangani sinyal CTRL+C dan CTRL+BREAK. Fungsi handler juga menangani sinyal yang dihasilkan oleh sistem saat pengguna menutup konsol, keluar, atau mematikan sistem. Awalnya, daftar handler untuk setiap proses hanya berisi fungsi handler default yang memanggil fungsi ExitProcess. Proses konsol menambahkan atau menghapus fungsi handler tambahan dengan memanggil fungsi SetConsoleCtrlHandler , yang tidak memengaruhi daftar fungsi handler untuk proses lain. Ketika proses konsol menerima salah satu sinyal kontrol, fungsi handler-nya dipanggil berdasarkan yang terakhir didaftarkan, pertama kali dipanggil sampai salah satu handler mengembalikan TRUE. Jika tidak ada handler yang TRUEmengembalikan , handler default dipanggil.

Memanggil AttachConsole, AllocConsole, atau FreeConsole akan mengatur ulang tabel penangan kontrol dalam proses klien ke status awalnya. Handler harus didaftarkan lagi ketika sesi konsol yang terpasang berubah.

Untuk proses konsol, kombinasi tombol CTRL+C dan CTRL+BREAK biasanya diperlakukan sebagai sinyal (CTRL_C_EVENT dan CTRL_BREAK_EVENT). Saat jendela konsol dengan fokus keyboard menerima CTRL+C atau CTRL+BREAK, sinyal biasanya diteruskan ke semua proses yang berbagi konsol tersebut.

CTRL+BREAK selalu diperlakukan sebagai sinyal, tetapi perilaku CTRL+C khas dapat diubah dengan tiga cara yang mencegah fungsi handler dipanggil:

Fungsi SetConsoleMode dapat menonaktifkan mode ENABLE_PROCESSED_INPUT untuk buffer input konsol, sehingga CTRL+C dilaporkan sebagai input keyboard daripada sebagai sinyal.
Memanggil SetConsoleCtrlHandler dengan argumen NULL dan TRUE menyebabkan proses panggilan mengabaikan sinyal CTRL+C. Atribut ini diwariskan oleh proses turunan, tetapi dapat diaktifkan atau dinonaktifkan oleh proses apa pun tanpa memengaruhi proses yang ada.
Jika proses konsol sedang di-debug dan sinyal CTRL+C belum dinonaktifkan, sistem menghasilkan pengecualian DBG_CONTROL_C. Pengecualian ini dimunculkan hanya untuk keuntungan debugger, dan aplikasi tidak boleh menggunakan handler pengecualian untuk menanganinya. Jika debugger menangani pengecualian, aplikasi tidak akan melihat CTRL+C, dengan satu pengecualian: penantian yang dapat diperingatkan akan berakhir. Jika debugger melewati pengecualian pada tidak tertangani, CTRL+C diteruskan ke proses konsol dan diperlakukan sebagai sinyal, seperti yang dibahas sebelumnya.

Proses konsol dapat menggunakan fungsi GenerateConsoleCtrlEvent untuk mengirim sinyal CTRL+C atau CTRL+BREAK ke grup proses konsol.

Sistem menghasilkan sinyal CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, dan CTRL_SHUTDOWN_EVENT saat pengguna menutup konsol, log off, atau mematikan sistem sehingga proses memiliki kesempatan untuk membersihkan sebelum penghentian. Fungsi konsol, atau fungsi run-time C apa pun yang memanggil fungsi konsol, mungkin tidak berfungsi dengan andal selama pemrosesan salah satu dari tiga sinyal yang disebutkan sebelumnya. Alasannya adalah bahwa beberapa atau semua rutinitas pembersihan konsol internal mungkin telah dipanggil sebelum menjalankan handler sinyal proses.

Windows 7, Windows 8, Windows 8.1 dan Windows 10:

Jika aplikasi konsol memuat pustaka gdi32.dll atau user32.dll, fungsi HandlerRoutine yang Anda tentukan saat Memanggil SetConsoleCtrlHandler tidak dipanggil untuk peristiwa CTRL_LOGOFF_EVENT dan CTRL_SHUTDOWN_EVENT. Sistem operasi mengenali proses yang memuat gdi32.dll atau user32.dll sebagai aplikasi Windows daripada aplikasi konsol. Perilaku ini juga terjadi untuk aplikasi konsol yang tidak memanggil fungsi di gdi32.dll atau user32.dll secara langsung, tetapi lakukan fungsi panggilan seperti fungsi Shell yang melakukan fungsi panggilan pada gilirannya di gdi32.dll atau user32.dll.

Untuk menerima peristiwa saat pengguna keluar atau perangkat dimatikan dalam keadaan ini, buat jendela tersembunyi di aplikasi konsol Anda, lalu tangani pesan jendela WM_QUERYENDSESSION dan WM_ENDSESSION yang diterima jendela tersembunyi. Anda dapat membuat jendela tersembunyi dengan memanggil metode CreateWindowEx dengan parameter dwExStyle diatur ke 0. Contoh ini disertakan dengan contoh handler dasar yang ditautkan di bawah ini.

Contoh

Misalnya, lihat Mendaftarkan Fungsi Handler Kontrol.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Header	ConsoleApi.h (melalui WinCon.h, sertakan Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll
Nama Unicode dan ANSI

Share via