LPHANDLER_FUNCTION fungsi panggilan balik (winsvc.h)

Artikel
03/08/2023

Fungsi panggilan balik yang ditentukan aplikasi yang digunakan dengan fungsi RegisterServiceCtrlHandler . Program layanan dapat menggunakannya sebagai fungsi handler kontrol dari layanan tertentu.

Jenis LPHANDLER_FUNCTION menentukan penunjuk ke fungsi ini. Handler adalah tempat penampung untuk nama yang ditentukan aplikasi.

Fungsi ini telah digantikan oleh fungsi handler kontrol HandlerEx yang digunakan dengan fungsi RegisterServiceCtrlHandlerEx . Layanan dapat menggunakan salah satu handler kontrol, tetapi handler kontrol baru mendukung data konteks yang ditentukan pengguna dan kode kontrol tambahan yang diperluas.

Sintaks

LPHANDLER_FUNCTION LphandlerFunction;

void LphandlerFunction(
  DWORD dwControl
)
{...}

Parameter

dwControl

Mengembalikan nilai

Tidak ada

Keterangan

Ketika layanan dimulai, fungsi ServiceMain-nya harus segera memanggil fungsi RegisterServiceCtrlHandler untuk menentukan fungsi Handler untuk memproses permintaan kontrol.

Dispatcher kontrol di utas utama proses layanan memanggil fungsi handler kontrol untuk layanan yang ditentukan setiap kali menerima permintaan kontrol dari manajer kontrol layanan. Setelah memproses permintaan kontrol, handler kontrol harus memanggil fungsi SetServiceStatus jika status layanan berubah untuk melaporkan status barunya ke manajer kontrol layanan.

Fungsi handler kontrol dimaksudkan untuk menerima pemberitahuan dan segera kembali. Fungsi panggilan balik harus menyimpan parameternya dan membuat utas lain untuk melakukan pekerjaan tambahan. (Aplikasi Anda harus memastikan bahwa utas tersebut telah keluar sebelum menghentikan layanan.) Secara khusus, handler kontrol harus menghindari operasi yang mungkin memblokir, seperti mengambil kunci, karena ini dapat mengakibatkan kebuntuan atau menyebabkan sistem berhenti merespons.

Ketika manajer kontrol layanan mengirim kode kontrol ke layanan, ia menunggu fungsi handler kembali sebelum mengirim kode kontrol tambahan ke layanan lain. Handler kontrol harus kembali secepat mungkin; jika tidak kembali dalam waktu 30 detik, SCM mengembalikan kesalahan. Jika layanan harus melakukan pemrosesan yang panjang ketika layanan menjalankan handler kontrol, layanan harus membuat utas sekunder untuk melakukan pemrosesan yang panjang, lalu kembali dari handler kontrol. Ini mencegah layanan mengikat dispatcher kontrol dan memblokir layanan lain agar tidak menerima kode kontrol.

Kode kontrol SERVICE_CONTROL_SHUTDOWN hanya boleh diproses oleh layanan yang harus benar-benar dibersihkan selama pematian, karena ada waktu terbatas (sekitar 20 detik) yang tersedia untuk penonaktifan layanan. Setelah waktu ini kedaluwarsa, pematian sistem berlanjut terlepas dari apakah penonaktifan layanan selesai. Perhatikan bahwa jika sistem dibiarkan dalam status matikan (tidak dimulai ulang atau dimatikan), layanan terus berjalan. Jika layanan Anda mendaftar untuk menerima SERVICE_CONTROL_SHUTDOWN, layanan harus menangani kode kontrol dan berhenti tepat waktu. Jika tidak, layanan dapat meningkatkan waktu yang diperlukan untuk mematikan sistem, karena sistem harus menunggu waktu penuh yang diizinkan untuk penonaktifan layanan sebelum pematian sistem dapat dilanjutkan.

Jika layanan memerlukan lebih banyak waktu untuk membersihkan, layanan harus mengirim pesan status STOP_PENDING , bersama dengan petunjuk tunggu, sehingga pengontrol layanan tahu berapa lama menunggu sebelum melaporkan ke sistem bahwa penonaktifan layanan selesai. Namun, untuk mencegah layanan menghentikan pematian, ada batasan berapa lama pengontrol layanan akan menunggu. Jika layanan dimatikan melalui snap-in Layanan, batasnya adalah 125 detik. Jika sistem operasi dimulai ulang, batas waktu ditentukan dalam nilai WaitToKillServiceTimeout dari kunci registri berikut:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

Layanan juga dapat menggunakan fungsi SetConsoleCtrlHandler untuk menerima pemberitahuan matikan. Pemberitahuan ini diterima ketika aplikasi yang sedang berjalan dimatikan, yang terjadi sebelum layanan dimatikan.

Contoh

Misalnya, lihat Menulis Fungsi Handler Kontrol.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	winsvc.h (termasuk Windows.h)