Fungsi RegisterServiceCtrlHandlerExA (winsvc.h)

Artikel
08/27/2023

Mendaftarkan fungsi untuk menangani permintaan kontrol layanan yang diperluas.

Sintaks

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerExA(
  [in]           LPCSTR                lpServiceName,
  [in]           LPHANDLER_FUNCTION_EX lpHandlerProc,
  [in, optional] LPVOID                lpContext
);

Parameter

[in] lpServiceName

Nama layanan yang dijalankan oleh utas panggilan. Ini adalah nama layanan yang ditentukan program kontrol layanan dalam fungsi CreateService saat membuat layanan.

[in] lpHandlerProc

Penunjuk ke fungsi handler yang akan didaftarkan. Untuk informasi selengkapnya, lihat HandlerEx.

[in, optional] lpContext

Setiap data yang ditentukan pengguna. Parameter ini, yang diteruskan ke fungsi handler, dapat membantu mengidentifikasi layanan ketika beberapa layanan berbagi proses.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah handel status layanan.

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

Kode kesalahan berikut dapat diatur oleh manajer kontrol layanan.

Menampilkan kode	Deskripsi
ERROR_NOT_ENOUGH_MEMORY	Tidak tersedia cukup memori untuk mengonversi parameter string ANSI ke Unicode. Kesalahan ini tidak terjadi untuk parameter untai (karakter) Unicode.
ERROR_SERVICE_NOT_IN_EXE	Entri layanan ditentukan dengan tidak benar ketika proses yang disebut fungsi StartServiceCtrlDispatcher .

Keterangan

Fungsi ServiceMain dari layanan baru harus segera memanggil fungsi RegisterServiceCtrlHandlerEx untuk mendaftarkan fungsi handler kontrol dengan dispatcher kontrol. Ini memungkinkan dispatcher kontrol untuk memanggil fungsi yang ditentukan ketika menerima permintaan kontrol untuk layanan ini. Untuk daftar kemungkinan kode kontrol, lihat HandlerEx. Utas proses panggilan dapat menggunakan handel status layanan yang dikembalikan oleh fungsi ini untuk mengidentifikasi layanan dalam panggilan berikutnya ke fungsi SetServiceStatus .

Fungsi RegisterServiceCtrlHandlerEx harus dipanggil sebelum panggilan SetServiceStatus pertama karena RegisterServiceCtrlHandlerEx mengembalikan handel status layanan untuk digunakan pemanggil sehingga tidak ada layanan lain yang secara tidak sengaja dapat mengatur status layanan ini. Selain itu, handler kontrol harus diberlakukan untuk menerima permintaan kontrol pada saat layanan menentukan kontrol yang diterimanya melalui fungsi SetServiceStatus .

Ketika fungsi handler kontrol dipanggil dengan permintaan kontrol, layanan harus memanggil SetServiceStatus untuk melaporkan status ke manajer kontrol layanan hanya jika status layanan telah berubah, seperti ketika layanan memproses kontrol berhenti atau matikan. Jika status layanan tidak berubah, layanan tidak boleh melaporkan status ke manajer kontrol layanan.

Handel status layanan tidak harus ditutup.

Catatan

Header winsvc.h mendefinisikan RegisterServiceCtrlHandlerEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

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 (sertakan Windows.h)
Pustaka	Advapi32.lib
DLL	Advapi32.dll