com_event_sink — Funktion · PHP-Referenz

Signatur

com_event_sink(variant $comobject, object $sinkobject, array|string $sinkinterface = null): bool

Beschreibung

com_event_sink() registriert ein PHP-Objekt als Event Sink für ein COM-Objekt. Wenn das COM-Objekt bestimmte Events auslöst (z. B. Fortschrittsmeldungen, Statusänderungen oder asynchrone Rückmeldungen), ruft PHP automatisch die entsprechenden Methoden des PHP-Sink-Objekts auf.

Das PHP-Sink-Objekt muss Methoden definieren, die denselben Namen tragen wie die Events, die das COM-Objekt über seine Dispatch-Schnittstelle bereitstellt. Der optionale Parameter sinkinterface erlaubt es, eine bestimmte Schnittstellenkennung (Interface GUID als String oder ein Array der Event-Namen) explizit anzugeben, falls das COM-Objekt mehrere Event-Schnittstellen anbietet.

Nach dem Verbinden muss die PHP-Nachrichtenschleife mit com_message_pump() betrieben werden, damit eingehende COM-Events verarbeitet werden. Ohne diesen Schritt werden keine Events ausgeliefert.

Diese Funktion ist typischerweise nützlich, wenn man mit COM-Automatisierungskomponenten (z. B. Internet Explorer, Windows Script Host, eigene ActiveX-Server) interagiert und auf asynchrone Rückmeldungen oder Ereignisse reagieren möchte.

Parameter

Name	Typ	Default	Beschreibung
$comobject Pflicht	variant		Das COM-Objekt, dessen Events abgefangen werden sollen. Muss eine gültige `COM`-Instanz sein, die mindestens eine Event-Dispatch-Schnittstelle (Outgoing Interface) besitzt.
$sinkobject Pflicht	object		Ein PHP-Objekt, das als Event Sink fungiert. Es muss öffentliche Methoden mit denselben Namen wie die COM-Events bereitstellen, die empfangen werden sollen.
$sinkinterface	array\|string	null	Optional: Eine Interface-GUID als String oder ein Array von Event-Methodennamen. Falls `null`, wird die Standard-Dispatch-Schnittstelle des COM-Objekts automatisch aus der Typbibliothek ermittelt.

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die Verbindung erfolgreich hergestellt wurde, andernfalls false. Im Fehlerfall (z. B. keine Typbibliothek verfügbar, falsche Schnittstelle) wird false zurückgegeben und ggf. eine PHP-Warnung ausgelöst.

Beispiele

Internet-Explorer-Events abfangen

<?php
// Event-Sink-Klasse definieren
class IEEventSink {
    public function DocumentComplete($pDisp, $url) {
        echo "Seite geladen: " . $url . PHP_EOL;
    }

    public function NavigateError($pDisp, $url, $frame, $statusCode, &$cancel) {
        echo "Navigationsfehler ($statusCode) bei: " . $url . PHP_EOL;
    }
}

// Internet Explorer instanziieren
$ie = new COM('InternetExplorer.Application');
$ie->Visible = true;

// Event Sink registrieren
$sink = new IEEventSink();
if (com_event_sink($ie, $sink, 'DWebBrowserEvents2')) {
    echo "Event Sink erfolgreich registriert." . PHP_EOL;
} else {
    echo "Registrierung fehlgeschlagen." . PHP_EOL;
}

// URL aufrufen
$ie->Navigate('https://example.com');

// Nachrichtenschleife betreiben, bis Events eintreffen
for ($i = 0; $i < 30; $i++) {
    com_message_pump(500); // 500 ms warten
}

$ie->Quit();
?>

Event Sink erfolgreich registriert. Seite geladen: https://example.com/

Generischer Event Sink mit automatischer Schnittstellenerkennung

<?php
class GenericSink {
    // Beliebige COM-Events werden als magische Methode abgefangen
    public function __call(string $name, array $args): void {
        echo "COM-Event empfangen: $name" . PHP_EOL;
        foreach ($args as $i => $arg) {
            echo "  Argument $i: " . print_r($arg, true) . PHP_EOL;
        }
    }
}

$com = new COM('Shell.Application');
$sink = new GenericSink();

// Keine explizite Schnittstelle angeben — automatische Erkennung
$result = com_event_sink($com, $sink);
echo $result ? "Verbunden." : "Fehler beim Verbinden.";

com_message_pump(2000);
?>

Verbunden.

// Wichtig · Fallstricke

Nur Windows: com_event_sink() ist ausschließlich unter Windows verfügbar und erfordert die PHP-COM-Erweiterung (php_com_dotnet.dll). Auf anderen Plattformen existiert diese Funktion nicht.

Typbibliothek erforderlich: Damit die automatische Schnittstellenerkennung funktioniert, muss das COM-Objekt eine registrierte Typbibliothek (TLB) besitzen. Ohne Typbibliothek sollte sinkinterface als Array der Event-Methodennamen übergeben werden.

Nachrichtenschleife: Events werden nur verarbeitet, wenn com_message_pump() aufgerufen wird. Ohne diese Funktion bleiben Events in der COM-Warteschlange stehen und werden nie an das PHP-Sink-Objekt weitergeleitet.

Sicherheit: Da COM-Events direkt PHP-Methoden aufrufen, sollte das Sink-Objekt nur die tatsächlich benötigten Methoden implementieren und Eingaben aus COM-Events stets validieren, da diese von externen Prozessen oder Netzwerkressourcen stammen können.

Siehe auch

com_message_pump com_print_typeinfo com_load_typelib COM