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
SERVICE_ADAPTER
0x00000004
Reserviert.
SERVICE_FILE_SYSTEM_DRIVER
0x00000002
Dateisystemtreiberdienst.
SERVICE_KERNEL_DRIVER
0x00000001
Treiberdienst.
SERVICE_RECOGNIZER_DRIVER
0x00000008
Reserviert.
SERVICE_WIN32_OWN_PROCESS
0x00000010
Dienst, der in einem eigenen Prozess ausgeführt wird.
SERVICE_WIN32_SHARE_PROCESS
0x00000020
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
SERVICE_INTERACTIVE_PROCESS
0x00000100
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
SERVICE_AUTO_START
0x00000002
Ein Dienst, der während des Systemstarts automatisch vom Dienststeuerungs-Manager gestartet wird. Weitere Informationen finden Sie unter Automatisches Starten von Diensten.
SERVICE_BOOT_START
0x00000000
Ein Gerätetreiber, der vom Systemladeprogramm gestartet wird. Dieses Wert ist nur für Treiberdienste gültig.
SERVICE_DEMAND_START
0x00000003
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.
SERVICE_DISABLED
0x00000004
Ein Dienst, der nicht gestartet werden kann. Versuche, den Dienst zu starten, führen zum Fehlercode ERROR_SERVICE_DISABLED.
SERVICE_SYSTEM_START
0x00000001
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.

Wert Bedeutung
SERVICE_ERROR_CRITICAL
0x00000003
Das Startprogramm protokolliert den Fehler nach Möglichkeit im Ereignisprotokoll. Wenn diese Konfiguration gestartet wird, schlägt der Startvorgang fehl. Andernfalls wird das System mit der zuletzt bekannten guten Konfiguration neu gestartet.
SERVICE_ERROR_IGNORE
0x00000000
Das Startprogramm ignoriert den Fehler und setzt den Startvorgang fort.
SERVICE_ERROR_NORMAL
0x00000001
Das Startprogramm protokolliert den Fehler im Ereignisprotokoll, setzt den Startvorgang jedoch fort.
SERVICE_ERROR_SEVERE
0x00000002
Das Startprogramm protokolliert den Fehler im Ereignisprotokoll. Wenn die letzte als fehlerfreie Konfiguration gestartet wird, wird der Startvorgang fortgesetzt. Andernfalls wird das System mit der letzten als fehlerfrei bekannten Konfiguration neu gestartet.

[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
ERROR_ACCESS_DENIED
Das Handle für die SCM-Datenbank verfügt nicht über das zugriffsrecht SC_MANAGER_CREATE_SERVICE .
ERROR_CIRCULAR_DEPENDENCY
Es wurde eine Zirkeldienstabhängigkeit angegeben.
ERROR_DUPLICATE_SERVICE_NAME
Der Anzeigename ist bereits als Dienstname oder als anderer Anzeigename in der Datenbank des Dienststeuerungs-Managers vorhanden.
ERROR_INVALID_HANDLE
Das Handle für die angegebene Dienststeuerungs-Manager-Datenbank ist ungültig.
ERROR_INVALID_NAME
Der angegebene Dienstname ist ungültig.
ERROR_INVALID_PARAMETER
Ein angegebener Parameter ist ungültig.
ERROR_INVALID_SERVICE_ACCOUNT
Der im parameter lpServiceStartName angegebene Benutzerkontoname ist nicht vorhanden.
ERROR_SERVICE_EXISTS
Der angegebene Dienst ist bereits in dieser Datenbank vorhanden.
ERROR_SERVICE_MARKED_FOR_DELETE
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

ChangeServiceConfig

ChangeServiceConfig2

CloseServiceHandle

ControlService

DeleteService

EnumDependentServices

OpenSCManager

QueryServiceConfig

QueryServiceDynamicInformation

QueryServiceObjectSecurity

QueryServiceStatusEx

Schrittweise Anleitung zu Dienstkonten

Dienstfunktionen

Dienstinstallation, -entfernung und -enumeration

SetServiceObjectSecurity

Startservice