Fungsi RegisterServiceCtrlHandlerA (winsvc.h)

Artikel
03/08/2023

Mendaftarkan fungsi untuk menangani permintaan kontrol layanan.

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

Sintaks

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerA(
  [in] LPCSTR             lpServiceName,
  [in] LPHANDLER_FUNCTION lpHandlerProc
);

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.

Jika jenis layanan SERVICE_WIN32_OWN_PROCESS, fungsi tidak memverifikasi bahwa nama yang ditentukan valid, karena hanya ada satu layanan terdaftar dalam proses.

[in] lpHandlerProc

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

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 RegisterServiceCtrlHandler 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 Handler. Utas proses panggilan dapat menggunakan handel status layanan yang dikembalikan oleh fungsi ini untuk mengidentifikasi layanan dalam panggilan berikutnya ke fungsi SetServiceStatus .

Fungsi RegisterServiceCtrlHandler harus dipanggil sebelum panggilan SetServiceStatus pertama karena RegisterServiceCtrlHandler 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.

Contoh

Misalnya, lihat Menulis Fungsi ServiceMain.

Catatan

Header winsvc.h mendefinisikan RegisterServiceCtrlHandler 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