Fungsi ControlService (winsvc.h)

Artikel
03/08/2023

Mengirim kode kontrol ke layanan.

Untuk menentukan informasi tambahan saat menghentikan layanan, gunakan fungsi ControlServiceEx .

Sintaks

BOOL ControlService(
  [in]  SC_HANDLE        hService,
  [in]  DWORD            dwControl,
  [out] LPSERVICE_STATUS lpServiceStatus
);

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.

Kode kontrol	Makna
SERVICE_CONTROL_CONTINUE 0x00000003	Memberi tahu layanan yang dijeda bahwa layanan harus dilanjutkan. Handel hService harus memiliki hak akses SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_INTERROGATE 0x00000004	Memberi tahu layanan bahwa layanan tersebut harus melaporkan informasi statusnya saat ini ke manajer kontrol layanan. Handel hService harus memiliki hak akses SERVICE_INTERROGATE . Perhatikan bahwa kontrol ini umumnya tidak berguna karena SCM mengetahui status layanan saat ini.
SERVICE_CONTROL_NETBINDADD 0x00000007	Memberi tahu layanan jaringan bahwa ada komponen baru untuk pengikatan. Handel hService harus memiliki hak akses SERVICE_PAUSE_CONTINUE . Namun, kode kontrol ini tidak digunakan lagi; gunakan fungsionalitas Plug and Play sebagai gantinya.
SERVICE_CONTROL_NETBINDDISABLE 0x0000000A	Memberi tahu layanan jaringan bahwa salah satu pengikatannya telah dinonaktifkan. Handel hService harus memiliki hak akses SERVICE_PAUSE_CONTINUE . Namun, kode kontrol ini tidak digunakan lagi; gunakan fungsionalitas Plug and Play sebagai gantinya.
SERVICE_CONTROL_NETBINDENABLE 0x00000009	Memberi tahu layanan jaringan bahwa pengikatan yang dinonaktifkan telah diaktifkan. Handel hService harus memiliki hak akses SERVICE_PAUSE_CONTINUE . Namun, kode kontrol ini tidak digunakan lagi; gunakan fungsionalitas Plug and Play sebagai gantinya.
SERVICE_CONTROL_NETBINDREMOVE 0x00000008	Memberi tahu layanan jaringan bahwa komponen untuk pengikatan telah dihapus. Handel hService harus memiliki hak akses SERVICE_PAUSE_CONTINUE . Namun, kode kontrol ini tidak digunakan lagi; gunakan fungsionalitas Plug and Play sebagai gantinya.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Memberi tahu layanan bahwa parameter startup-nya telah berubah. Handel hService harus memiliki hak akses SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_PAUSE 0x00000002	Memberi tahu layanan bahwa layanan harus dijeda. Handel hService harus memiliki hak akses SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_STOP 0x00000001	Memberi tahu layanan bahwa layanan tersebut harus dihentikan. Handel hService harus memiliki hak akses SERVICE_STOP . Setelah mengirim permintaan berhenti ke layanan, Anda tidak boleh mengirim kontrol lain ke layanan.

Nilai ini juga bisa menjadi kode kontrol yang ditentukan pengguna, seperti yang dijelaskan dalam tabel berikut.

Kode kontrol	Makna
Rentang 128 hingga 255	Layanan menentukan tindakan yang terkait dengan kode kontrol. Handel hService harus memiliki hak akses SERVICE_USER_DEFINED_CONTROL .

[out] lpServiceStatus

Penunjuk ke struktur SERVICE_STATUS yang menerima informasi status layanan terbaru. Informasi yang dikembalikan mencerminkan status terbaru yang dilaporkan layanan ke manajer kontrol layanan.

Manajer kontrol layanan mengisi struktur hanya ketika GetLastError mengembalikan salah satu kode kesalahan berikut: NO_ERROR, ERROR_INVALID_SERVICE_CONTROL, ERROR_SERVICE_CANNOT_ACCEPT_CTRL, atau ERROR_SERVICE_NOT_ACTIVE. Jika tidak, struktur tidak diisi.

Mengembalikan nilai

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
ERROR_ACCESS_DENIED	Handel tidak memiliki hak akses yang diperlukan.
ERROR_DEPENDENT_SERVICES_RUNNING	Layanan tidak dapat dihentikan karena layanan lain yang sedang berjalan bergantung padanya.
ERROR_INVALID_HANDLE	Handel yang ditentukan tidak diperoleh menggunakan CreateService atau OpenService, atau handel tidak lagi valid.
ERROR_INVALID_PARAMETER	Kode kontrol yang diminta tidak ditentukan.
ERROR_INVALID_SERVICE_CONTROL	Kode kontrol yang diminta tidak valid, atau tidak dapat diterima oleh layanan.
ERROR_SERVICE_CANNOT_ACCEPT_CTRL	Kode kontrol yang diminta tidak dapat dikirim ke layanan karena status layanan SERVICE_STOPPED, SERVICE_START_PENDING, atau SERVICE_STOP_PENDING.
ERROR_SERVICE_NOT_ACTIVE	Layanan belum dimulai.
ERROR_SERVICE_REQUEST_TIMEOUT	Proses untuk layanan dimulai, tetapi tidak memanggil StartServiceCtrlDispatcher, atau utas yang disebut StartServiceCtrlDispatcher dapat diblokir dalam fungsi handler kontrol.
ERROR_SHUTDOWN_IN_PROGRESS	Sistem dimatikan.

Keterangan

Fungsi ControlService 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 status di mana kode kontrol dapat dikirim ke dalamnya.

SCM memproses pemberitahuan kontrol layanan dengan cara serial—akan menunggu satu layanan selesai memproses pemberitahuan kontrol layanan sebelum mengirim yang berikutnya. Karena itu, panggilan ke ControlService akan memblokir selama 30 detik jika ada layanan yang sibuk menangani kode kontrol. Jika layanan sibuk masih belum kembali dari fungsi handler-nya ketika waktu habis berakhir, ControlService gagal dengan ERROR_SERVICE_REQUEST_TIMEOUT.

Untuk menghentikan dan memulai layanan memerlukan deskriptor 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, ControlService mengembalikan nol dan GetLastError mengembalikan ERROR_INVALID_SERVICE_CONTROL.
(b): Layanan tidak dalam keadaan di mana kontrol dapat dikirim ke dalamnya, sehingga ControlService mengembalikan nol dan GetLastError mengembalikan ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
(c): Layanan tidak aktif, sehingga ControlService mengembalikan nol dan GetLastError mengembalikan ERROR_SERVICE_NOT_ACTIVE.

Contoh

Misalnya, lihat Menghentikan Layanan.

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