Fungsi SetServiceStatus (winsvc.h)

Artikel
03/04/2024

Updates informasi status manajer kontrol layanan untuk layanan panggilan.

Sintaks

BOOL SetServiceStatus(
  [in] SERVICE_STATUS_HANDLE hServiceStatus,
  [in] LPSERVICE_STATUS      lpServiceStatus
);

Parameter

[in] hServiceStatus

Handel ke struktur informasi status untuk layanan saat ini. Handel ini dikembalikan oleh fungsi RegisterServiceCtrlHandlerEx .

[in] lpServiceStatus

Penunjuk ke struktur SERVICE_STATUS berisi informasi status terbaru untuk layanan panggilan.

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_INVALID_DATA	Struktur status layanan yang ditentukan tidak valid.
ERROR_INVALID_HANDLE	Handel yang ditentukan tidak valid.

Keterangan

Fungsi ServiceMain pertama-tama memanggil fungsi RegisterServiceCtrlHandlerEx untuk mendapatkan SERVICE_STATUS_HANDLE layanan. Kemudian segera memanggil fungsi SetServiceStatus untuk memberi tahu manajer kontrol layanan bahwa statusnya SERVICE_START_PENDING. Selama inisialisasi, layanan dapat memberikan status yang diperbarui untuk menunjukkan bahwa itu membuat kemajuan tetapi membutuhkan lebih banyak waktu. Bug umum adalah agar layanan memiliki utas utama melakukan inisialisasi sementara utas terpisah terus memanggil SetServiceStatus untuk mencegah manajer kontrol layanan menandainya sebagai digantung. Namun, jika utas utama macet, maka layanan mulai berakhir dalam perulangan tak terbatas karena utas pekerja terus melaporkan bahwa utas utama membuat kemajuan.

Setelah memproses permintaan kontrol, fungsi Handler layanan harus memanggil SetServiceStatus jika status layanan berubah untuk melaporkan status barunya ke manajer kontrol layanan. Anda hanya perlu melakukannya ketika layanan mengubah status, seperti ketika sedang memproses kontrol berhenti atau matikan. Layanan juga dapat menggunakan fungsi ini kapan saja dari utas layanan apa pun untuk memberi tahu manajer kontrol layanan tentang perubahan status, seperti kapan layanan harus berhenti karena kesalahan yang dapat dipulihkan.

Layanan dapat memanggil fungsi ini hanya setelah disebut RegisterServiceCtrlHandlerEx untuk mendapatkan handel status layanan.

Jika layanan memanggil SetServiceStatus dengan anggota dwCurrentState yang diatur ke SERVICE_STOPPED dan anggota dwWin32ExitCode diatur ke nilai bukan nol, entri berikut ditulis ke dalam log peristiwa Sistem:

   Event ID    = 7023
   Source      = Service Control Manager
   Type        = Error
   Description = <ServiceName> terminated with the following error:
                 <ExitCode>.

Berikut ini adalah praktik terbaik saat memanggil fungsi ini:

Inisialisasi semua bidang dalam struktur SERVICE_STATUS , memastikan bahwa ada titik pemeriksaan yang valid dan nilai petunjuk tunggu untuk status tertunda. Gunakan petunjuk tunggu yang wajar.
Jangan mendaftar untuk menerima kontrol saat statusnya SERVICE_START_PENDING atau layanan dapat mengalami crash. Setelah inisialisasi selesai, terima kode SERVICE_CONTROL_STOP.
Panggil fungsi ini dengan nilai titik pemeriksaan dan petunjuk tunggu hanya jika layanan membuat kemajuan pada tugas yang terkait dengan operasi mulai, berhenti, jeda, atau lanjutkan yang tertunda. Jika tidak, SCM tidak dapat mendeteksi apakah layanan Anda digantung.
Masukkan status berhenti dengan kode keluar yang sesuai jika ServiceMain gagal.
Jika status SERVICE_STOPPED, lakukan semua pembersihan yang diperlukan dan panggil SetServiceStatus satu kali saja. Fungsi ini membuat panggilan LRPC ke SCM. Panggilan pertama ke fungsi dalam status SERVICE_STOPPED menutup handel konteks RPC dan panggilan berikutnya dapat menyebabkan proses crash.
Jangan mencoba melakukan pekerjaan tambahan setelah memanggil SetServiceStatus dengan SERVICE_STOPPED, karena proses layanan dapat dihentikan kapan saja.

Contoh

Misalnya, lihat Menulis Fungsi ServiceMain.

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