Signatur
Beschreibung
win32_send_custom_control ermöglicht es, einen benutzerdefinierten Steuercode an einen Windows-Dienst zu senden. Benutzerdefinierte Steuercodes liegen im Bereich 128–255 und erlauben es, eigene Signale an Dienste zu übermitteln, ohne die standardisierten Aktionen wie Start, Stop oder Pause zu verwenden. Der Dienst muss diese Codes in seinem Handler entsprechend auswerten.
Diese Funktion ist Teil der win32service-Erweiterung und steht ausschließlich auf Windows-Systemen zur Verfügung. Sie setzt voraus, dass PHP mit der win32service-Extension betrieben wird und der ausführende Benutzer über ausreichende Berechtigungen zum Steuern des angegebenen Dienstes verfügt.
Typische Einsatzgebiete sind beispielsweise das Auslösen von Konfigurations-Reloads, das Schreiben von Diagnosedaten oder das Auslösen beliebiger dienstspezifischer Aktionen, ohne den Dienst neu starten zu müssen. Der Dienst muss so programmiert sein, dass er den benutzerdefinierten Code in seiner Steuerhandler-Routine (win32_run_loop bzw. dem eigenen Handler) verarbeitet.
Ab win32service Version 1.0.0 wirft die Funktion im Fehlerfall eine Win32ServiceException anstatt einen Fehlercode zurückzugeben. Ältere Versionen gaben im Erfolgsfall WIN32_NO_ERROR zurück.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $servicename Pflicht | string | Der interne Name (nicht der Anzeigename) des Windows-Dienstes, an den das Steuersignal gesendet werden soll. | |
| $control Pflicht | int | Der benutzerdefinierte Steuercode, der an den Dienst gesendet werden soll. Muss im Bereich 128–255 liegen, da dieser Bereich für benutzerdefinierte Codes reserviert ist. | |
| $machine | string | Der Name des entfernten Rechners, auf dem der Dienst läuft. Wird ein leerer String oder nichts übergeben, wird der lokale Rechner verwendet. |
Rückgabewert
Win32ServiceException geworfen.Beispiele
Benutzerdefiniertes Steuersignal an einen lokalen Dienst senden
<?php
// Steuercode 200 an den Dienst 'MeinPHPDienst' senden
// Der Dienst muss diesen Code in seinem Handler auswerten
try {
win32_send_custom_control('MeinPHPDienst', 200);
echo "Steuersignal erfolgreich gesendet.\n";
} catch (Win32ServiceException $e) {
echo "Fehler beim Senden des Steuersignals: " . $e->getMessage() . "\n";
}
?>Benutzerdefiniertes Steuersignal an einen Dienst auf einem entfernten Rechner senden
<?php
// Steuercode 128 (minimaler benutzerdefinierter Code) an einen Dienst
// auf dem entfernten Server 'WINSERVER01' senden
try {
win32_send_custom_control('MeinPHPDienst', 128, 'WINSERVER01');
echo "Steuersignal an Remote-Dienst erfolgreich gesendet.\n";
} catch (Win32ServiceException $e) {
echo "Fehler: " . $e->getMessage() . "\n";
echo "Fehlercode: " . $e->getCode() . "\n";
}
?>// Wichtig · Fallstricke
Plattformbeschränkung: Diese Funktion ist ausschließlich unter Windows verfügbar und setzt die win32service-PHP-Erweiterung voraus. Auf anderen Betriebssystemen führt ein Aufruf zu einem fatalen Fehler.
Steuercode-Bereich: Der Parameter control muss im Bereich 128–255 liegen. Werte außerhalb dieses Bereichs sind für Windows-Systemsteuercodes reserviert und führen zu einem Fehler. Für Standardaktionen wie Stoppen oder Pausieren stehen separate Funktionen wie win32_stop_service zur Verfügung.
Berechtigungen: Der Prozess, der diese Funktion aufruft, benötigt ausreichende Windows-Berechtigungen zum Steuern des Zieldienstes (typischerweise Administrator-Rechte). Fehlende Berechtigungen führen zu einer Win32ServiceException.
Version: Ab win32service 1.0.0 wurde die Fehlerbehandlung auf Exceptions umgestellt. In älteren Versionen wurde ein numerischer Fehlercode zurückgegeben, der mit den WIN32_*-Konstanten verglichen werden musste.