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.

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.

[in] dwStartType

Die Startoptionen für den Dienst. Dieser Parameter kann einen der folgenden Werte annehmen.

[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.

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.

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

Weitere Informationen

ChangeServiceConfig

ChangeServiceConfig2

CloseServiceHandle

ControlService

DeleteService

EnumDependentServices

OpenSCManager

QueryServiceConfig

QueryServiceDynamicInformation

QueryServiceObjectSecurity

QueryServiceStatusEx

Schrittweise Anleitung zu Dienstkonten

Dienstfunktionen

Dienstinstallation, -entfernung und -enumeration

SetServiceObjectSecurity

Startservice