Fungsi NotifyServiceStatusChangeA (winsvc.h)
Memungkinkan aplikasi untuk menerima pemberitahuan ketika layanan yang ditentukan dibuat atau dihapus atau ketika statusnya berubah.
Sintaks
DWORD NotifyServiceStatusChangeA(
[in] SC_HANDLE hService,
[in] DWORD dwNotifyMask,
[in] PSERVICE_NOTIFYA pNotifyBuffer
);
Parameter
[in] hService
Handel ke layanan atau manajer kontrol layanan. Handel ke layanan dikembalikan oleh fungsi OpenService atau CreateService dan harus memiliki hak akses SERVICE_QUERY_STATUS. Handel ke manajer kontrol layanan dikembalikan oleh fungsi OpenSCManager dan harus memiliki hak akses SC_MANAGER_ENUMERATE_SERVICE. Untuk informasi selengkapnya, lihat Keamanan Layanan dan Hak Akses.
Hanya ada satu permintaan pemberitahuan yang luar biasa per layanan.
[in] dwNotifyMask
Jenis perubahan status yang harus dilaporkan. Parameter ini bisa menjadi satu atau beberapa nilai berikut.
| Nilai | Makna |
|---|---|
|
Laporkan kapan layanan telah dibuat.
Parameter hService harus berupa handel ke SCM. |
|
Laporkan kapan layanan akan dilanjutkan.
Parameter hService harus berupa handel ke layanan. |
|
Laporkan ketika aplikasi telah menentukan layanan dalam panggilan ke fungsi DeleteService . Aplikasi Anda harus menutup handel apa pun ke layanan sehingga dapat dihapus.
Parameter hService harus berupa handel ke layanan. |
|
Laporkan kapan layanan telah dihapus. Aplikasi tidak dapat menerima pemberitahuan ini jika memiliki handel terbuka ke layanan.
Parameter hService harus berupa handel ke SCM. |
|
Laporkan saat layanan dijeda.
Parameter hService harus berupa handel ke layanan. |
|
Laporkan kapan layanan telah dijeda.
Parameter hService harus berupa handel ke layanan. |
|
Laporkan saat layanan berjalan.
Parameter hService harus berupa handel ke layanan. |
|
Laporkan kapan layanan dimulai.
Parameter hService harus berupa handel ke layanan. |
|
Laporkan kapan layanan berhenti.
Parameter hService harus berupa handel ke layanan. |
|
Laporkan kapan layanan telah berhenti.
Parameter hService harus berupa handel ke layanan. |
[in] pNotifyBuffer
Penunjuk ke struktur SERVICE_NOTIFY yang berisi informasi pemberitahuan, seperti penunjuk ke fungsi panggilan balik. Struktur ini harus tetap valid sampai fungsi panggilan balik dipanggil atau utas panggilan membatalkan permintaan pemberitahuan.
Jangan melakukan beberapa panggilan ke NotifyServiceStatusChange dengan parameter buffer yang sama sampai fungsi panggilan balik dari panggilan pertama telah selesai dengan buffer atau permintaan pemberitahuan pertama telah dibatalkan. Jika tidak, tidak ada jaminan versi buffer mana yang akan diterima fungsi panggilan balik.
Windows Vista: Alamat fungsi panggilan balik harus berada dalam rentang alamat modul yang dimuat. Oleh karena itu, fungsi panggilan balik tidak dapat berupa kode yang dihasilkan pada durasi (seperti kode terkelola yang dihasilkan oleh pengompilasi JIT) atau kode asli yang didekompresi pada durasi. Pembatasan ini dihapus di Windows Server 2008 dan Windows Vista dengan SP1.
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS. Jika layanan telah ditandai untuk penghapusan, nilai yang dikembalikan ERROR_SERVICE_MARKED_FOR_DELETE dan handel ke layanan harus ditutup. Jika pemberitahuan layanan tertinggal terlalu jauh di belakang status sistem, fungsi mengembalikan ERROR_SERVICE_NOTIFY_CLIENT_LAGGING. Dalam hal ini, klien harus menutup handel ke SCM, membuka handel baru, dan memanggil fungsi ini lagi.
Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan sistem.
Keterangan
Fungsi NotifyServiceStatusChange dapat digunakan untuk menerima pemberitahuan tentang aplikasi layanan. Ini tidak dapat digunakan untuk menerima pemberitahuan tentang layanan driver.
Ketika status layanan berubah, sistem memanggil fungsi panggilan balik yang ditentukan sebagai panggilan prosedur asinkron (APC) yang diantrekan ke utas panggilan. Utas panggilan harus memasukkan tunggu yang dapat diperingatkan (misalnya, dengan memanggil fungsi SleepEx ) untuk menerima pemberitahuan. Untuk informasi selengkapnya, lihat Panggilan Prosedur Asinkron.
Jika layanan sudah berada di salah satu status yang diminta saat NotifyServiceStatusChange dipanggil, fungsi panggilan balik segera diantrekan. Jika status layanan tidak berubah pada saat berikutnya fungsi dipanggil dengan layanan dan status yang sama, fungsi panggilan balik tidak segera diantrekan; fungsi panggilan balik diantrekan saat layanan memasuki status yang diminta.
Fungsi NotifyServiceStatusChange memanggil fungsi OpenThread pada utas panggilan dengan akses THREAD_SET_CONTEXT kanan. Jika utas panggilan tidak memiliki akses ini dengan benar, NotifyServiceStatusChange gagal. Jika utas panggilan meniru pengguna lain, alur panggilan mungkin tidak memiliki izin yang memadai untuk mengatur konteks.
Lebih efisien untuk memanggil NotifyServiceStatusChange dari utas yang melakukan penantian daripada membuat utas tambahan.
Setelah fungsi panggilan balik dipanggil, pemanggil harus memanggil NotifyServiceStatusChange untuk menerima pemberitahuan tambahan. Perhatikan bahwa fungsi tertentu di Windows API, termasuk NotifyServiceStatusChange dan fungsi SCM lainnya, menggunakan panggilan prosedur jarak jauh (RPC); fungsi-fungsi ini mungkin melakukan operasi tunggu yang dapat diperingatkan, sehingga tidak aman untuk dipanggil dari dalam fungsi panggilan balik. Sebagai gantinya, fungsi panggilan balik harus menyimpan parameter pemberitahuan dan melakukan pekerjaan tambahan di luar panggilan balik.
Untuk membatalkan pemberitahuan yang beredar, tutup handel layanan menggunakan fungsi CloseServiceHandle . Setelah CloseServiceHandle berhasil, tidak ada lagi APC pemberitahuan yang akan diantrekan. Jika utas panggilan keluar tanpa menutup handel layanan atau menunggu hingga APC dihasilkan, kebocoran memori dapat terjadi.
Catatan
Header winsvc.h mendefinisikan NotifyServiceStatusChange sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor 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 Vista [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | winsvc.h (sertakan Windows.h) |
| Pustaka | Advapi32.lib |
| DLL | Advapi32.dll |