Fungsi ControlServiceExA (winsvc.h)
Mengirim kode kontrol ke layanan.
Sintaks
BOOL ControlServiceExA(
[in] SC_HANDLE hService,
[in] DWORD dwControl,
[in] DWORD dwInfoLevel,
[in, out] PVOID pControlParams
);
Parameter
[in] hService
Handel ke layanan. Handel ini dikembalikan oleh fungsi OpenService atau CreateService . Hak akses yang diperlukan untuk handel ini bergantung pada kode dwControl yang diminta.
[in] dwControl
Parameter ini bisa menjadi salah satu kode kontrol berikut.
Parameter ini juga dapat menjadi kode kontrol yang ditentukan pengguna, seperti yang dijelaskan dalam tabel berikut.
Kode kontrol | Makna |
---|---|
|
Layanan menentukan tindakan yang terkait dengan kode kontrol. Handel hService harus memiliki hak akses SERVICE_USER_DEFINED_CONTROL. |
[in] dwInfoLevel
Tingkat informasi untuk parameter kontrol layanan. Parameter ini harus diatur ke SERVICE_CONTROL_STATUS_REASON_INFO (1).
[in, out] pControlParams
Penunjuk ke parameter kontrol layanan. Jika dwInfoLevel SERVICE_CONTROL_STATUS_REASON_INFO, anggota ini adalah penunjuk ke struktur SERVICE_CONTROL_STATUS_REASON_PARAMS .
Nilai kembali
Jika fungsi berhasil, nilai yang dikembalikan bukan nol.
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. Kode kesalahan lainnya dapat diatur oleh fungsi registri yang dipanggil oleh manajer kontrol layanan.
Menampilkan kode | Deskripsi |
---|---|
|
Handel tidak memiliki hak akses yang diperlukan. |
|
Layanan tidak dapat dihentikan karena layanan lain yang sedang berjalan bergantung padanya. |
|
Handel yang ditentukan tidak diperoleh menggunakan CreateService atau OpenService, atau handel tidak lagi valid. |
|
Kode kontrol yang diminta dalam parameter dwControl tidak terdefinisi, atau dwControl SERVICE_CONTROL_STOP tetapi anggota dwReason atau pszComment dari struktur SERVICE_CONTROL_STATUS_REASON_PARAMS tidak valid. |
|
Kode kontrol yang diminta tidak valid, atau tidak dapat diterima oleh layanan. |
|
Kode kontrol yang diminta tidak dapat dikirim ke layanan karena status layanan SERVICE_STOPPED, SERVICE_START_PENDING, atau SERVICE_STOP_PENDING. |
|
Layanan belum dimulai. |
|
Proses untuk layanan dimulai, tetapi tidak memanggil StartServiceCtrlDispatcher, atau utas yang disebut StartServiceCtrlDispatcher dapat diblokir dalam fungsi handler kontrol. |
|
Sistem sedang dimatikan. |
Keterangan
Fungsi ControlServiceEx meminta Service Control Manager (SCM) untuk mengirim kode kontrol yang diminta ke layanan. SCM mengirimkan kode jika layanan telah menentukan bahwa ia akan menerima kode, dan berada dalam keadaan di mana kode kontrol dapat dikirim ke dalamnya.
SCM memproses pemberitahuan kontrol layanan secara serial — menunggu satu layanan selesai memproses pemberitahuan kontrol layanan sebelum mengirim yang berikutnya. Karena itu, panggilan ke ControlServiceEx memblokir selama 30 detik jika ada layanan yang sibuk menangani kode kontrol. Jika layanan sibuk masih belum kembali dari fungsi handler saat batas waktu berakhir, ControlServiceEx gagal dengan ERROR_SERVICE_REQUEST_TIMEOUT.
Untuk menghentikan dan memulai layanan memerlukan pendeskripsi keamanan yang memungkinkan Anda melakukannya. Pendeskripsi keamanan default memungkinkan akun LocalSystem, dan anggota grup Administrator dan Pengguna Power untuk menghentikan dan memulai layanan. Untuk mengubah pendeskripsi keamanan layanan, lihat Memodifikasi DACL untuk Layanan.
Fungsi QueryServiceStatusEx mengembalikan struktur SERVICE_STATUS_PROCESS yang anggota dwCurrentState dan dwControlsAccepted menunjukkan status dan kontrol saat ini yang diterima oleh layanan yang sedang berjalan. Semua layanan yang berjalan menerima kode kontrol SERVICE_CONTROL_INTERROGATE secara default. Driver tidak menerima kode kontrol selain SERVICE_CONTROL_STOP dan SERVICE_CONTROL_INTERROGATE. Setiap layanan menentukan kode kontrol lain yang diterimanya saat memanggil fungsi SetServiceStatus untuk melaporkan statusnya. Layanan harus selalu menerima kode-kode ini ketika sedang berjalan, apa pun yang dilakukannya.
Tabel berikut menunjukkan tindakan SCM di setiap status layanan yang mungkin.
Status layanan | Hentikan | Kontrol lainnya |
---|---|---|
BERHENTI | (c) | (c) |
STOP_PENDING | (b) | (b) |
START_PENDING | (a) | (b) |
RUNNING | (a) | (a) |
CONTINUE_PENDING | (a) | (a) |
PAUSE_PENDING | (a) | (a) |
BERHENTI | (a) | (a) |
- (a)
- Jika layanan menerima kode kontrol ini, kirim permintaan ke layanan; jika tidak, ControlServiceEx mengembalikan nol dan GetLastError mengembalikan ERROR_INVALID_SERVICE_CONTROL.
- (b)
- Layanan tidak dalam keadaan di mana kontrol dapat dikirim ke dalamnya, sehingga ControlServiceEx mengembalikan nol dan GetLastError mengembalikan ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
- (c)
- Layanan tidak aktif, sehingga ControlServiceEx mengembalikan nol dan GetLastError mengembalikan ERROR_SERVICE_NOT_ACTIVE.
Catatan
Header winsvc.h mendefinisikan ControlServiceEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosedur 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
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 (termasuk Windows.h) |
Pustaka | Advapi32.lib |
DLL | Advapi32.dll |