StartServiceA-Funktion (winsvc.h)

Artikel
11/20/2024

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 Service Security and Access Rights.

[in] dwNumServiceArgs

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

[in, optional] lpServiceArgVectors

Die mit Null beendeten Zeichenfolgen, die als Argumente an die ServiceMain--Funktion für den Dienst ü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 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 fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

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 SERVICE_START Zugriffsrecht.
ERROR_INVALID_HANDLE	Das Handle ist ungültig.
ERROR_PATH_NOT_FOUND	Die Dienst-Binärdatei konnte nicht gefunden werden.
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 wurde aufgrund eines Anmeldefehlers nicht gestartet. Dieser Fehler tritt auf, wenn der Dienst so konfiguriert ist, dass er unter einem Konto ausgeführt wird, das nicht über das Recht "Anmelden als Dienst" 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 StartServiceCtrlDispatcheraufgerufen, oder der Thread, der StartServiceCtrlDispatcher aufgerufen wurde, kann in einer Steuerelementhandlerfunktion blockiert werden.

Bemerkungen

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, zeichnet der Dienststeuerungs-Manager (Service Control Manager, SCM) bei Bedarf den Dienstprozess aus. Wenn der angegebene Dienst einen Prozess mit anderen Diensten teilt, ist der erforderliche Prozess möglicherweise bereits vorhanden. Die StartService--Funktion wartet nicht auf die erste Statusaktualisierung vom neuen Dienst, da dies eine Weile dauern kann. Stattdessen wird zurückgegeben, wenn der SCM Benachrichtigungen vom Dienststeuerungsverteiler empfängt, dass der ServiceMain-Thread für diesen Dienst erfolgreich erstellt wurde.

Der SCM legt die folgenden Standardwerte fest, bevor sie von StartService-zurückgegeben werden:

Der aktuelle Status des Diensts wird auf SERVICE_START_PENDING festgelegt.
Die akzeptierten Steuerelemente sind auf "none" (Null) festgelegt.
Der CheckPoint-Wert ist auf Null festgelegt.
Die WaitHint-Zeit ist auf 2 Sekunden festgelegt.

Der aufrufende Prozess kann ermitteln, ob der neue Dienst seine Initialisierung abgeschlossen hat, indem er die QueryServiceStatus- Funktion regelmäßig aufruft, um den Status des Diensts abzufragen.

Ein Dienst kann StartService- während der Initialisierung nicht aufrufen. Der Grund dafür ist, dass die 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-blockiert StartService- 30 Sekunden, wenn ein Dienst beschäftigt ist, um einen Steuerelementcode zu behandeln. Wenn der Beschäftigt-Dienst beim Ablauf des Timeouts immer noch nicht von der Handlerfunktion zurückgegeben wurde, schlägt StartService- mit ERROR_SERVICE_REQUEST_TIMEOUT fehl. Dies liegt daran, dass der SCM jeweils nur eine Dienststeuerungsbenachrichtigung verarbeitet.

Beispiele

Ein Beispiel finden Sie unter Starten eines Dienst-.

Anmerkung

Der winsvc.h-Header definiert StartService als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winsvc.h (enthalten Windows.h)
Library	Advapi32.lib
DLL-	Advapi32.dll