Fungsi panggilan balik HandlerRoutine

Artikel
07/12/2023

Fungsi yang ditentukan aplikasi yang digunakan dengan fungsi SetConsoleCtrlHandler. Proses konsol menggunakan fungsi ini untuk menangani sinyal kontrol yang diterima oleh proses. Ketika sinyal diterima, sistem membuat utas baru dalam proses untuk menjalankan fungsi.

Jenis PHANDLER_ROUTINE menentukan penunjuk ke fungsi panggilan balik ini. HandlerRoutine adalah tempat penampung untuk nama fungsi yang ditentukan aplikasi.

Sintaks

BOOL WINAPI HandlerRoutine(
  _In_ DWORD dwCtrlType
);

Parameter

dwCtrlType [in]
Jenis sinyal kontrol yang diterima oleh handler. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
CTRL_C_EVENT 0	Sinyal `CTRL+C` diterima, baik dari input keyboard atau dari sinyal yang dihasilkan oleh fungsi GenerateConsoleCtrlEvent.
CTRL_BREAK_EVENT 1	Sinyal `CTRL+BREAK` diterima, baik dari input keyboard atau dari sinyal yang dihasilkan oleh GenerateConsoleCtrlEvent.
CTRL_CLOSE_EVENT 2	Sinyal yang dikirim sistem ke semua proses yang dilampirkan ke konsol saat pengguna menutup konsol (baik dengan mengklik Tutup pada menu jendela jendela konsol, atau dengan mengklik perintah tombol Akhiri Tugas dari Task Manager).
CTRL_LOGOFF_EVENT 5	Sinyal yang dikirim sistem ke semua proses konsol saat pengguna keluar. Sinyal ini tidak menunjukkan pengguna mana yang keluar, sehingga tidak ada asumsi yang dapat dibuat. Perhatikan bahwa sinyal ini hanya diterima oleh layanan. Aplikasi interaktif dihentikan saat keluar, sehingga tidak ada ketika sistem mengirim sinyal ini.
CTRL_SHUTDOWN_EVENT 6	Sinyal yang dikirim sistem ketika sistem dimatikan. Aplikasi interaktif tidak ada pada saat sistem mengirim sinyal ini, oleh karena itu hanya dapat diterima menjadi layanan dalam situasi ini. Layanan juga memiliki mekanisme pemberitahuan mereka sendiri untuk peristiwa penonaktifan. Untuk informasi selengkapnya, lihat Handler.

Nilai hasil

Jika fungsi menangani sinyal kontrol, fungsi harus mengembalikan TRUE. Jika mengembalikan FALSE, fungsi handler berikutnya dalam daftar handler untuk proses ini digunakan.

Keterangan

Karena sistem membuat utas baru dalam proses untuk menjalankan fungsi handler, ada kemungkinan bahwa fungsi handler akan dihentikan oleh utas lain dalam proses. Pastikan untuk menyinkronkan utas dalam proses dengan utas untuk fungsi handler.

Setiap proses konsol memiliki daftar fungsi HandlerRoutine sendiri. Awalnya, daftar ini hanya berisi fungsi handler default yang memanggil 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 dan pertama kali dipanggil sampai salah satu handler mengembalikan TRUE. Jika tidak ada handler yang mengembalikan TRUE, handler default akan dipanggil.

Sinyal CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, dan CTRL_SHUTDOWN_EVENT memberi proses kesempatan untuk membersihkan sebelum penghentian. HandlerRoutine dapat melakukan pembersihan yang diperlukan, lalu mengambil salah satu tindakan berikut:

Panggil fungsi ExitProcess untuk mengakhiri proses.
Kembalikan FALSE. Jika tidak ada fungsi handler terdaftar yang mengembalikan TRUE, handler default mengakhiri proses.
Mengembalikan TRUE. Dalam hal ini, tidak ada fungsi handler lain yang dipanggil dan sistem menghentikan proses.

Proses dapat menggunakan fungsi SetProcessShutdownParameters untuk mencegah sistem menampilkan kotak dialog kepada pengguna selama keluar atau mematikan. Dalam hal ini, sistem mengakhiri proses ketika HandlerRoutine mengembalikan TRUE atau ketika periode waktu habis berlalu.

Saat aplikasi konsol dijalankan sebagai layanan, aplikasi tersebut menerima handler kontrol konsol default yang dimodifikasi. Handler yang dimodifikasi ini tidak memanggil ExitProcess saat memproses sinyal CTRL_LOGOFF_EVENT dan CTRL_SHUTDOWN_EVENT. Ini memungkinkan layanan untuk terus berjalan setelah pengguna keluar. Jika layanan menginstal handler kontrol konsolnya sendiri, handler ini dipanggil sebelum handler default. Jika handler yang diinstal memanggil ExitProcess saat memproses sinyal CTRL_LOGOFF_EVENT , layanan akan keluar saat pengguna keluar.

Perhatikan bahwa pustaka pihak ketiga atau DLL dapat menginstal handler kontrol konsol untuk aplikasi Anda. Jika ya, handler ini mengambil alih handler default, dan dapat menyebabkan aplikasi keluar saat pengguna keluar.

Waktu habis

Kejadian	Keadaan	Waktu habis
`CTRL_CLOSE_EVENT`	any	parameter `SPI_GETHUNGAPPTIMEOUT`sistem , 5000ms
`CTRL_LOGOFF_EVENT`	cepat[1]	kunci `CriticalAppShutdownTimeout` registri atau 500ms
`CTRL_LOGOFF_EVENT`	tidak satu pun dari hal di atas	parameter `SPI_GETWAITTOKILLTIMEOUT`sistem , 5000ms
`CTRL_SHUTDOWN_EVENT`	proses layanan	parameter `SPI_GETWAITTOKILLSERVICETIMEOUT`sistem , 20000ms
`CTRL_SHUTDOWN_EVENT`	cepat[1]	kunci `CriticalAppShutdownTimeout` registri atau 500ms
`CTRL_SHUTDOWN_EVENT`	tidak satu pun dari hal di atas	parameter `SPI_GETWAITTOKILLTIMEOUT`sistem , 5000ms
`CTRL_C`, `CTRL_BREAK`	any	tidak ada batas waktu

[1]: Peristiwa "cepat" tidak pernah digunakan, tetapi masih ada kode untuk mendukungnya.

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)