Signatur
Beschreibung
Mit win32_set_service_pause_resume_state() kann ein als Windows-Dienst laufendes PHP-Skript dem Service Control Manager (SCM) mitteilen, ob es Pause- (SERVICE_CONTROL_PAUSE) und Fortsetzen-Befehle (SERVICE_CONTROL_CONTINUE) entgegennehmen kann und soll. Standardmäßig unterstützen viele Dienste diese Steueranweisungen nicht – erst durch explizites Aktivieren über diese Funktion signalisiert der Dienst dem SCM, dass er darauf reagieren kann.
Die Funktion muss innerhalb des Dienstprozesses aufgerufen werden, nachdem der Dienst gestartet wurde (typischerweise nach dem Aufruf von win32_start_service_ctrl_dispatcher()). Sie ist ausschließlich auf Windows-Systemen mit der win32service-Extension verfügbar.
Wird der Wert auf true gesetzt, erscheinen die entsprechenden Schaltflächen bzw. Menüpunkte in der Dienste-Verwaltungskonsole (services.msc) und der Dienst kann über den SCM pausiert oder fortgesetzt werden. Das PHP-Skript muss dann selbst auf den Status WIN32_SERVICE_PAUSED reagieren und die Arbeit entsprechend unterbrechen.
Typischerweise wird diese Funktion zusammen mit win32_get_last_control_message() verwendet, um in der Dienst-Hauptschleife den aktuellen Steuerbefehl zu prüfen und den Dienst-Status korrekt zu verwalten.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $enable Pflicht | bool | true, um Pause/Fortsetzen-Unterstützung zu aktivieren; false, um sie zu deaktivieren. Ist dieser Wert true, meldet der Dienst dem SCM, dass er SERVICE_CONTROL_PAUSE- und SERVICE_CONTROL_CONTINUE-Befehle verarbeiten kann. |
Rückgabewert
Win32ServiceException ausgelöst (ab win32service 1.0.0).Beispiele
Pause/Fortsetzen in einem Windows-Dienst aktivieren
<?php
// Dienst-Callback-Funktion
function serviceMain(array $args): void
{
// Pause/Fortsetzen-Unterstützung einschalten
win32_set_service_pause_resume_state(true);
// Dienst als laufend markieren
win32_set_service_status(WIN32_SERVICE_RUNNING);
while (true) {
$msg = win32_get_last_control_message();
if ($msg === WIN32_SERVICE_CONTROL_STOP) {
// Dienst beenden
win32_set_service_status(WIN32_SERVICE_STOPPED);
break;
} elseif ($msg === WIN32_SERVICE_CONTROL_PAUSE) {
// Dienst pausieren
win32_set_service_status(WIN32_SERVICE_PAUSED);
// Warten, bis Fortsetzen-Befehl kommt
while (win32_get_last_control_message() !== WIN32_SERVICE_CONTROL_CONTINUE) {
sleep(1);
}
win32_set_service_status(WIN32_SERVICE_RUNNING);
}
// Eigentliche Dienstlogik
// ...
sleep(1);
}
}
// Dienst-Dispatcher starten
win32_start_service_ctrl_dispatcher('MeinPHPDienst', 'serviceMain');Pause/Fortsetzen-Unterstützung deaktivieren
<?php
// In bestimmten Situationen (z. B. während kritischer Operationen)
// kann die Pause-Fähigkeit vorübergehend deaktiviert werden
function serviceMain(array $args): void
{
win32_set_service_status(WIN32_SERVICE_RUNNING);
while (true) {
$msg = win32_get_last_control_message();
if ($msg === WIN32_SERVICE_CONTROL_STOP) {
win32_set_service_status(WIN32_SERVICE_STOPPED);
break;
}
// Kritische Phase: Pause nicht erlauben
win32_set_service_pause_resume_state(false);
performCriticalOperation();
// Unkritische Phase: Pause wieder erlauben
win32_set_service_pause_resume_state(true);
sleep(1);
}
}
function performCriticalOperation(): void
{
// Datenbankmigrationen o. Ä.
sleep(2);
}
win32_start_service_ctrl_dispatcher('MeinPHPDienst', 'serviceMain');// Wichtig · Fallstricke
Plattform: Diese Funktion ist ausschließlich unter Windows verfügbar und erfordert die PECL-Extension win32service. Auf Unix/Linux-Systemen existiert sie nicht.
Kontext: Die Funktion darf nur innerhalb des Dienstprozesses aufgerufen werden, also innerhalb der Dienst-Callback-Funktion nach dem Start über win32_start_service_ctrl_dispatcher(). Ein Aufruf außerhalb dieses Kontexts führt zu einem Fehler.
Ausnahmebehandlung: Ab win32service 1.0.0 werden Fehler als Win32ServiceException geworfen statt als einfache Fehlercodes zurückgegeben. Code sollte entsprechend mit try/catch abgesichert werden.
Reaktion auf Befehle: Das bloße Aktivieren dieser Funktion reicht nicht aus – das Skript muss aktiv auf WIN32_SERVICE_CONTROL_PAUSE und WIN32_SERVICE_CONTROL_CONTINUE in der Hauptschleife reagieren und den Dienststatus mit win32_set_service_status() entsprechend setzen.