Fungsi StartServiceCtrlDispatcherA (winsvc.h)

Artikel
03/08/2023

Menghubungkan utas utama proses layanan ke manajer kontrol layanan, yang menyebabkan utas menjadi utas dispatcher kontrol layanan untuk proses panggilan.

Sintaks

BOOL StartServiceCtrlDispatcherA(
  [in] const SERVICE_TABLE_ENTRYA *lpServiceStartTable
);

Parameter

[in] lpServiceStartTable

Penunjuk ke array struktur SERVICE_TABLE_ENTRY yang berisi satu entri untuk setiap layanan yang dapat dijalankan dalam proses panggilan. Anggota entri terakhir dalam tabel harus memiliki nilai NULL untuk menunjuk akhir tabel.

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
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT	Kesalahan ini dikembalikan jika program dijalankan sebagai aplikasi konsol daripada sebagai layanan. Jika program akan dijalankan sebagai aplikasi konsol untuk tujuan penelusuran kesalahan, susun sehingga kode khusus layanan tidak dipanggil ketika kesalahan ini dikembalikan.
ERROR_INVALID_DATA	Tabel pengiriman yang ditentukan berisi entri yang tidak dalam format yang tepat.
ERROR_SERVICE_ALREADY_RUNNING	Proses ini telah disebut StartServiceCtrlDispatcher. Setiap proses dapat memanggil StartServiceCtrlDispatcher hanya satu kali.

Keterangan

Ketika manajer kontrol layanan memulai proses layanan, ia menunggu proses untuk memanggil fungsi StartServiceCtrlDispatcher . Utas utama proses layanan harus melakukan panggilan ini sesegera mungkin setelah dimulai (dalam 30 detik). Jika StartServiceCtrlDispatcher berhasil, ini menyambungkan utas panggilan ke manajer kontrol layanan dan tidak kembali sampai semua layanan yang berjalan dalam proses telah memasuki status SERVICE_STOPPED. Manajer kontrol layanan menggunakan koneksi ini untuk mengirim kontrol dan permintaan mulai layanan ke utas utama proses layanan. Utas utama bertindak sebagai dispatcher dengan memanggil fungsi HandlerEx yang sesuai untuk menangani permintaan kontrol, atau dengan membuat utas baru untuk menjalankan fungsi ServiceMain yang sesuai saat layanan baru dimulai.

Parameter lpServiceTable berisi entri untuk setiap layanan yang dapat berjalan dalam proses panggilan. Setiap entri menentukan fungsi ServiceMain untuk layanan tersebut. Untuk layanan SERVICE_WIN32_SHARE_PROCESS, setiap entri harus berisi nama layanan. Nama ini adalah nama layanan yang ditentukan oleh fungsi CreateService saat layanan diinstal. Untuk layanan SERVICE_WIN32_OWN_PROCESS, nama layanan dalam entri tabel diabaikan.

Jika layanan berjalan dalam prosesnya sendiri, utas utama proses layanan harus segera memanggil StartServiceCtrlDispatcher. Semua tugas inisialisasi dilakukan dalam fungsi ServiceMain layanan saat layanan dimulai.

Jika beberapa layanan berbagi proses dan beberapa inisialisasi seluruh proses umum perlu dilakukan sebelum fungsi ServiceMain dipanggil, utas utama dapat melakukan pekerjaan sebelum memanggil StartServiceCtrlDispatcher, selama dibutuhkan kurang dari 30 detik. Jika tidak, utas lain harus dibuat untuk melakukan inisialisasi di seluruh proses, sementara utas utama memanggil StartServiceCtrlDispatcher dan menjadi dispatcher kontrol layanan. Inisialisasi khusus layanan apa pun masih harus dilakukan dalam fungsi utama layanan individual.

Layanan tidak boleh mencoba menampilkan antarmuka pengguna secara langsung. Untuk informasi selengkapnya, lihat Layanan Interaktif.

Contoh

Misalnya, lihat Menulis Fungsi Utama Program Layanan.

Catatan

Header winsvc.h mendefinisikan StartServiceCtrlDispatcher sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor 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 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