ControlService-Funktion (winsvc.h)

Artikel
03/13/2024

Sendet einen Steuerelementcode an einen Dienst.

Wenn Sie beim Beenden eines Diensts zusätzliche Informationen angeben möchten, verwenden Sie die ControlServiceEx-Funktion .

Syntax

BOOL ControlService(
  [in]  SC_HANDLE        hService,
  [in]  DWORD            dwControl,
  [out] LPSERVICE_STATUS lpServiceStatus
);

Parameter

[in] hService

Ein Handle für den Dienst. Dieses Handle wird von der OpenService- oder CreateService-Funktion zurückgegeben. Die für dieses Handle erforderlichen Zugriffsrechte hängen vom angeforderten dwControl-Code ab.

[in] dwControl

Bei diesem Parameter kann es sich um einen der folgenden Steuercodes handeln.

Steuerungscode	Bedeutung
SERVICE_CONTROL_CONTINUE 0x00000003	Benachrichtigt einen angehaltenen Dienst, dass er fortgesetzt werden soll. Das hService-Handle muss über das zugriffsrecht SERVICE_PAUSE_CONTINUE verfügen.
SERVICE_CONTROL_INTERROGATE 0x00000004	Benachrichtigt einen Dienst, dass er seine aktuellen status Informationen an den Dienststeuerungs-Manager melden soll. Das hService-Handle muss über das zugriffsrecht SERVICE_INTERROGATE verfügen. Beachten Sie, dass dieses Steuerelement im Allgemeinen nicht nützlich ist, da der SCM den aktuellen Status des Diensts kennt.
SERVICE_CONTROL_NETBINDADD 0x00000007	Benachrichtigt einen Netzwerkdienst, dass eine neue Komponente für die Bindung vorhanden ist. Das hService-Handle muss über das zugriffsrecht SERVICE_PAUSE_CONTINUE verfügen. Dieser Kontrollcode ist jedoch veraltet. verwenden Sie stattdessen Plug & Play Funktionalität.
SERVICE_CONTROL_NETBINDDISABLE 0x0000000A	Benachrichtigt einen Netzwerkdienst, dass eine seiner Bindungen deaktiviert wurde. Das hService-Handle muss über das zugriffsrecht SERVICE_PAUSE_CONTINUE verfügen. Dieser Kontrollcode ist jedoch veraltet. verwenden Sie stattdessen Plug & Play Funktionalität.
SERVICE_CONTROL_NETBINDENABLE 0x00000009	Benachrichtigt einen Netzwerkdienst, dass eine deaktivierte Bindung aktiviert wurde. Das hService-Handle muss über das zugriffsrecht SERVICE_PAUSE_CONTINUE verfügen. Dieser Kontrollcode ist jedoch veraltet. verwenden Sie stattdessen Plug & Play Funktionalität.
SERVICE_CONTROL_NETBINDREMOVE 0x00000008	Benachrichtigt einen Netzwerkdienst, dass eine Komponente für die Bindung entfernt wurde. Das hService-Handle muss über das zugriffsrecht SERVICE_PAUSE_CONTINUE verfügen. Dieser Kontrollcode ist jedoch veraltet. verwenden Sie stattdessen Plug & Play Funktionalität.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Benachrichtigt einen Dienst, dass seine Startparameter geändert wurden. Das hService-Handle muss über das zugriffsrecht SERVICE_PAUSE_CONTINUE verfügen.
SERVICE_CONTROL_PAUSE 0x00000002	Benachrichtigt einen Dienst, dass er angehalten werden soll. Das hService-Handle muss über das zugriffsrecht SERVICE_PAUSE_CONTINUE verfügen.
SERVICE_CONTROL_STOP 0x00000001	Benachrichtigt einen Dienst, dass er beendet werden soll. Das hService-Handle muss über das zugriffsrecht SERVICE_STOP verfügen. Nachdem Sie die Beendigungsanforderung an einen Dienst gesendet haben, sollten Sie keine anderen Steuerelemente an den Dienst senden.

Dieser Wert kann auch ein benutzerdefinierter Steuerelementcode sein, wie in der folgenden Tabelle beschrieben.

Steuerungscode	Bedeutung
Bereich 128 bis 255	Der Dienst definiert die Aktion, die dem Steuerelementcode zugeordnet ist. Das hService-Handle muss über das zugriffsrecht SERVICE_USER_DEFINED_CONTROL verfügen.

[out] lpServiceStatus

Ein Zeiger auf eine SERVICE_STATUS-Struktur, die die neuesten Informationen zum Dienst status empfängt. Die zurückgegebenen Informationen spiegeln die letzten status wider, die der Dienst dem Dienststeuerungs-Manager gemeldet hat.

Der Dienststeuerungs-Manager füllt die Struktur nur aus, wenn GetLastError einen der folgenden Fehlercodes zurückgibt: NO_ERROR, ERROR_INVALID_SERVICE_CONTROL, ERROR_SERVICE_CANNOT_ACCEPT_CTRL oder ERROR_SERVICE_NOT_ACTIVE. Andernfalls wird die Struktur nicht ausgefüllt.

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 Fehlercodes 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 erforderliche Zugriffsrecht.
ERROR_DEPENDENT_SERVICES_RUNNING	Der Dienst kann nicht beendet werden, da andere ausgeführte Dienste davon abhängig sind.
ERROR_INVALID_HANDLE	Das angegebene Handle wurde nicht mit CreateService oder OpenService abgerufen, oder das Handle ist nicht mehr gültig.
ERROR_INVALID_PARAMETER	Der angeforderte Steuerelementcode ist nicht definiert.
ERROR_INVALID_SERVICE_CONTROL	Der angeforderte Steuerungscode ist nicht gültig, oder es ist für den Dienst nicht akzeptabel.
ERROR_SERVICE_CANNOT_ACCEPT_CTRL	Der angeforderte Steuerungscode kann nicht an den Dienst gesendet werden, da der Status des Diensts SERVICE_STOPPED, SERVICE_START_PENDING oder SERVICE_STOP_PENDING ist.
ERROR_SERVICE_NOT_ACTIVE	Der Dienst wurde nicht gestartet.
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.
ERROR_SHUTDOWN_IN_PROGRESS	Das System wird heruntergefahren.

Hinweise

Die ControlService-Funktion fordert den Dienststeuerungs-Manager (SCM) auf, den angeforderten Steuerungscode an den Dienst zu senden. Der SCM sendet den Code, wenn der Dienst angegeben hat, dass er den Code akzeptiert und sich in einem Zustand befindet, in dem ein Steuerelementcode an ihn gesendet werden kann.

Das SCM verarbeitet Dienststeuerungsbenachrichtigungen seriell– es wartet, bis ein Dienst die Verarbeitung einer Dienststeuerungsbenachrichtigung abgeschlossen hat, bevor die nächste gesendet wird. Aus diesem Grund wird ein Aufruf von ControlService 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 ControlService mit ERROR_SERVICE_REQUEST_TIMEOUT fehl.

Um einen Dienst zu beenden und zu starten, ist ein Sicherheitsdeskriptor erforderlich, mit dem Sie dies tun können. Die Standardsicherheitsbeschreibung ermöglicht dem LocalSystem-Konto und Mitgliedern der Gruppen Administratoren und Power Users das Beenden und Starten von Diensten. Informationen zum Ändern der Sicherheitsbeschreibung eines Diensts finden Sie unter Ändern der DACL für einen Dienst.

Die QueryServiceStatusEx-Funktion gibt eine SERVICE_STATUS_PROCESS-Struktur zurück, deren dwCurrentState - und dwControlsAccepted-Member den aktuellen Zustand und die von einem ausgeführten Dienst akzeptierten Steuerelemente angeben. Alle ausgeführten Dienste akzeptieren standardmäßig den SERVICE_CONTROL_INTERROGATE-Steuerelementcode. Treiber akzeptieren keine anderen Steuercodes als SERVICE_CONTROL_STOP und SERVICE_CONTROL_INTERROGATE. Jeder Dienst gibt die anderen Steuerelementcodes an, die er akzeptiert, wenn er die SetServiceStatus-Funktion aufruft, um seine status zu melden. Ein Dienst sollte diese Codes immer akzeptieren, wenn er ausgeführt wird, unabhängig davon, was er tut.

Die folgende Tabelle zeigt die Aktion des SCM in jedem der möglichen Dienstzustände.

Dienstzustand	Beenden	Weitere Steuermöglichkeiten
STOPPED	(c)	(c)
STOP_PENDING	b)	b)
START_PENDING	a)	b)
AUSGEFÜHRTE	a)	a)
CONTINUE_PENDING	a)	a)
PAUSE_PENDING	a)	a)
ANGEHALTEN	a)	a)

a): Wenn der Dienst diesen Steuerungscode akzeptiert, senden Sie die Anforderung an den Dienst. Andernfalls gibt ControlService null und GetLastErrorERROR_INVALID_SERVICE_CONTROL zurück.
b): Der Dienst befindet sich nicht in einem Zustand, in dem ein Steuerelement an ihn gesendet werden kann, sodass ControlService null und GetLastErrorERROR_SERVICE_CANNOT_ACCEPT_CTRL zurückgibt.
(c): Der Dienst ist nicht aktiv, sodass ControlService null und GetLastErrorERROR_SERVICE_NOT_ACTIVE zurückgibt.

Beispiele

Ein Beispiel finden Sie unter Beenden 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