Fungsi StartServiceA (winsvc.h)

Artikel
08/27/2023

Memulai layanan.

Sintaks

BOOL StartServiceA(
  [in]           SC_HANDLE hService,
  [in]           DWORD     dwNumServiceArgs,
  [in, optional] LPCSTR    *lpServiceArgVectors
);

Parameter

[in] hService

Handel ke layanan. Handel ini dikembalikan oleh fungsi OpenService atau CreateService , dan harus memiliki hak akses SERVICE_START. Untuk informasi selengkapnya, lihat Keamanan Layanan dan Hak Akses.

[in] dwNumServiceArgs

Jumlah string dalam array lpServiceArgVectors . Jika lpServiceArgVectors ADALAH NULL, parameter ini bisa nol.

[in, optional] lpServiceArgVectors

String yang dihentikan null untuk diteruskan ke fungsi ServiceMain untuk layanan sebagai argumen. Jika tidak ada argumen, parameter ini bisa NULL. Jika tidak, argumen pertama (lpServiceArgVectors[0]) adalah nama layanan, diikuti oleh argumen tambahan apa pun (lpServiceArgVectors[1] melalui lpServiceArgVectors[dwNumServiceArgs-1]).

Layanan driver tidak menerima argumen ini.

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. Yang lain dapat diatur oleh fungsi registri yang dipanggil oleh manajer kontrol layanan.

Menampilkan kode	Deskripsi
ERROR_ACCESS_DENIED	Handel tidak memiliki hak akses SERVICE_START.
ERROR_INVALID_HANDLE	Handel tidak valid.
ERROR_PATH_NOT_FOUND	File biner layanan tidak dapat ditemukan.
ERROR_SERVICE_ALREADY_RUNNING	Instans layanan sudah berjalan.
ERROR_SERVICE_DATABASE_LOCKED	Database dikunci.
ERROR_SERVICE_DEPENDENCY_DELETED	Layanan tergantung pada layanan yang tidak ada atau telah ditandai untuk dihapus.
ERROR_SERVICE_DEPENDENCY_FAIL	Layanan tergantung pada layanan lain yang gagal dimulai.
ERROR_SERVICE_DISABLED	Layanan telah dinonaktifkan.
ERROR_SERVICE_LOGON_FAILED	Layanan tidak dimulai karena kegagalan masuk. Kesalahan ini terjadi jika layanan dikonfigurasi untuk berjalan di bawah akun yang tidak memiliki hak "Masuk sebagai layanan".
ERROR_SERVICE_MARKED_FOR_DELETE	Layanan telah ditandai untuk dihapus.
ERROR_SERVICE_NO_THREAD	Utas tidak dapat dibuat untuk layanan.
ERROR_SERVICE_REQUEST_TIMEOUT	Proses untuk layanan dimulai, tetapi tidak memanggil StartServiceCtrlDispatcher, atau utas yang disebut StartServiceCtrlDispatcher dapat diblokir dalam fungsi handler kontrol.

Keterangan

Ketika layanan driver dimulai, fungsi StartService tidak kembali sampai driver perangkat selesai diinisialisasi.

Ketika layanan dimulai, Service Control Manager (SCM) menelurkan proses layanan, jika perlu. Jika layanan yang ditentukan berbagi proses dengan layanan lain, proses yang diperlukan mungkin sudah ada. Fungsi StartService tidak menunggu pembaruan status pertama dari layanan baru, karena dapat memakan waktu cukup lama. Sebaliknya, ia kembali ketika SCM menerima pemberitahuan dari dispatcher kontrol layanan bahwa utas ServiceMain untuk layanan ini berhasil dibuat.

SCM mengatur nilai status default berikut sebelum kembali dari StartService:

Status layanan saat ini diatur ke SERVICE_START_PENDING.
Kontrol yang diterima diatur ke tidak ada (nol).
Nilai CheckPoint diatur ke nol.
Waktu WaitHint diatur ke 2 detik.

Proses panggilan dapat menentukan apakah layanan baru telah menyelesaikan inisialisasinya dengan memanggil fungsi QueryServiceStatus secara berkala untuk mengkueri status layanan.

Layanan tidak dapat memanggil StartService selama inisialisasi. Alasannya adalah bahwa SCM mengunci database kontrol layanan selama inisialisasi, sehingga panggilan ke StartService akan memblokir. Setelah layanan melaporkan ke SCM bahwa layanan telah berhasil dimulai, layanan dapat memanggil StartService.

Seperti halnya ControlService, StartService akan memblokir selama 30 detik jika ada layanan yang sibuk menangani kode kontrol. Jika layanan sibuk masih belum kembali dari fungsi handler-nya ketika batas waktu habis berakhir, StartService gagal dengan ERROR_SERVICE_REQUEST_TIMEOUT. Ini karena SCM hanya memproses satu pemberitahuan kontrol layanan pada satu waktu.

Contoh

Misalnya, lihat Memulai Layanan.

Catatan

Header winsvc.h mendefinisikan StartService 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 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