Signatur
Beschreibung
win32_query_service_status() ist Bestandteil der win32service-Erweiterung und ermöglicht es, den Betriebsstatus eines Windows-Systemdienstes abzufragen. Die Funktion kommuniziert direkt mit dem Windows Service Control Manager (SCM) und gibt ein Array zurück, das detaillierte Statusinformationen enthält – darunter den aktuellen Dienststatus, den Prozesstyp sowie Hinweise auf laufende Steuervorgänge.
Typische Anwendungsfälle sind die Überwachung kritischer Systemdienste, das Prüfen ob ein Dienst vor einem Start- oder Stopp-Vorgang bereits läuft, sowie die Implementierung von Verwaltungs-Skripten auf Windows-Servern. Der optionale Parameter $machine ermöglicht auch das Abfragen von Diensten auf Remote-Maschinen.
Das zurückgegebene Array enthält Schlüssel wie CurrentState (z. B. WIN32_SERVICE_RUNNING, WIN32_SERVICE_STOPPED), ServiceType, ControlsAccepted, Win32ExitCode, ServiceSpecificExitCode, CheckPoint und WaitHint. Bei einem Fehler wird ein Integer-Fehlercode zurückgegeben.
Hinweis: Diese Funktion ist ausschließlich unter Windows verfügbar und setzt die Installation der win32service-Erweiterung voraus. Ab Version 1.0.0 der Erweiterung löst die Funktion bei Fehlern eine Win32ServiceException aus, statt einen Fehlercode zurückzugeben.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $servicename Pflicht | string | Der interne Name des Windows-Dienstes (nicht der Anzeigename), z. B. W32Time für den Windows-Zeitdienst. |
|
| $machine | string | null | Der Name des Remote-Rechners, auf dem der Dienst abgefragt werden soll. Wird der Parameter weggelassen oder ist null, wird der lokale Rechner verwendet. |
Rückgabewert
CurrentState (aktueller Zustand, entspricht einer WIN32_SERVICE_*-Konstante), ServiceType, ControlsAccepted, Win32ExitCode, ServiceSpecificExitCode, CheckPoint und WaitHint. Im Fehlerfall wird ein int-Fehlercode zurückgegeben. Ab Erweiterungsversion 1.0.0 wird stattdessen eine Win32ServiceException ausgelöst.Beispiele
Status des Windows-Zeitdienstes abfragen
<?php
// Status des Windows-Zeitdienstes (W32Time) abfragen
$status = win32_query_service_status('W32Time');
if (!is_array($status)) {
echo 'Fehler beim Abfragen des Dienststatus. Fehlercode: ' . $status . PHP_EOL;
} else {
switch ($status['CurrentState']) {
case WIN32_SERVICE_RUNNING:
echo 'Dienst läuft.' . PHP_EOL;
break;
case WIN32_SERVICE_STOPPED:
echo 'Dienst ist gestoppt.' . PHP_EOL;
break;
case WIN32_SERVICE_START_PENDING:
echo 'Dienst wird gestartet...' . PHP_EOL;
break;
case WIN32_SERVICE_STOP_PENDING:
echo 'Dienst wird gestoppt...' . PHP_EOL;
break;
default:
echo 'Unbekannter Status: ' . $status['CurrentState'] . PHP_EOL;
}
}
?>Dienststatus mit Ausnahmebehandlung (ab Erweiterungsversion 1.0.0)
<?php
// Ab win32service 1.0.0 werden Fehler als Exception geworfen
try {
$status = win32_query_service_status('Spooler');
if ($status['CurrentState'] === WIN32_SERVICE_RUNNING) {
echo 'Der Druckdienst (Spooler) ist aktiv.' . PHP_EOL;
} else {
echo 'Der Druckdienst ist nicht aktiv. Status-Code: ' . $status['CurrentState'] . PHP_EOL;
}
} catch (Win32ServiceException $e) {
echo 'Fehler beim Abfragen: ' . $e->getMessage() . PHP_EOL;
echo 'Fehlercode: ' . $e->getCode() . PHP_EOL;
}
?>// Wichtig · Fallstricke
Plattform: Diese Funktion ist ausschließlich unter Windows verfügbar. Auf anderen Betriebssystemen ist sie nicht definiert und führt zu einem fatalen Fehler.
Berechtigungen: Das Abfragen von Diensten auf Remote-Maschinen erfordert entsprechende Windows-Berechtigungen. Unzureichende Rechte führen zu einem Fehler oder einer Exception.
API-Änderung in Version 1.0.0: Ab Version 1.0.0 der win32service-Erweiterung wird bei Fehlern keine Integer-Fehlerkodierung mehr zurückgegeben, sondern eine Win32ServiceException geworfen. Bestehenden Code sollte auf Try-Catch umgestellt werden.
Dienstname vs. Anzeigename: Der Parameter $servicename erwartet den internen Dienstnamen (wie er in der Registrierung steht), nicht den benutzerfreundlichen Anzeigenamen. Den internen Namen findet man z. B. in der Windows-Dienstverwaltung (services.msc) unter den Eigenschaften des Dienstes.