ControlServiceExA-Funktion (winsvc.h)

Artikel
08/27/2023

Sendet einen Steuerelementcode an einen Dienst.

Syntax

BOOL ControlServiceExA(
  [in]      SC_HANDLE hService,
  [in]      DWORD     dwControl,
  [in]      DWORD     dwInfoLevel,
  [in, out] PVOID     pControlParams
);

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-and-Play-Funktionen.
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-and-Play-Funktionen.
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-and-Play-Funktionen.
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-and-Play-Funktionen.
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 Parameter 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.

[in] dwInfoLevel

Die Informationsebene für die Dienststeuerungsparameter. Dieser Parameter muss auf SERVICE_CONTROL_STATUS_REASON_INFO (1) festgelegt werden.

[in, out] pControlParams

Ein Zeiger auf die Dienststeuerungsparameter. Wenn dwInfoLevel SERVICE_CONTROL_STATUS_REASON_INFO ist, ist dieser Member ein Zeiger auf eine SERVICE_CONTROL_STATUS_REASON_PARAMS-Struktur .

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 im dwControl-Parameter ist nicht definiert, oder dwControl ist SERVICE_CONTROL_STOP, aber die Elemente dwReason oder pszComment der SERVICE_CONTROL_STATUS_REASON_PARAMS-Struktur sind ungültig.
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 ControlServiceEx-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 darauf, dass ein Dienst die Verarbeitung einer Dienststeuerungsbenachrichtigung abgeschlossen hat, bevor der nächste gesendet wird. Aus diesem Grund blockiert ein Aufruf von ControlServiceEx für 30 Sekunden, 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 ControlServiceEx 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 es dem LocalSystem-Konto und Mitgliedern der Gruppen Administratoren und Power Users, Dienste zu beenden und zu starten. 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 Steuercodes 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)
RUNNING	a)	a)
CONTINUE_PENDING	a)	a)
PAUSE_PENDING	a)	a)
PAUSED	a)	a)

a): Wenn der Dienst diesen Kontrollcode akzeptiert, senden Sie die Anforderung an den Dienst. Andernfalls gibt ControlServiceEx 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 ControlServiceEx null und GetLastErrorERROR_SERVICE_CANNOT_ACCEPT_CTRL zurückgibt.
(c): Der Dienst ist nicht aktiv, sodass ControlServiceEx null und GetLastErrorERROR_SERVICE_NOT_ACTIVE zurückgibt.

Hinweis

Der winsvc.h-Header definiert ControlServiceEx 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 Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winsvc.h (windows.h einschließen)
Bibliothek	Advapi32.lib
DLL	Advapi32.dll