Bagikan melalui

Fungsi NotifyServiceStatusChangeA (winsvc.h)

  • Artikel

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
SERVICE_NOTIFY_CREATED
0x00000080
 Laporkan kapan layanan telah dibuat.

Parameter hService harus berupa handel ke SCM.
SERVICE_NOTIFY_CONTINUE_PENDING
0x00000010
 Laporkan kapan layanan akan dilanjutkan.

Parameter hService harus berupa handel ke layanan.
SERVICE_NOTIFY_DELETE_PENDING
0x00000200
 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.
SERVICE_NOTIFY_DELETED
0x00000100
 Laporkan kapan layanan telah dihapus. Aplikasi tidak dapat menerima pemberitahuan ini jika memiliki handel terbuka ke layanan.

Parameter hService harus berupa handel ke SCM.
SERVICE_NOTIFY_PAUSE_PENDING
0x00000020
 Laporkan saat layanan dijeda.

Parameter hService harus berupa handel ke layanan.
SERVICE_NOTIFY_PAUSED
0x00000040
 Laporkan kapan layanan telah dijeda.

Parameter hService harus berupa handel ke layanan.
SERVICE_NOTIFY_RUNNING
0x00000008
 Laporkan saat layanan berjalan.

Parameter hService harus berupa handel ke layanan.
SERVICE_NOTIFY_START_PENDING
0x00000002
 Laporkan kapan layanan dimulai.

Parameter hService harus berupa handel ke layanan.
SERVICE_NOTIFY_STOP_PENDING
0x00000004
 Laporkan kapan layanan berhenti.

Parameter hService harus berupa handel ke layanan.
SERVICE_NOTIFY_STOPPED
0x00000001
 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.

Penting Jika utas panggilan berada di DLL dan DLL dibongkar sebelum utas menerima pemberitahuan atau memanggil CloseServiceHandle, pemberitahuan akan menyebabkan hasil yang tidak dapat diprediksi dan dapat menyebabkan proses berhenti merespons.
 

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

Lihat juga

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

Fungsi Layanan