ComObjConnect() [AHK_L 53+]

Verbindet die Ereignisquellen eines COM-Objekts mit Funktionen, die ein bestimmtes Präfix haben.

ComObjConnect(ComObject , PräfixOderSink)

Parameter

ComObject

Ein Objekt, das Ereignisse auslöst.

Wenn das Objekt das IConnectionPointContainer-Interface nicht unterstützt oder wenn die Typinformationen zur Klasse des Objekts nicht abgerufen werden kann, wird eine Fehlermeldung angezeigt. Mit ComObjError() oder Try/Catch kann dies unterdrückt oder kontrolliert werden.

[v1.1.22+]: Das IProvideClassInfo-Interface wird genutzt, um die Typinformationen zur Klasse des Objekts abzurufen, sofern es vom Objekt unterstützt wird. Ansonsten versucht ComObjConnect, die Typinformationen via IDispatch-Interface des Objekts abzurufen, was unzuverlässig sein kann.

PräfixOderSink

Eine Zeichenkette, die dem Ereignisnamen vorangestellt wird, um zu bestimmen, welche Funktion aufgerufen werden soll, wenn ein Ereignis stattfindet, oder [in v1.1.01+] ein Event-Sink-Objekt, das eine Methode für jedes zu behandelnde Ereignis definiert.

Lässt man diesen Parameter weg, wird die Verbindung zu diesem Objekt getrennt; das heißt, dass das Skript nicht länger Benachrichtigungen von seinen Ereignissen erhält.

Verwendung

Um ComObjConnect effektiv zu nutzen, müssen Sie zunächst Funktionen in das Skript schreiben, die die entsprechenden Ereignisse behandeln können. Solche Funktionen, auch "Eventhandler" genannt, haben die folgende Struktur:

PräfixEreignisName([Params..., ComObject])
{
    ... ereignisbehandelnder Code ...
    return RückgabeWert
}

Präfix sollte identisch mit dem PräfixOderSink-Parameter sein, wenn es eine Zeichenkette ist; ansonsten sollte es weggelassen werden. EreignisName sollte mit dem Namen des Ereignisses ersetzt werden, das von der Funktion behandelt werden soll.

Params entspricht den Parametern, die das Ereignis hat. Wenn das Ereignis keine Parameter hat, sollte Params ganz weggelassen werden. ComObject ist optional und kann nur genutzt werden, wenn die korrekte Anzahl von Params definiert ist; es enthält eine Referenz zum originalen Wrapper-Objekt, das an ComObjConnect übergeben wurde. "ComObject" sollte mit einem Namen ersetzt werden, der eher dem Kontext Ihres Skripts entspricht.

Beachten Sie, dass Eventhandler Rückgabewerte haben können. Mit ComObject(Typ, Wert) kann ein COM-spezifischer Wertetyp zurückgegeben werden. return ComObject(0,0) beispielsweise gibt eine Variante des Typs VT_EMPTY zurück, was das gleiche ist wie, als würde eine JavaScript-Funktion undefined (oder überhaupt nichts) zurückgeben.

Mit ComObjConnect(MeinObjekt, "Präfix") kann die Ereignisbehandlung aktiviert werden.

Mit ComObjConnect(MeinObjekt) kann die Verbindung zum Objekt getrennt werden (um die Ereignisbehandlung zu stoppen).

Ist die Anzahl der Parameter unbekannt, kann eine variadische Funktion verwendet werden.

Event-Sink [v1.1.01+]

Wenn PräfixOderSink ein Objekt ist, wird bei jedem ausgelösten Ereignis die entsprechende Methode dieses Objekts aufgerufen. Obwohl das Objekt dynamisch konstruiert werden kann, ist es für PräfixOderSink typischer, auf eine Klasse oder eine Instanz einer Klasse zu verweisen. In diesem Fall werden die Methoden wie oben gezeigt definiert, aber ohne Präfix.

Wie bei jedem Methodenaufruf enthält der (normalerweise versteckte) this-Parameter der Methode eine Referenz zum Objekt, über das die Methode aufgerufen wurde; also das Event-Sink-Objekt, nicht das COM-Objekt. Dies kann verwendet werden, um den Ereignishandlern Kontext bereitzustellen oder um Werte zwischen ihnen auszutauschen.

Mit einer __Call-Metafunktion können alle Ereignisse abgefangen werden, ohne dass für jedes Ereignis eine Methode definiert werden muss.

ComObject behält eine Referenz zu PräfixOderSink, daher kann es nicht vor dem Trennen des Objekts gelöscht werden.

[v1.1.36.02+]: ComObject gibt seine Referenz zu PräfixOderSink automatisch frei, wenn das COM-Objekt die Verbindung freigibt. Das passiert zum Beispiel, wenn der Internet Explorer beendet wird. Wenn das Skript seine eigene Referenz zu PräfixOderSink nicht beibehält, kann es __Delete nutzen, um zu erkennen, wann dies geschieht. Wenn das Objekt von einem Remote-Prozess gehostet wird und der Prozess unerwartet terminiert wird, kann es mehrere Minuten dauern, bis das System die Verbindung freigibt.

Bemerkungen

Das Skript muss eine Referenz zu ComObject behalten, da ComObject sonst automatisch freigegeben und von dessen COM-Objekt getrennt werden würde, wodurch die Erkennung weiterer Ereignisse verhindert wird. Es gibt keine Standardmethode, um zu erkennen, wann die Verbindung überflüssig ist, daher muss das Skript die Verbindung manuell trennen, indem es ComObjConnect aufruft.

Die #Persistent-Direktive ist eventuell vonnöten, um das Skript am Laufen zu halten, während es auf Ereignisse wartet.

Bei Misserfolg wird die Funktion je nach aktueller ComObjError()-Einstellung und anderen Faktoren eventuell eine Ausnahme auslösen, das Skript beenden oder einfach ihren Wert zurückgeben.

Siehe auch

ComObjCreate(), ComObjGet(), ComObjActive(), ComObjError(), WScript.ConnectObject (Microsoft Docs)

Beispiele

ie := ComObjCreate("InternetExplorer.Application")

; Verbindet Ereignisse mit entsprechenden Skript-Funktionen, die das Präfix "IE_" haben.
ComObjConnect(ie, "IE_")

ie.Visible := true  ; Funktioniert nicht korrekt unter IE7.
ie.Navigate("https://www.autohotkey.com/")
#Persistent

IE_DocumentComplete(ieEventParam, url, ieFinalParam) {
    global ie
    if (ie != ieEventParam)
        s .= "Erster Parameter ist ein neues Wrapper-Objekt.`n"
    if (ie == ieFinalParam)
        s .= "Letzter Parameter ist das originale Wrapper-Objekt.`n"
    if ((disp1:=ComObjUnwrap(ieEventParam)) == (disp2:=ComObjUnwrap(ieFinalParam)))
        s .= "Beide Wrapper-Objekte verweisen auf die gleiche IDispatch-Instanz.`n"
    ObjRelease(disp1), ObjRelease(disp2)
    MsgBox % s . "Das Laden von " ie.Document.title " @ " url " wurde abgeschlossen."
    ie.Quit()
    ExitApp
}