win32_set_service_exit_code — Funktion · PHP-Referenz

Signatur

win32_set_service_exit_code(int $exitCode = 0): int

Beschreibung

win32_set_service_exit_code() ermöglicht es einem als Windows-Dienst laufenden PHP-Prozess, dem Service Control Manager (SCM) beim Beenden einen bestimmten Exitcode zu übermitteln. Dieser Code kann von Monitoring-Systemen, Neustart-Strategien oder der Windows-Ereignisanzeige ausgewertet werden.

Wird die Funktion ohne Argument aufgerufen (bzw. mit dem Standardwert 0), gibt sie lediglich den aktuell gesetzten Exitcode zurück, ohne ihn zu ändern. Übergibt man einen Wert ungleich 0, wird dieser als neuer Exitcode gespeichert und der vorherige Wert zurückgegeben.

Typischerweise wird diese Funktion gemeinsam mit win32_set_service_exit_info() verwendet: Der Exitcode gibt den allgemeinen Fehlertyp an (z. B. ERROR_SERVICE_SPECIFIC_ERROR = 1066), während win32_set_service_exit_info() einen anwendungsspezifischen Untercode setzt. So lassen sich differenzierte Fehlerinformationen an den SCM weitergeben.

Diese Funktion ist nur auf Windows-Plattformen verfügbar und setzt die PECL-Erweiterung win32service voraus. Ein Aufruf außerhalb eines Dienstkontexts hat keine sinnvolle Wirkung.

Parameter

Name	Typ	Default	Beschreibung
$exitCode	int	0	Der Exitcode, der beim Beenden des Dienstes an den SCM gemeldet werden soll. `0` steht für Erfolg. Der Wert `1066` (`ERROR_SERVICE_SPECIFIC_ERROR`) wird häufig verwendet, wenn ein anwendungsspezifischer Fehlercode via `win32_set_service_exit_info()` gesetzt wird. Bei Übergabe von `0` wird der aktuelle Exitcode nur gelesen, nicht verändert.

Rückgabewert

Typ

int

Beschreibung

Gibt den zuvor gesetzten Exitcode zurück. Beim ersten Aufruf ist dies in der Regel 0. So lässt sich der alte Wert sichern, bevor ein neuer gesetzt wird.

Beispiele

Dienst mit Fehlercode beenden

<?php
// Dienst starten und initialisieren
win32_start_service_ctrl_dispatcher('MeinPHPDienst');

while (WIN32_SERVICE_CONTROL_STOP !== win32_get_last_control_message()) {
    // Dienst-Logik ...

    // Fehlerfall: anwendungsspezifischen Exitcode setzen
    $fehler = true;
    if ($fehler) {
        // ERROR_SERVICE_SPECIFIC_ERROR = 1066
        win32_set_service_exit_code(1066);
        // Anwendungsspezifischen Untercode setzen
        win32_set_service_exit_info(42);
        win32_set_service_status(WIN32_SERVICE_STOPPED);
        exit;
    }
    sleep(1);
}

win32_set_service_exit_code(0); // Erfolgreich beendet
win32_set_service_status(WIN32_SERVICE_STOPPED);

Aktuellen Exitcode auslesen ohne Änderung

<?php
// Nur lesen, nichts ändern (Standardwert 0 entspricht "kein Schreiben")
$aktuellerCode = win32_set_service_exit_code(0);
echo 'Aktueller Dienst-Exitcode: ' . $aktuellerCode . PHP_EOL;

// Neuen Code setzen und alten Wert abrufen
$alterCode = win32_set_service_exit_code(1066);
echo 'Alter Code war: ' . $alterCode . ', neuer Code: 1066' . PHP_EOL;

Aktueller Dienst-Exitcode: 0 Alter Code war: 0, neuer Code: 1066

// Wichtig · Fallstricke

Nur Windows: Diese Funktion ist ausschließlich auf Windows-Systemen verfügbar und erfordert die PECL-Erweiterung win32service. Auf anderen Betriebssystemen führt ein Aufruf zu einem fatalen Fehler.

Dienstkontext erforderlich: Die Funktion ist nur sinnvoll, wenn das PHP-Skript tatsächlich als Windows-Dienst via win32_start_service_ctrl_dispatcher() gestartet wurde. Außerhalb dieses Kontexts hat sie keine praktische Wirkung auf den SCM.

Versionierung: Ab win32service 1.0.0 wird bei ungültigem Kontext eine Win32ServiceException geworfen anstatt einen Fehler zurückzugeben. Prüfe die verwendete Erweiterungsversion entsprechend.

Siehe auch

win32_set_service_exit_info win32_set_service_status win32_start_service_ctrl_dispatcher win32_get_last_control_message