ControlService-Funktion (winsvc.h)
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.
Dieser Wert kann auch ein benutzerdefinierter Steuerelementcode sein, wie in der folgenden Tabelle beschrieben.
| Steuerungscode | Bedeutung |
|---|---|
|
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 |
|---|---|
|
Das Handle verfügt nicht über das erforderliche Zugriffsrecht. |
|
Der Dienst kann nicht beendet werden, da andere ausgeführte Dienste davon abhängig sind. |
|
Das angegebene Handle wurde nicht mit CreateService oder OpenService abgerufen, oder das Handle ist nicht mehr gültig. |
|
Der angeforderte Steuerelementcode ist nicht definiert. |
|
Der angeforderte Steuerungscode ist nicht gültig, oder es ist für den Dienst nicht akzeptabel. |
|
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. |
|
Der Dienst wurde nicht gestartet. |
|
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. |
|
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 |