Signatur
Beschreibung
com_message_pump() ist eine Windows-spezifische Funktion, die die COM-Nachrichtenwarteschlange des aktuellen Threads abarbeitet. Sie wird benötigt, wenn PHP-Skripte COM-Objekte verwenden, die asynchrone Ereignisse oder Callbacks auslösen – etwa ActiveX-Steuerelemente oder COM-Server, die Ereignisse feuern.
Die Funktion blockiert für bis zu timeoutms Millisekunden und verarbeitet während dieser Wartezeit alle eingehenden COM-Nachrichten. Wird 0 übergeben, werden sofort alle aktuell anstehenden Nachrichten verarbeitet, ohne zu blockieren. Dies entspricht dem Windows-Konzept eines Message Pumps, der nötig ist, damit COM-Ereignisse (wie Sink-Callbacks) vom PHP-Prozess empfangen und weitergeleitet werden können.
Typischerweise wird diese Funktion in einer Warteschleife eingesetzt, wenn auf COM-Ereignisse gewartet wird, z. B. wenn ein COM-Server einen Vorgang asynchron abschließt und PHP darüber benachrichtigt werden soll. Ohne regelmäßigen Aufruf von com_message_pump() werden diese Ereignisse nie zugestellt.
Die Funktion steht nur auf Windows-Systemen zur Verfügung und erfordert, dass PHP mit COM-Unterstützung kompiliert wurde.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $timeoutms | int | 0 | Maximale Wartezeit in Millisekunden, während der COM-Nachrichten verarbeitet werden. Bei 0 werden sofort alle anstehenden Nachrichten verarbeitet, ohne zu blockieren. |
Rückgabewert
true zurück, wenn die Nachrichtenwarteschlange erfolgreich verarbeitet wurde. Gibt false zurück, wenn keine Nachrichtenwarteschlange vorhanden ist oder ein Fehler aufgetreten ist.Beispiele
Warten auf ein COM-Ereignis in einer Schleife
<?php
// COM-Objekt erstellen, das asynchrone Ereignisse auslöst
$com = new COM('InternetExplorer.Application');
$com->Visible = true;
$com->Navigate('https://example.com');
// Solange auf das Ereignis warten (z. B. bis die Seite geladen ist)
$timeout = 30000; // max. 30 Sekunden warten
$elapsed = 0;
$interval = 200; // alle 200 ms pollen
while ($com->Busy && $elapsed < $timeout) {
com_message_pump($interval);
$elapsed += $interval;
}
if ($com->Busy) {
echo "Seite wurde nicht rechtzeitig geladen.\n";
} else {
echo "Seite erfolgreich geladen: " . $com->LocationURL . "\n";
}
$com->Quit();
?>Sofortige Verarbeitung aller ausstehenden Nachrichten
<?php
// Alle aktuell anstehenden COM-Nachrichten sofort verarbeiten (nicht blockierend)
$result = com_message_pump(0);
if ($result) {
echo "COM-Nachrichten erfolgreich verarbeitet.\n";
} else {
echo "Keine COM-Nachrichtenwarteschlange vorhanden oder Fehler.\n";
}
?>// Wichtig · Fallstricke
Plattformeinschränkung: com_message_pump() ist ausschließlich unter Windows verfügbar und setzt eine PHP-Installation mit aktivierter COM-Erweiterung (php_com_dotnet.dll) voraus. Auf anderen Betriebssystemen existiert diese Funktion nicht.
Endlosschleifen vermeiden: Beim Warten auf COM-Ereignisse sollte immer ein maximales Timeout oder eine Abbruchbedingung implementiert werden, um Endlosschleifen zu verhindern, falls das erwartete Ereignis nie eintrifft.
Threads: Die Funktion verarbeitet nur die Nachrichtenwarteschlange des aktuellen Threads. COM-Objekte, die in einem anderen Thread erstellt wurden (STA/MTA), haben eine eigene Warteschlange, die separat behandelt werden muss.