LPHANDLER_FUNCTION_EX fungsi panggilan balik (winsvc.h)
Fungsi panggilan balik yang ditentukan aplikasi yang digunakan dengan fungsi RegisterServiceCtrlHandlerEx . Program layanan dapat menggunakannya sebagai fungsi handler kontrol dari layanan tertentu.
Jenis LPHANDLER_FUNCTION_EX mendefinisikan penunjuk ke fungsi ini. HandlerEx adalah tempat penampung untuk nama yang ditentukan aplikasi.
Fungsi ini menggantikan fungsi handler kontrol Handler yang digunakan dengan fungsi RegisterServiceCtrlHandler . 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_EX LphandlerFunctionEx;
DWORD LphandlerFunctionEx(
[in] DWORD dwControl,
[in] DWORD dwEventType,
[in] LPVOID lpEventData,
[in] LPVOID lpContext
)
{...}
Parameter
[in] dwControl
Kode kontrol. Parameter ini bisa menjadi salah satu nilai berikut.
| Kode kontrol | Makna |
|---|---|
|
Memberi tahu layanan yang dijeda bahwa layanan harus dilanjutkan. |
|
Memberi tahu layanan untuk melaporkan informasi statusnya saat ini ke manajer kontrol layanan.
Handler hanya harus mengembalikan NO_ERROR; SCM mengetahui status layanan saat ini. |
|
Memberi tahu layanan jaringan bahwa ada komponen baru untuk pengikatan. Layanan harus mengikat komponen baru.
Aplikasi harus menggunakan fungsionalitas Plug and Play sebagai gantinya. |
|
Memberi tahu layanan jaringan bahwa salah satu pengikatannya telah dinonaktifkan. Layanan harus dibaca ulang informasi pengikatannya dan menghapus pengikatan.
Aplikasi harus menggunakan fungsionalitas Plug and Play sebagai gantinya. |
|
Memberi tahu layanan jaringan bahwa pengikatan yang dinonaktifkan telah diaktifkan. Layanan harus dibaca ulang informasi pengikatannya dan menambahkan pengikatan baru.
Aplikasi harus menggunakan fungsionalitas Plug and Play sebagai gantinya. |
|
Memberi tahu layanan jaringan bahwa komponen untuk pengikatan telah dihapus. Layanan harus dibaca ulang informasi pengikatannya dan membatalkan ikatan dari komponen yang dihapus.
Aplikasi harus menggunakan fungsionalitas Plug and Play sebagai gantinya. |
|
Memberi tahu layanan bahwa parameter startup khusus layanan telah berubah. Layanan harus dibaca ulang parameter startup-nya. |
|
Memberi tahu layanan bahwa layanan harus dijeda. |
|
Memberi tahu layanan bahwa sistem akan dimatikan. Layanan yang membutuhkan waktu tambahan untuk melakukan tugas pembersihan di luar pembatasan waktu yang ketat pada pematian sistem dapat menggunakan pemberitahuan ini. Manajer kontrol layanan mengirimkan pemberitahuan ini ke aplikasi yang telah mendaftarkannya sebelum mengirim pemberitahuan SERVICE_CONTROL_SHUTDOWN ke aplikasi yang telah mendaftar untuk pemberitahuan tersebut.
Layanan yang menangani pemberitahuan ini memblokir penonaktifan sistem hingga layanan berhenti atau interval batas waktu penonaktifan yang ditentukan melalui SERVICE_PRESHUTDOWN_INFO kedaluwarsa. Karena ini mempengaruhi pengalaman pengguna, layanan harus menggunakan fitur ini hanya jika benar-benar diperlukan untuk menghindari kehilangan data atau waktu pemulihan yang signifikan pada awal sistem berikutnya. Windows Server 2003 dan Windows XP: Nilai ini tidak didukung. |
|
Memberi tahu layanan bahwa sistem dimatikan sehingga layanan dapat melakukan tugas pembersihan. Perhatikan bahwa layanan yang mendaftar untuk pemberitahuan SERVICE_CONTROL_PRESHUTDOWN tidak dapat menerima pemberitahuan ini karena telah berhenti.
Jika layanan menerima kode kontrol ini, layanan harus berhenti setelah melakukan tugas pembersihan dan mengembalikan NO_ERROR. Setelah SCM mengirim kode kontrol ini, SCM tidak akan mengirim kode kontrol lain ke layanan. Untuk informasi selengkapnya, lihat bagian Keterangan dari topik ini. |
|
Memberi tahu layanan bahwa layanan tersebut harus dihentikan.
Jika layanan menerima kode kontrol ini, layanan harus berhenti setelah diterima dan mengembalikan NO_ERROR. Setelah SCM mengirim kode kontrol ini, SCM tidak akan mengirim kode kontrol lain ke layanan. Windows XP: Jika layanan mengembalikan NO_ERROR dan terus berjalan, layanan terus menerima kode kontrol. Perilaku ini berubah dimulai dengan Windows Server 2003 dan Windows XP dengan SP2. |
Parameter ini juga dapat menjadi salah satu kode kontrol yang diperluas berikut. Perhatikan bahwa kode kontrol ini tidak didukung oleh fungsi Handler .
| Kode Kontrol | Makna |
|---|---|
|
Memberi tahu layanan peristiwa perangkat. (Layanan harus telah terdaftar untuk menerima pemberitahuan ini menggunakan fungsi RegisterDeviceNotification .) Parameter dwEventType dan lpEventData berisi informasi tambahan. |
|
Memberi tahu layanan bahwa profil perangkat keras komputer telah berubah. Parameter dwEventType berisi informasi tambahan. |
|
Memberi tahu layanan peristiwa daya sistem. Parameter dwEventType berisi informasi tambahan. Jika dwEventTypePBT_POWERSETTINGCHANGE, parameter lpEventData juga berisi informasi tambahan. |
|
Memberi tahu layanan peristiwa perubahan sesi. Perhatikan bahwa layanan hanya akan diberi tahu tentang pengguna yang masuk jika sepenuhnya dimuat sebelum upaya masuk dilakukan. Parameter dwEventType dan lpEventData berisi informasi tambahan. |
|
Memberi tahu layanan bahwa waktu sistem telah berubah. Parameter lpEventData berisi informasi tambahan. Parameter dwEventType tidak digunakan.
Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Kode kontrol ini tidak didukung. |
|
Memberi tahu layanan yang terdaftar untuk peristiwa pemicu layanan bahwa peristiwa telah terjadi.
Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Kode kontrol ini tidak didukung. |
|
Memberi tahu layanan bahwa pengguna telah memulai boot ulang.
Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Kode kontrol ini tidak didukung. |
Parameter ini juga bisa menjadi kode kontrol yang ditentukan pengguna, seperti yang dijelaskan dalam tabel berikut.
| Kode kontrol | Makna |
|---|---|
|
Layanan menentukan tindakan yang terkait dengan kode kontrol. |
[in] dwEventType
Jenis peristiwa yang telah terjadi. Parameter ini digunakan jika dwControlSERVICE_CONTROL_DEVICEEVENT, SERVICE_CONTROL_HARDWAREPROFILECHANGE, SERVICE_CONTROL_POWEREVENT, atau SERVICE_CONTROL_SESSIONCHANGE. Jika tidak, itu nol.
Jika dwControlSERVICE_CONTROL_DEVICEEVENT, parameter ini bisa menjadi salah satu nilai berikut:
- DBT_DEVICEARRIVAL
- DBT_DEVICEREMOVECOMPLETE
- DBT_DEVICEQUERYREMOVE
- DBT_DEVICEQUERYREMOVEFAILED
- DBT_DEVICEREMOVEPENDING
- DBT_CUSTOMEVENT
Jika dwControlSERVICE_CONTROL_SESSIONCHANGE, parameter ini dapat menjadi salah satu nilai yang ditentukan dalam parameter wParam dari pesan WM_WTSSESSION_CHANGE .
[in] lpEventData
Informasi perangkat tambahan, jika diperlukan. Format data ini tergantung pada nilai parameter dwControl dan dwEventType .
Jika dwControlSERVICE_CONTROL_DEVICEEVENT, data ini sesuai dengan parameter lParam yang diterima aplikasi sebagai bagian dari pesan WM_DEVICECHANGE .
Jika dwControlSERVICE_CONTROL_POWEREVENT dan dwEventType PBT_POWERSETTINGCHANGE, data ini adalah penunjuk ke struktur POWERBROADCAST_SETTING .
Jika dwControlSERVICE_CONTROL_SESSIONCHANGE, parameter ini adalah penunjuk ke struktur WTSSESSION_NOTIFICATION .
Jika dwControlSERVICE_CONTROL_TIMECHANGE, data ini adalah penunjuk ke struktur SERVICE_TIMECHANGE_INFO .
[in] lpContext
Data yang ditentukan pengguna diteruskan dari RegisterServiceCtrlHandlerEx. Ketika beberapa layanan berbagi proses, parameter lpContext dapat membantu mengidentifikasi layanan.
Mengembalikan nilai
Nilai pengembalian untuk fungsi ini tergantung pada kode kontrol yang diterima.
Daftar berikut mengidentifikasi aturan untuk nilai pengembalian ini:
- Secara umum, jika layanan Anda tidak menangani kontrol, kembalikan ERROR_CALL_NOT_IMPLEMENTED. Namun, layanan Anda harus mengembalikan NO_ERROR untuk SERVICE_CONTROL_INTERROGATE meskipun layanan Anda tidak menanganinya.
- Jika layanan Anda menangani SERVICE_CONTROL_STOP atau SERVICE_CONTROL_SHUTDOWN, kembalikan NO_ERROR.
- Jika layanan Anda menangani SERVICE_CONTROL_DEVICEEVENT, kembalikan NO_ERROR untuk memberikan permintaan dan kode kesalahan untuk menolak permintaan.
- Jika layanan Anda menangani SERVICE_CONTROL_HARDWAREPROFILECHANGE, kembalikan NO_ERROR untuk memberikan permintaan dan kode kesalahan untuk menolak permintaan.
- Jika layanan Anda menangani SERVICE_CONTROL_POWEREVENT, kembalikan NO_ERROR untuk memberikan permintaan dan kode kesalahan untuk menolak permintaan.
- Untuk semua kode kontrol lainnya yang ditangani layanan Anda, kembalikan NO_ERROR.
Keterangan
Ketika layanan dimulai, fungsi ServiceMain-nya harus segera memanggil fungsi RegisterServiceCtrlHandlerEx untuk menentukan fungsi HandlerEx untuk memproses permintaan kontrol. Untuk menentukan kode kontrol yang akan diterima, gunakan fungsi SetServiceStatus dan RegisterDeviceNotification .
Dispatcher kontrol di utas utama layanan memanggil fungsi handler kontrol untuk layanan yang ditentukan setiap kali menerima permintaan kontrol dari manajer kontrol layanan. Setelah memproses permintaan kontrol, penangan kontrol harus memanggil 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 mengembalikan NO_ERROR. Mengembalikan kesalahan untuk kode kontrol ini dan tidak berhenti secara tepat waktu dapat meningkatkan waktu yang diperlukan untuk mematikan sistem, karena sistem harus menunggu waktu penuh yang diizinkan untuk pematian 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 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
Pastikan untuk menangani Plug and Play peristiwa perangkat secepat mungkin; jika tidak, sistem mungkin menjadi tidak responsif. Jika penanganan aktivitas Anda adalah melakukan operasi yang dapat memblokir eksekusi (seperti I/O), sebaiknya mulai utas lain untuk melakukan operasi secara asinkron.
Layanan juga dapat menggunakan fungsi SetConsoleCtrlHandler untuk menerima pemberitahuan matikan. Pemberitahuan ini diterima ketika aplikasi yang sedang berjalan dimatikan, yang terjadi sebelum layanan dimatikan.
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) |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk