ControlServiceExA-Funktion (winsvc.h)

Artikel
11/20/2024

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 Zugriffs berechtigungen hängen vom angeforderten dwControl Code ab.

[in] dwControl

Dieser Parameter kann einer der folgenden Steuerelementcodes sein.

Steuerelementcode	Bedeutung
SERVICE_CONTROL_CONTINUE 0x00000003	Benachrichtigt einen angehaltenen Dienst, dass er fortgesetzt werden soll. Der hService- Handle muss über das SERVICE_PAUSE_CONTINUE Zugriffsrecht verfügen.
SERVICE_CONTROL_INTERROGATE 0x00000004	Benachrichtigt einen Dienst, dass er seine aktuellen Statusinformationen an den Dienststeuerungs-Manager melden soll. Der hService- Handle muss über das SERVICE_INTERROGATE Zugriffsrecht verfügen. Beachten Sie, dass dieses Steuerelement in der Regel 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. Der hService- Handle muss über das SERVICE_PAUSE_CONTINUE Zugriffsrecht verfügen. Dieser Steuerelementcode ist jedoch veraltet; Verwenden Sie stattdessen Plug- und Play-Funktionen.
SERVICE_CONTROL_NETBINDDISABLE 0x0000000A	Benachrichtigt einen Netzwerkdienst, dass eine seiner Bindungen deaktiviert wurde. Der hService- Handle muss über das SERVICE_PAUSE_CONTINUE Zugriffsrecht verfügen. Dieser Steuerelementcode ist jedoch veraltet; Verwenden Sie stattdessen Plug- und Play-Funktionen.
SERVICE_CONTROL_NETBINDENABLE 0x00000009	Benachrichtigt einen Netzwerkdienst, dass eine deaktivierte Bindung aktiviert wurde. Der hService- Handle muss über das SERVICE_PAUSE_CONTINUE Zugriffsrecht verfügen. Dieser Steuerelementcode ist jedoch veraltet; Verwenden Sie stattdessen Plug- und Play-Funktionen.
SERVICE_CONTROL_NETBINDREMOVE 0x00000008	Benachrichtigt einen Netzwerkdienst, dass eine Komponente für die Bindung entfernt wurde. Der hService- Handle muss über das SERVICE_PAUSE_CONTINUE Zugriffsrecht verfügen. Dieser Steuerelementcode ist jedoch veraltet; Verwenden Sie stattdessen Plug- und Play-Funktionen.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Benachrichtigt einen Dienst, dass sich die Startparameter geändert haben. Der hService- Handle muss über das SERVICE_PAUSE_CONTINUE Zugriffsrecht verfügen.
SERVICE_CONTROL_PAUSE 0x00000002	Benachrichtigt einen Dienst, dass er angehalten werden soll. Der hService- Handle muss über das SERVICE_PAUSE_CONTINUE Zugriffsrecht verfügen.
SERVICE_CONTROL_STOP 0x00000001	Benachrichtigt einen Dienst darüber, dass er beendet werden soll. Der hService- Handle muss über das SERVICE_STOP Zugriffsrecht verfügen. Nachdem Sie die Stoppanforderung 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.

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

[in] dwInfoLevel

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

[in, out] pControlParams

Ein Zeiger auf die Parameter des Dienststeuerelements. Wenn dwInfoLevel- SERVICE_CONTROL_STATUS_REASON_INFO ist, ist dieses Element 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 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 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 der 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 dwReason oder pszComment Member der SERVICE_CONTROL_STATUS_REASON_PARAMS Struktur sind ungültig.
ERROR_INVALID_SERVICE_CONTROL	Der angeforderte Steuerelementcode ist ungültig oder für den Dienst nicht akzeptabel.
ERROR_SERVICE_CANNOT_ACCEPT_CTRL	Der angeforderte Steuerelementcode kann nicht an den Dienst gesendet werden, da der Dienststatus 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 StartServiceCtrlDispatcheraufgerufen, oder der Thread, der StartServiceCtrlDispatcher aufgerufen wurde, kann in einer Steuerelementhandlerfunktion blockiert werden.
ERROR_SHUTDOWN_IN_PROGRESS	Das System wird heruntergefahren.

Bemerkungen

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

SCM verarbeitet Dienststeuerungsbenachrichtigungen auf serielle Weise – es wartet, bis ein Dienst die Verarbeitung einer Dienststeuerungsbenachrichtigung abgeschlossen hat, bevor die nächste gesendet wird. Aus diesem Grund wird ein Aufruf von ControlServiceEx 30 Sekunden blockiert, wenn ein Dienst beschäftigt ist, um einen Steuerelementcode zu verarbeiten. Wenn der beschäftigt-Dienst nach Ablauf des Timeouts immer noch nicht von der Handlerfunktion zurückgegeben wurde, schlägt ControlServiceEx- mit ERROR_SERVICE_REQUEST_TIMEOUT fehl.

Zum Beenden und Starten eines Diensts ist ein Sicherheitsdeskriptor erforderlich, mit dem Sie dies tun können. Der Standardmäßige Sicherheitsdeskriptor ermöglicht das LocalSystem-Kontound Mitglieder 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 Steuerelementcodes an, die er akzeptiert, wenn er den SetServiceStatus Funktion aufruft, um den 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.

Dienststatus	Aufhören	Andere Steuerelemente
ANGEHALTEN	(c)	(c)
STOP_PENDING	b)	b)
START_PENDING	a)	b)
AUSGEFÜHRTE	a)	a)
CONTINUE_PENDING	a)	a)
PAUSE_PENDING	a)	a)
PAUSIERT	a)	a)

a): Wenn der Dienst diesen Steuercode akzeptiert, senden Sie die Anforderung an den Dienst; andernfalls gibt ControlServiceEx null zurück und GetLastErrorERROR_INVALID_SERVICE_CONTROLzurück.
b): Der Dienst befindet sich nicht in einem Zustand, in dem ein Steuerelement an das Steuerelement gesendet werden kann, sodass ControlServiceEx null zurückgibt und GetLastError-ERROR_SERVICE_CANNOT_ACCEPT_CTRLzurückgibt.
(c): Der Dienst ist nicht aktiv, sodass ControlServiceEx Null zurückgibt und GetLastErrorERROR_SERVICE_NOT_ACTIVEzurückgibt.

Anmerkung

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

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