CreateServiceW-Funktion (winsvc.h)
Erstellt ein Dienstobjekt und fügt es der angegebenen Dienststeuerungs-Manager-Datenbank hinzu.
Syntax
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
Ein Handle für die Datenbank des Dienststeuerungs-Managers. Dieses Handle wird von der OpenSCManager-Funktion zurückgegeben und muss über das zugriffsrecht SC_MANAGER_CREATE_SERVICE verfügen. Weitere Informationen finden Sie unter Dienstsicherheit und Zugriffsrechte.
[in] lpServiceName
Der Name des zu installierenden Diensts. Die maximale Zeichenfolgenlänge beträgt 256 Zeichen. Die Datenbank des Dienststeuerungs-Managers behält die Groß-/Kleinschreibung der Zeichen bei, bei Dienstnamenvergleichen wird jedoch immer die Groß-/Kleinschreibung nicht beachtet. Schrägstrich (/) und umgekehrter Schrägstrich (\) sind keine gültigen Dienstnamenzeichen.
[in, optional] lpDisplayName
Der Anzeigename, der von Benutzeroberflächenprogrammen zur Identifizierung des Diensts verwendet werden soll. Die maximale Länge der Zeichenfolge beträgt 256 Zeichen. Der Name wird im Dienststeuerungs-Manager in Groß-/Kleinschreibung beibehalten. Bei Anzeigenamenvergleichen wird immer zwischen Groß- und Kleinschreibung unterschieden.
[in] dwDesiredAccess
Der Zugriff auf den Dienst. Vor dem Gewähren des angeforderten Zugriffs überprüft das System das Zugriffstoken des aufrufenden Prozesses. Eine Liste der Werte finden Sie unter Dienstsicherheit und Zugriffsrechte.
[in] dwServiceType
Der Diensttyp. Dieser Parameter kann einen der folgenden Werte annehmen.
| Wert | Bedeutung |
|---|---|
|
Reserviert. |
|
Dateisystemtreiberdienst. |
|
Treiberdienst. |
|
Reserviert. |
|
Dienst, der in einem eigenen Prozess ausgeführt wird. |
|
Dienst, der einen Prozess mit einem oder mehreren anderen Diensten gemeinsam verwendet. Weitere Informationen finden Sie unter Dienstprogramme. |
Wenn Sie entweder SERVICE_WIN32_OWN_PROCESS oder SERVICE_WIN32_SHARE_PROCESS angeben und der Dienst im Kontext des LocalSystem-Kontos ausgeführt wird, können Sie auch den folgenden Wert angeben.
| Wert | Bedeutung |
|---|---|
|
Der Dienst kann mit dem Desktop interagieren.
Weitere Informationen finden Sie unter Interactive Services. |
[in] dwStartType
Die Startoptionen für den Dienst. Dieser Parameter kann einen der folgenden Werte annehmen.
| Wert | Bedeutung |
|---|---|
|
Ein Dienst, der während des Systemstarts automatisch vom Dienststeuerungs-Manager gestartet wird. Weitere Informationen finden Sie unter Automatisches Starten von Diensten. |
|
Ein Gerätetreiber, der vom Systemladeprogramm gestartet wird. Dieses Wert ist nur für Treiberdienste gültig. |
|
Ein Dienst, der vom Dienststeuerungs-Manager gestartet wird, wenn ein Prozess die StartService-Funktion aufruft. Weitere Informationen finden Sie unter Starten von Diensten bei Bedarf. |
|
Ein Dienst, der nicht gestartet werden kann. Versuche, den Dienst zu starten, führen zum Fehlercode ERROR_SERVICE_DISABLED. |
|
Ein Gerätetreiber, der von der IoInitSystem-Funktion gestartet wird. Dieses Wert ist nur für Treiberdienste gültig. |
[in] dwErrorControl
Der Schweregrad des Fehlers und die ausgeführte Aktion, wenn dieser Dienst nicht gestartet werden kann. Dieser Parameter kann einen der folgenden Werte annehmen.
[in, optional] lpBinaryPathName
Der vollqualifizierte Pfad zur Binärdatei des Diensts. Wenn der Pfad ein Leerzeichen enthält, muss er in Anführungszeichen gesetzt werden, damit er richtig interpretiert wird. Beispielsweise sollte "d:\my share\myservice.exe" als ""d:\my share\myservice.exe" angegeben werden.
Der Pfad kann auch Argumente für einen Dienst für den automatischen Start enthalten. Beispiel: "d:\myshare\myservice.exe arg1 arg2". Diese Argumente werden an den Diensteinstiegspunkt (in der Regel die Standard-Funktion) übergeben.
Wenn Sie einen Pfad auf einem anderen Computer angeben, muss für das Computerkonto des lokalen Computers auf die Freigabe zugegriffen werden, da dies der Sicherheitskontext ist, der im Remoteaufruf verwendet wird. Diese Anforderung ermöglicht jedoch, dass sich potenzielle Sicherheitsrisiken auf dem Remotecomputer auf den lokalen Computer auswirken. Daher ist es am besten, eine lokale Datei zu verwenden.
[in, optional] lpLoadOrderGroup
Die Namen der Lastreihenfolgegruppe, der dieser Dienst angehört. Geben Sie NULL oder eine leere Zeichenfolge an, wenn der Dienst nicht zu einer Gruppe gehört.
Das Startprogramm verwendet Ladereihenfolgegruppen, um Gruppen von Diensten in einer angegebenen Reihenfolge in Bezug auf die anderen Gruppen zu laden. Die Liste der Lastreihenfolgegruppen ist im folgenden Registrierungswert enthalten: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder
[out, optional] lpdwTagId
Ein Zeiger auf eine Variable, die einen Tagwert empfängt, der in der gruppe eindeutig ist, die im parameter lpLoadOrderGroup angegeben ist. Geben Sie NULL an, wenn Sie das vorhandene Tag nicht ändern.
Sie können ein Tag zum Bestellen des Dienststarts innerhalb einer Ladereihenfolgegruppe verwenden, indem Sie einen Tagreihenfolgevektor im folgenden Registrierungswert angeben:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\GroupOrderList
Tags werden nur für Treiberdienste ausgewertet, die über SERVICE_BOOT_START - oder SERVICE_SYSTEM_START Starttypen verfügen.
[in, optional] lpDependencies
Ein Zeiger auf ein double-NULL-beendetes Array mit null getrennten Namen von Diensten oder Lastenreihenfolgegruppen, die das System vor diesem Dienst starten muss. Geben Sie NULL oder eine leere Zeichenfolge an, wenn der Dienst keine Abhängigkeiten aufweist. „Abhängigkeit von einer Gruppe“ bedeutet, dass dieser Dienst ausgeführt werden kann, wenn nach einem Versuch, alle Mitglieder der Gruppe zu starten, mindestens ein Mitglied der Gruppe ausgeführt wird.
Sie müssen Gruppennamen mit SC_GROUP_IDENTIFIER präfixieren, damit sie von einem Dienstnamen unterschieden werden können, da Dienste und Dienstgruppen denselben Namensraum verwenden.
[in, optional] lpServiceStartName
Der Name des Kontos, unter dem der Dienst ausgeführt werden soll. Wenn der Diensttyp SERVICE_WIN32_OWN_PROCESS ist, verwenden Sie einen Kontonamen im Format Domänenname\Benutzername. Der Dienstprozess wird als dieser Benutzer angemeldet. Wenn das Konto zur integrierten Domäne gehört, können Sie .\UserName angeben.
Wenn dieser Parameter NULL ist, verwendet CreateService das LocalSystem-Konto. Wenn der Diensttyp SERVICE_INTERACTIVE_PROCESS angibt, muss der Dienst im LocalSystem-Konto ausgeführt werden.
Wenn dieser Parameter NT AUTHORITY\LocalService ist, verwendet CreateService das LocalService-Konto. Wenn der Parameter NT AUTHORITY\NetworkService ist, verwendet CreateService das NetworkService-Konto.
Ein freigegebener Prozess kann wie ein beliebiger Benutzer ausgeführt werden.
Wenn der Diensttyp SERVICE_KERNEL_DRIVER oder SERVICE_FILE_SYSTEM_DRIVER ist, ist der Name der Treiberobjektname, den das System zum Laden des Gerätetreibers verwendet. Geben Sie NULL an, wenn der Treiber einen Standardobjektnamen verwenden soll, der vom E/A-System erstellt wurde.
Ein Dienst kann so konfiguriert werden, dass er ein verwaltetes Konto oder ein virtuelles Konto verwendet. Wenn der Dienst für die Verwendung eines verwalteten Dienstkontos konfiguriert ist, lautet der Name des verwalteten Dienstkontos. Wenn der Dienst für die Verwendung eines virtuellen Kontos konfiguriert ist, geben Sie den Namen NT SERVICE\ServiceName an. Weitere Informationen zu verwalteten Dienstkonten und virtuellen Konten finden Sie in der schrittweisen Anleitung zu Dienstkonten.
Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Verwaltete Dienstkonten und virtuelle Konten werden erst unter Windows 7 und Windows Server 2008 R2 unterstützt.
[in, optional] lpPassword
Das Kennwort für den Kontonamen, der durch den lpServiceStartName-Parameter angegeben wird. Geben Sie eine leere Zeichenfolge an, wenn das Konto über kein Kennwort verfügt oder wenn der Dienst im LocalService-, NetworkService- oder LocalSystem-Konto ausgeführt wird. Weitere Informationen finden Sie unter Diensteintragsliste.
Wenn der durch den lpServiceStartName-Parameter angegebene Kontoname der Name eines verwalteten Dienstkontos oder eines virtuellen Kontos ist, muss der lpPassword-Parameter NULL sein.
Kennwörter werden für Treiberdienste ignoriert.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für den Dienst.
Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.
Die folgenden Fehlercodes können vom Dienststeuerungs-Manager festgelegt werden. Andere Fehlercodes können von den Registrierungsfunktionen festgelegt werden, die vom Dienststeuerungs-Manager aufgerufen werden.
| Rückgabecode | Beschreibung |
|---|---|
|
Das Handle für die SCM-Datenbank verfügt nicht über das zugriffsrecht SC_MANAGER_CREATE_SERVICE . |
|
Es wurde eine Zirkeldienstabhängigkeit angegeben. |
|
Der Anzeigename ist bereits als Dienstname oder als anderer Anzeigename in der Datenbank des Dienststeuerungs-Managers vorhanden. |
|
Das Handle für die angegebene Dienststeuerungs-Manager-Datenbank ist ungültig. |
|
Der angegebene Dienstname ist ungültig. |
|
Ein angegebener Parameter ist ungültig. |
|
Der im parameter lpServiceStartName angegebene Benutzerkontoname ist nicht vorhanden. |
|
Der angegebene Dienst ist bereits in dieser Datenbank vorhanden. |
|
Der angegebene Dienst ist bereits in dieser Datenbank vorhanden und wurde zum Löschen markiert. |
Hinweise
Die CreateService-Funktion erstellt ein Dienstobjekt und installiert es in der Datenbank des Dienststeuerungs-Managers, indem sie einen Schlüssel mit demselben Namen wie der Dienst unter dem folgenden Registrierungsschlüssel erstellt:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services
Die von CreateService, ChangeServiceConfig und ChangeServiceConfig2 angegebenen Informationen werden als Werte unter diesem Schlüssel gespeichert. Im Folgenden sind Beispiele für Werte aufgeführt, die für einen Dienst gespeichert sind.
| Wert | BESCHREIBUNG |
|---|---|
| DependOnGroup | Lastenreihenfolgegruppen, von denen dieser Dienst abhängig ist, wie in lpDependencies angegeben. |
| DependOnService | Dienste, von denen dieser Dienst abhängig ist, wie von lpDependencies angegeben. |
| Beschreibung | Beschreibung, die von ChangeServiceConfig2 angegeben wird. |
| DisplayName | Anzeigename angegeben durch lpDisplayName. |
| ErrorControl | Fehlersteuerung durch dwErrorControl angegeben. |
| FailureActions | Fehleraktionen, die von ChangeServiceConfig2 angegeben werden. |
| Gruppe | Laden Sie die von lpLoadOrderGroup angegebene Reihenfolgesgruppe. Beachten Sie, dass das Festlegen dieses Werts die Einstellung des DependOnService-Werts außer Kraft setzen kann. |
| ImagePath | Name der Binärdatei, wie von lpBinaryPathName angegeben. |
| ObjectName | Kontoname angegeben durch lpServiceStartName. |
| Starten | Wann der Dienst gestartet werden soll, wie in dwStartType angegeben. |
| Tag | Tagbezeichner, der von lpdwTagId angegeben wird. |
| Typ | Diensttyp, der von dwServiceType angegeben wird. |
Setupprogramme und der Dienst selbst können zusätzliche Unterschlüssel für dienstspezifische Informationen erstellen.
Das zurückgegebene Handle ist nur für den Prozess gültig, der CreateService aufgerufen hat. Sie kann durch Aufrufen der CloseServiceHandle-Funktion geschlossen werden.
Wenn Sie Dienste erstellen, die einen Prozess gemeinsam nutzen, vermeiden Sie das Aufrufen von Funktionen mit prozessweiten Effekten, z. B. ExitProcess. Darüber hinaus entladen Sie ihre Dienst-DLL nicht.
Beispiele
Ein Beispiel finden Sie unter Installieren eines Diensts.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winsvc.h (einschließen von Windows.h) |
| Bibliothek | Advapi32.lib |
| DLL | Advapi32.dll |
Weitere Informationen
QueryServiceDynamicInformation
Schrittweise Anleitung zu Dienstkonten