Fungsi CreateServiceW (winsvc.h)

Artikel
08/27/2023

Membuat objek layanan dan menambahkannya ke database manajer kontrol layanan yang ditentukan.

Sintaks

SC_HANDLE CreateServiceW(
  [in]            SC_HANDLE hSCManager,
  [in]            LPCWSTR   lpServiceName,
  [in, optional]  LPCWSTR   lpDisplayName,
  [in]            DWORD     dwDesiredAccess,
  [in]            DWORD     dwServiceType,
  [in]            DWORD     dwStartType,
  [in]            DWORD     dwErrorControl,
  [in, optional]  LPCWSTR   lpBinaryPathName,
  [in, optional]  LPCWSTR   lpLoadOrderGroup,
  [out, optional] LPDWORD   lpdwTagId,
  [in, optional]  LPCWSTR   lpDependencies,
  [in, optional]  LPCWSTR   lpServiceStartName,
  [in, optional]  LPCWSTR   lpPassword
);

Parameter

[in] hSCManager

Handel ke database manajer kontrol layanan. Handel ini dikembalikan oleh fungsi OpenSCManager dan harus memiliki hak akses SC_MANAGER_CREATE_SERVICE . Untuk informasi selengkapnya, lihat Keamanan Layanan dan Hak Akses.

[in] lpServiceName

Nama layanan yang akan diinstal. Panjang string maksimum adalah 256 karakter. Database manajer kontrol layanan mempertahankan kasus karakter, tetapi perbandingan nama layanan selalu tidak peka huruf besar/kecil. Garis miring (/) dan garis miring terbelakang (\) bukan karakter nama layanan yang valid.

[in, optional] lpDisplayName

Nama tampilan yang akan digunakan oleh program antarmuka pengguna untuk mengidentifikasi layanan. String ini memiliki panjang maksimum 256 karakter. Nama ini dipertahankan huruf besar/kecil di manajer kontrol layanan. Perbandingan nama tampilan selalu tidak peka huruf besar/kecil.

[in] dwDesiredAccess

Akses ke layanan. Sebelum memberikan akses yang diminta, sistem memeriksa token akses proses panggilan. Untuk daftar nilai, lihat Keamanan Layanan dan Hak Akses.

[in] dwServiceType

Jenis layanan. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
SERVICE_ADAPTER 0x00000004	Dicadangkan.
SERVICE_FILE_SYSTEM_DRIVER 0x00000002	Layanan driver sistem file.
SERVICE_KERNEL_DRIVER 0x00000001	Layanan driver.
SERVICE_RECOGNIZER_DRIVER 0x00000008	Dicadangkan.
SERVICE_WIN32_OWN_PROCESS 0x00000010	Layanan yang berjalan dalam prosesnya sendiri.
SERVICE_WIN32_SHARE_PROCESS 0x00000020	Layanan yang berbagi proses dengan satu atau beberapa layanan lainnya. Untuk informasi selengkapnya, lihat Program Layanan.

Jika Anda menentukan SERVICE_WIN32_OWN_PROCESS atau SERVICE_WIN32_SHARE_PROCESS, dan layanan berjalan dalam konteks akun LocalSystem, Anda juga dapat menentukan nilai berikut.

Nilai	Makna
SERVICE_INTERACTIVE_PROCESS 0x00000100	Layanan ini dapat berinteraksi dengan desktop. Untuk informasi selengkapnya, lihat Layanan Interaktif.

[in] dwStartType

Opsi mulai layanan. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
SERVICE_AUTO_START 0x00000002	Layanan dimulai secara otomatis oleh manajer kontrol layanan selama startup sistem. Untuk informasi selengkapnya, lihat Memulai Layanan Secara Otomatis.
SERVICE_BOOT_START 0x00000000	Driver perangkat dimulai oleh pemuat sistem. Nilai ini hanya berlaku untuk layanan driver.
SERVICE_DEMAND_START 0x00000003	Layanan dimulai oleh manajer kontrol layanan saat proses memanggil fungsi StartService . Untuk informasi selengkapnya, lihat Memulai Layanan sesuai Permintaan.
SERVICE_DISABLED 0x00000004	Layanan yang tidak dapat dimulai. Upaya untuk memulai layanan menghasilkan kode kesalahan ERROR_SERVICE_DISABLED.
SERVICE_SYSTEM_START 0x00000001	Driver perangkat yang dimulai oleh fungsi IoInitSystem . Nilai ini hanya berlaku untuk layanan driver.

[in] dwErrorControl

Tingkat keparahan kesalahan, dan tindakan yang diambil, jika layanan ini gagal dimulai. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
SERVICE_ERROR_CRITICAL 0x00000003	Program startup mencatat kesalahan dalam log peristiwa, jika memungkinkan. Jika konfigurasi terakhir yang diketahui baik sedang dimulai, operasi startup gagal. Jika tidak, sistem dimulai ulang dengan konfigurasi baik yang terakhir diketahui.
SERVICE_ERROR_IGNORE 0x00000000	Program startup mengabaikan kesalahan dan melanjutkan operasi startup.
SERVICE_ERROR_NORMAL 0x00000001	Program startup mencatat kesalahan dalam log peristiwa tetapi melanjutkan operasi startup.
SERVICE_ERROR_SEVERE 0x00000002	Program startup mencatat kesalahan dalam log peristiwa. Jika konfigurasi terakhir yang diketahui baik sedang dimulai, operasi startup berlanjut. Jika tidak, sistem dimulai ulang dengan konfigurasi terakhir yang diketahui baik.

[in, optional] lpBinaryPathName

Jalur yang sepenuhnya memenuhi syarat ke file biner layanan. Jika jalur berisi spasi, jalur harus dikutip sehingga ditafsirkan dengan benar. Misalnya, "d:\my share\myservice.exe" harus ditentukan sebagai ""d:\my share\myservice.exe"".

Jalur juga dapat menyertakan argumen untuk layanan mulai otomatis. Misalnya, "d:\myshare\myservice.exe arg1 arg2". Argumen ini diteruskan ke titik entri layanan (biasanya fungsi utama ).

Jika Anda menentukan jalur pada komputer lain, berbagi harus dapat diakses oleh akun komputer komputer komputer lokal karena ini adalah konteks keamanan yang digunakan dalam panggilan jarak jauh. Namun, persyaratan ini memungkinkan potensi kerentanan di komputer jarak jauh memengaruhi komputer lokal. Oleh karena itu, yang terbaik adalah menggunakan file lokal.

[in, optional] lpLoadOrderGroup

Nama-nama grup pengurutan beban di mana layanan ini adalah anggota. Tentukan NULL atau string kosong jika layanan bukan milik grup.

Program startup menggunakan grup pengurutan beban untuk memuat grup layanan dalam urutan tertentu sehubungan dengan grup lain. Daftar grup pengurutan beban terkandung dalam nilai registri berikut: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder

[out, optional] lpdwTagId

Penunjuk ke variabel yang menerima nilai tag yang unik dalam grup yang ditentukan dalam parameter lpLoadOrderGroup . Tentukan NULL jika Anda tidak mengubah tag yang ada.

Anda dapat menggunakan tag untuk memesan startup layanan dalam grup pemesanan beban dengan menentukan vektor pesanan tag dalam nilai registri berikut:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\GroupOrderList

Tag hanya dievaluasi untuk layanan driver yang memiliki jenis mulai SERVICE_BOOT_START atau SERVICE_SYSTEM_START .

[in, optional] lpDependencies

Penunjuk ke array ganda yang dihentikan null dari nama layanan yang dipisahkan null atau grup pengurutan beban yang harus dimulai sistem sebelum layanan ini. Tentukan NULL atau string kosong jika layanan tidak memiliki dependensi. Dependensi pada grup berarti bahwa layanan ini dapat berjalan jika setidaknya satu anggota grup berjalan setelah upaya untuk memulai semua anggota grup.

Anda harus mengawali nama grup dengan SC_GROUP_IDENTIFIER sehingga dapat dibedakan dari nama layanan, karena layanan dan grup layanan memiliki ruang nama yang sama.

[in, optional] lpServiceStartName

Nama akun tempat layanan harus berjalan. Jika jenis layanan SERVICE_WIN32_OWN_PROCESS, gunakan nama akun dalam formulirNamaPenggunaNama Domain\. Proses layanan akan masuk sebagai pengguna ini. Jika akun milik domain bawaan, Anda dapat menentukan .\UserName.

Jika parameter ini NULL, CreateService menggunakan akun LocalSystem. Jika jenis layanan menentukan SERVICE_INTERACTIVE_PROCESS, layanan harus berjalan di akun LocalSystem.

Jika parameter ini adalah NT AUTHORITY\LocalService, CreateService menggunakan akun LocalService. Jika parameternya adalah NT AUTHORITY\NetworkService, CreateService menggunakan akun NetworkService.

Proses bersama dapat berjalan sebagai pengguna mana pun.

Jika jenis layanan SERVICE_KERNEL_DRIVER atau SERVICE_FILE_SYSTEM_DRIVER, nama tersebut adalah nama objek driver yang digunakan sistem untuk memuat driver perangkat. Tentukan NULL jika driver menggunakan nama objek default yang dibuat oleh sistem I/O.

Layanan dapat dikonfigurasi untuk menggunakan akun terkelola atau akun virtual. Jika layanan dikonfigurasi untuk menggunakan akun layanan terkelola, nama tersebut adalah nama akun layanan terkelola. Jika layanan dikonfigurasi untuk menggunakan akun virtual, tentukan nama sebagai NT SERVICE\ServiceName. Untuk informasi selengkapnya tentang akun layanan terkelola dan akun virtual, lihat Panduan Langkah demi Langkah Akun Layanan.

Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Akun layanan terkelola dan akun virtual tidak didukung hingga Windows 7 dan Windows Server 2008 R2.

[in, optional] lpPassword

Kata sandi ke nama akun yang ditentukan oleh parameter lpServiceStartName . Tentukan string kosong jika akun tidak memiliki kata sandi atau jika layanan berjalan di akun LocalService, NetworkService, atau LocalSystem. Untuk informasi selengkapnya, lihat Daftar Catatan Layanan.

Jika nama akun yang ditentukan oleh parameter lpServiceStartName adalah nama akun layanan terkelola atau nama akun virtual, parameter lpPassword harus NULL.

Kata sandi diabaikan untuk layanan driver.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke layanan.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL. 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 ke database SCM tidak memiliki hak akses SC_MANAGER_CREATE_SERVICE .
ERROR_CIRCULAR_DEPENDENCY	Dependensi layanan melingkar ditentukan.
ERROR_DUPLICATE_SERVICE_NAME	Nama tampilan sudah ada dalam database manajer kontrol layanan baik sebagai nama layanan atau sebagai nama tampilan lain.
ERROR_INVALID_HANDLE	Handel ke database manajer kontrol layanan yang ditentukan tidak valid.
ERROR_INVALID_NAME	Nama layanan yang ditentukan tidak valid.
ERROR_INVALID_PARAMETER	Parameter yang ditentukan tidak valid.
ERROR_INVALID_SERVICE_ACCOUNT	Nama akun pengguna yang ditentukan dalam parameter lpServiceStartName tidak ada.
ERROR_SERVICE_EXISTS	Layanan yang ditentukan sudah ada dalam database ini.
ERROR_SERVICE_MARKED_FOR_DELETE	Layanan yang ditentukan sudah ada dalam database ini dan telah ditandai untuk dihapus.

Keterangan

Fungsi CreateService membuat objek layanan dan menginstalnya di database manajer kontrol layanan dengan membuat kunci dengan nama yang sama dengan layanan di bawah kunci registri berikut:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services

Informasi yang ditentukan oleh CreateService, ChangeServiceConfig, dan ChangeServiceConfig2 disimpan sebagai nilai di bawah kunci ini. Berikut ini adalah contoh nilai yang disimpan untuk layanan.

Nilai	Deskripsi
DependOnGroup	Grup pemesanan beban tempat layanan ini bergantung, seperti yang ditentukan oleh lpDependencies.
DependOnService	Layanan yang bergantung pada layanan ini, seperti yang ditentukan oleh lpDependencies.
Deskripsi	Deskripsi yang ditentukan oleh ChangeServiceConfig2.
DisplayName	Nama tampilan yang ditentukan oleh lpDisplayName.
ErrorControl	Kontrol kesalahan ditentukan oleh dwErrorControl.
FailureActions	Tindakan kegagalan yang ditentukan oleh ChangeServiceConfig2.
Grup	Muat grup pemesanan yang ditentukan oleh lpLoadOrderGroup. Perhatikan bahwa mengatur nilai ini dapat mengambil alih pengaturan nilai DependOnService .
ImagePath	Nama file biner, seperti yang ditentukan oleh lpBinaryPathName.
ObjectName	Nama akun yang ditentukan oleh lpServiceStartName.
Mulai	Kapan harus memulai layanan, seperti yang ditentukan oleh dwStartType.
Menandai	Pengidentifikasi tag yang ditentukan oleh lpdwTagId.
Jenis	Jenis layanan yang ditentukan oleh dwServiceType.

Program penyiapan dan layanan itu sendiri dapat membuat subkunci tambahan untuk informasi khusus layanan.

Handel yang dikembalikan hanya valid untuk proses yang disebut CreateService. Ini dapat ditutup dengan memanggil fungsi CloseServiceHandle .

Jika Anda membuat layanan yang berbagi proses, hindari fungsi panggilan dengan efek di seluruh proses, seperti ExitProcess. Selain itu, jangan membongkar DLL layanan Anda.

Contoh

Misalnya, lihat Menginstal 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 (sertakan Windows.h)
Pustaka	Advapi32.lib
DLL	Advapi32.dll