StartServiceA-Funktion (winsvc.h)

Artikel
08/27/2023

Startet einen Dienst.

Syntax

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

Parameter

[in] hService

Ein Handle für den Dienst. Dieses Handle wird von der OpenService - oder CreateService-Funktion zurückgegeben und muss über das SERVICE_START-Zugriffsrecht verfügen. Weitere Informationen finden Sie unter Dienstsicherheit und Zugriffsrechte.

[in] dwNumServiceArgs

Die Anzahl der Zeichenfolgen im LpServiceArgVectors-Array . Wenn lpServiceArgVectors NULL ist, kann dieser Parameter null sein.

[in, optional] lpServiceArgVectors

Die NULL-beendeten Zeichenfolgen, die an die ServiceMain-Funktion für den Dienst als Argumente übergeben werden sollen. Wenn keine Argumente vorhanden sind, kann dieser Parameter NULL sein. Andernfalls ist das erste Argument (lpServiceArgVectors[0]) der Name des Diensts, gefolgt von allen zusätzlichen Argumenten (lpServiceArgVectors[1] bis lpServiceArgVectors[dwNumServiceArgs-1]).

Treiberdienste erhalten diese Argumente nicht.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, 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 können von den Registrierungsfunktionen festgelegt werden, die vom Dienststeuerungs-Manager aufgerufen werden.

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Das Handle verfügt nicht über das Zugriffsrecht SERVICE_START.
ERROR_INVALID_HANDLE	Das Handle ist ungültig.
ERROR_PATH_NOT_FOUND	Die Binärdatei des Diensts wurde nicht gefunden.
ERROR_SERVICE_ALREADY_RUNNING	Eine Instanz des Diensts wird bereits ausgeführt.
ERROR_SERVICE_DATABASE_LOCKED	Die Datenbank ist gesperrt.
ERROR_SERVICE_DEPENDENCY_DELETED	Der Dienst hängt von einem Dienst ab, der nicht vorhanden ist oder zum Löschen markiert wurde.
ERROR_SERVICE_DEPENDENCY_FAIL	Der Dienst hängt von einem anderen Dienst ab, der nicht gestartet werden konnte.
ERROR_SERVICE_DISABLED	Der Dienst wurde deaktiviert.
ERROR_SERVICE_LOGON_FAILED	Der Dienst konnte wegen einer fehlerhaften Anmeldung nicht gestartet werden. Dieser Fehler tritt auf, wenn der Dienst für die Ausführung unter einem Konto konfiguriert ist, das nicht über das Recht "Als Dienst anmelden" verfügt.
ERROR_SERVICE_MARKED_FOR_DELETE	Der Dienst wurde zum Löschen markiert.
ERROR_SERVICE_NO_THREAD	Für den Dienst konnte kein Thread erstellt werden.
ERROR_SERVICE_REQUEST_TIMEOUT	Der Prozess für den Dienst wurde gestartet, aber er hat nicht StartServiceCtrlDispatcher aufgerufen, oder der Thread, der StartServiceCtrlDispatcher aufgerufen hat, kann in einer Steuerelementhandlerfunktion blockiert werden.

Hinweise

Wenn ein Treiberdienst gestartet wird, wird die StartService-Funktion erst zurückgegeben, wenn der Gerätetreiber die Initialisierung abgeschlossen hat.

Wenn ein Dienst gestartet wird, führt der Dienststeuerungs-Manager (SCM) ggf. den Dienstprozess aus. Wenn der angegebene Dienst einen Prozess für andere Dienste gemeinsam verwendet, ist der erforderliche Prozess möglicherweise bereits vorhanden. Die StartService-Funktion wartet nicht auf die erste status Aktualisierung des neuen Diensts, da dies eine Weile dauern kann. Stattdessen wird zurückgegeben, wenn der SCM vom Dienststeuerungsverteiler eine Benachrichtigung erhält, dass der ServiceMain-Thread für diesen Dienst erfolgreich erstellt wurde.

Der SCM legt die folgenden Standardwerte status fest, bevor von StartService zurückgegeben wird:

Der aktuelle Status des Diensts ist auf SERVICE_START_PENDING festgelegt.
Akzeptierte Steuerelemente sind auf keine (null) festgelegt.
Der CheckPoint-Wert ist auf 0 (null) festgelegt.
Die WaitHint-Zeit ist auf 2 Sekunden festgelegt.

Der aufrufende Prozess kann bestimmen, ob der neue Dienst seine Initialisierung abgeschlossen hat, indem die QueryServiceStatus-Funktion regelmäßig aufgerufen wird, um die status des Diensts abzufragen.

Ein Dienst kann StartService während der Initialisierung nicht aufrufen. Der Grund dafür ist, dass der SCM die Dienststeuerungsdatenbank während der Initialisierung sperrt, sodass ein Aufruf von StartService blockiert wird. Nachdem der Dienst dem SCM gemeldet hat, dass er erfolgreich gestartet wurde, kann er StartService aufrufen.

Wie bei ControlService wird StartService für 30 Sekunden blockiert, wenn ein Dienst mit der Verarbeitung eines Steuerelementcodes beschäftigt ist. Wenn der ausgelastete Dienst immer noch nicht von seiner Handlerfunktion zurückgegeben wurde, wenn das Timeout abläuft, schlägt StartService mit ERROR_SERVICE_REQUEST_TIMEOUT fehl. Dies liegt daran, dass das SCM jeweils nur eine Dienststeuerungsbenachrichtigung verarbeitet.

Beispiele

Ein Beispiel finden Sie unter Starten eines Diensts.

Hinweis

Der winsvc.h-Header definiert StartService als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winsvc.h (windows.h einschließen)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll