LocalConnection  - AS3

Gibt das Objekt an, bei dem Callback-Methoden aufgerufen werden. Standardeinstellung ist das erstellte LocalConnection-Objekt this. Wenn Sie die client-Eigenschaft auf ein anderes Objekt einstellen, werden die Callback-Methoden bei dem eingestellten Objekt aufgerufen.

Ein String, der die Domäne des Pfads der aktuellen Datei angibt.

Bei Inhalt, der in der Sicherheitssandbox der Anwendung Adobe AIR ausgeführt wird (Inhalt, der mit der AIR-Anwendung installiert wurde), verwendet die Laufzeit den String app# gefolgt von der Anwendungs-ID für die AIR-Anwendung (definiert in der Anwendungsdeskriptordatei) anstelle der Superdomäne. So wird zum Beispiel ein connectionName für eine Anwendung mit der Anwendungs-ID com.example.air.MyApp connectionName in "app#com.example.air.MyApp:connectionName" aufgelöst.

In für Flash Player 9 oder neuere Versionen veröffentlichten SWF-Dateien entspricht der zurückgegebene String der exakten Domäne der Datei, einschließlich Subdomänen. Wenn die Datei beispielsweise unter www.adobe.com gespeichert ist, gibt dieser Befehl "www.adobe.com" zurück.

Wenn die aktuelle Datei eine lokale Datei auf dem Client-Computer ist, die in Flash Player ausgeführt wird, gibt dieser Befehl "localhost" zurück.

Gewöhnlich wird bei dieser Eigenschaft der Domänenname des sendenden LocalConnection-Objekts als Parameter in die Methode einbezogen, die Sie im empfangenden LocalConnection-Objekt oder mit LocalConnection.allowDomain() aufrufen möchten, um Befehle von einer angegebenen Domäne zu akzeptieren. Wenn Sie den Datenaustausch nur zwischen LocalConnection-Objekten derselben Domäne aktivieren, ist diese Eigenschaft nicht erforderlich.

Verwandte API-Elemente

Gibt an, ob das LocalConnection-Objekt auf den aktuellen Benutzer beschränkt ist (true) oder ob es global allen Benutzern des Computers zur Verfügung steht (false). Diese Eigenschaft betrifft nur Inhalt, der unter Mac OS X ausgeführt wird; andere Plattformen ignorieren diesen Parameter. Verbindungen unter Windows- und Linux-Betriebssystemen werden immer auf Benutzerbasis hergestellt.

In Flash Player 10.0.22 und älteren Versionen sowie in AIR 1.5.1 und älteren Versionen haben alle LocalConnection-Objekte unter Mac OS X einen globalen Gültigkeitsbereich. Stellen Sie diese Eigenschaft immer auf true ein, falls Sie nicht die Kompatibilität mit älteren Versionen sicherstellen müssen. In zukünftigen Versionen wird der Standardwert dieser Eigenschaft möglicherweise zu true geändert.

Der Standardwert ist false.

Die isSupported-Eigenschaft hat den Wert true, wenn die LocalConnection-Klasse von der aktuellen Plattform unterstützt wird, andernfalls hat sie den Wert false.

Erstellt ein LocalConnection-Objekt. Mit LocalConnection-Objekten können Sie die Kommunikation zwischen verschiedenen Dateien auf demselben Client-Computer ermöglichen.

Verwandte API-Elemente

Gibt eine oder mehrere Domänen an, die LocalConnection-Aufrufe an diese LocalConnection-Instanz senden können.

Sie können diese Methode nicht verwenden, um Dateien, die mit einem sicheren Protokoll (HTTPS) gehostet werden, den Zugriff von Dateien zu erlauben, die in nicht sicheren Protokollen gehostet werden. Sie müssen stattdessen die Ereignisprozedur allowInsecureDomain() verwenden.

Sie sollten diese Methode verwenden, damit eine untergeordnete Datei von einer anderen Domäne LocalConnection-Aufrufe an die übergeordnete Datei vornehmen kann, ohne dass die endgültige Domäne bekannt ist, aus der die untergeordnete Datei stammt. Dies ist beispielsweise der Fall, wenn Sie Weiterleitungen mit Lastausgleich oder Server von Dritten verwenden. In diesem Fall können Sie die Eigenschaft url des mit der Ladung verwendeten LoaderInfo-Objekts einsetzen, um die Domäne dazu zu bewegen, die Methode allowDomain() anzuwenden. Wenn Sie beispielsweise mit einem Loader-Objekt eine untergeordnete Datei laden, können Sie, sobald der Ladevorgang abgeschlossen ist, die Eigenschaft contentLoaderInfo.url des Loader-Objekts überprüfen und die Domäne anhand der vollständigen URL parsen. Wenn Sie so verfahren, müssen Sie unbedingt warten, bis die Datei geladen wurde, denn die contentLoaderInfo.url-Eigenschaft verfügt erst, nachdem die Datei vollständig geladen wurde, über ihren endgültigen, korrekten Wert.

Es kann auch die entgegengesetzte Situation auftreten: Angenommen, Sie haben eine untergeordnete Datei erstellt, die LocalConnection-Aufrufe von der übergeordnete Datei annehmen möchte, der aber die Domäne der übergeordneten Datei nicht bekannt ist. In diesem Fall implementieren Sie diese Methode, indem Sie prüfen, ob das Domänenargument mit der Domäne der Eigenschaft loaderInfo.url in der geladenen Datei übereinstimmt. Auch diesmal müssen Sie die Domäne anhand der vollständigen URL von loaderInfo.url parsen. In diesem Fall müssen Sie jedoch nicht warten, bis die übergeordnete Datei geladen wurde, denn das Laden der übergeordneten Datei ist bereits abgeschlossen, wenn der Ladevorgang für die untergeordnete Datei erfolgt.

Bedenken Sie beim Einsatz dieser Methode das Sicherheitsmodell von Flash Player. In der Standardeinstellung wird ein LocalConnection-Objekt mit der Sandbox der erstellenden Datei verknüpft. Domänenübergreifende Aufrufe für LocalConnection-Objekte sind nur dann zulässig, wenn Sie in der empfangenden Datei die Methode LocalConnection.allowDomain() aufrufen. In Adobe AIR unterliegt Inhalt in der Sicherheitssandbox der Anwendung (Inhalt, der mit der AIR-Anwendung installiert wird) nicht diesen Sicherheitseinschränkungen.

Weitere Informationen zum Thema Sicherheit finden Sie im Flash Player Developer Center im Abschnitt Sicherheit.

Hinweis: Die Form der Methode allowDomain() hat sich geändert. In den früheren Versionen (ActionScript 1.0 und 2.0) war allowDomain eine zu implementierende Callback-Methode. In ActionScript 3.0 ist allowDomain() eine in den LocalConnection-Aufruf eingebettete Methode. Aufgrund dieser Änderung ist die Methode allowDomain() jetzt mit flash.system.Security.allowDomain() vergleichbar.

Parameter

Verwandte API-Elemente

Gibt eine oder mehrere Domänen an, die LocalConnection-Aufrufe an dieses LocalConnection-Objekt senden können.

Die Methode allowInsecureDomain() funktioniert wie die Methode allowDomain(), mit der Ausnahme, dass die Methode allowInsecureDomain() auch das Senden von LocalConnection-Aufrufen von Dateien aus HTTPS-Quellen durch SWF-Dateien aus Nicht-HTTPS-Quellen zulässt. Dieser Unterschied ist nur von Bedeutung, wenn Sie die Methode allowInsecureDomain() aus einer Datei aufrufen, die über HTTPS geladen wurde. Sie müssen die Methode allowInsecureDomain() auch bei Nicht-HTTPS-/HTTPS-Verbindungen innerhalb derselben Domäne aufrufen. Standardmäßig sind LocalConnection-Aufrufe von Dateien aus Nicht-HTTPS-Quellen an Dateien aus HTTPS-Quellen selbst innerhalb derselben Domäne nicht zulässig.

Der Aufruf von allowInsecureDomain() wird nicht empfohlen, da hierdurch die durch HTTPS gewährleistete Sicherheit möglicherweise gefährdet wird. Wenn Sie eine Datei über HTTPS laden, können Sie relativ sicher sein, dass die Datei bei der Übermittlung über das Netzwerk nicht manipuliert wird. Wenn Sie dann LocalConnection-Aufrufe an diese Datei durch eine Datei ohne HTTPS zulassen, akzeptieren Sie Aufrufe von einer Datei, die während der Übertragung möglicherweise manipuliert wurde. In diesem Fall ist extreme Vorsicht geboten, da Sie sich nicht auf die Authentizität der LocalConnection-Aufrufe an die über HTTPS geladene Datei verlassen können.

Standardmäßig können nur andere Dateien, die mit dem HTTPS-Protokoll gehostet werden, auf mit dem HTTPS-Protokoll gehostete Dateien zugreifen. Durch diese Implementierung bleibt die durch das HTTPS-Protokoll gewährleistete Integrität gewahrt.

Der Einsatz dieser Methode zur Umgehung des Standardverhaltens empfiehlt sich nicht, da damit die HTTPS-Sicherheit beeinträchtigt wird. In einigen Fällen ist dies jedoch notwendig. Beispiel: Sie müssen den Zugriff auf für Flash Player 9 oder eine neuere Version veröffentlichte HTTPS-Dateien durch HTTPS-Dateien zulassen, die für Flash Player 6 oder eine ältere Version veröffentlicht wurden.

Weitere Informationen zum Thema Sicherheit finden Sie im Flash Player Developer Center im Abschnitt Sicherheit.

Parameter

Verwandte API-Elemente

Schließt das LocalConnection-Objekt (bricht die Verbindung ab). Rufen Sie diesen Befehl auf, wenn das Objekt keine Befehle mehr annehmen soll, beispielsweise, wenn Sie einen connect()-Befehl mit demselben Parameter connectionName in einer anderen SWF-Datei aufrufen möchten.

Verwandte API-Elemente

Bereitet ein LocalConnection-Objekt auf den Empfang von Befehlen vor, die von einem send()-Befehl gesendet werden (vom sendenden LocalConnection-Objekt). Das mit der connect()-Methode verwendete Objekt ist das empfangende LocalConnection-Objekt. Das empfangende und das sendende Objekt müssen auf demselben Client-Computer ausgeführt werden.

Um eine „Race“-Bedingung zu vermeiden, definieren Sie die mit dem empfangenden LocalConnection-Objekt verknüpften Methoden, bevor Sie diese Methode aufrufen, wie im Beispiel zur Klasse „LocalConnection“ gezeigt.

In der Standardeinstellung wird das connectionName-Argument in den Wert "superdomain:connectionName" aufgelöst, wobei superdomain die Superdomäne der Datei mit dem Befehl connect() ist. Wenn sich beispielsweise die Datei mit dem empfangenden LocalConnection-Objekt unter www.someDomain.com befindet, wird connectionName in "someDomain.com:connectionName" aufgelöst. (Wenn sich eine Datei, die in Flash Player ausgeführt wird, auf dem Client-Computer befindet, wird superdomain der Wert "localhost" zugewiesen.)

Bei Inhalt, der in der Sicherheitssandbox der Anwendung Adobe AIR ausgeführt wird (Inhalt, der mit der AIR-Anwendung installiert wurde), verwendet die Laufzeit den String app# gefolgt von der Anwendungs-ID für die AIR-Anwendung (definiert in der Anwendungsdeskriptordatei) anstelle der Superdomäne. So wird zum Beispiel ein connectionName für eine Anwendung mit der Anwendungs-ID com.example.air.MyApp connectionName in "app#com.example.air.MyApp:connectionName" aufgelöst.

Ebenso lässt Flash Player das empfangende LocalConnection-Objekt nur Befehle von sendenden LocalConnection-Objekten empfangen, deren Verbindungsnamen ebenfalls in den Wert "superdomain:connectionName" aufgelöst werden. Auf diese Weise können in Flash Player zwischen Dateien derselben Domäne ganz einfach Daten ausgetauscht werden.

Wenn Sie den Datenaustausch nur zwischen Dateien in derselben Domäne implementieren, geben Sie einen String für connectionName an, der nicht mit einem Unterstrich (_) beginnt und der keinen Domänennamen angibt (beispielsweise "myDomain:connectionName"). Verwenden Sie denselben String in der Methode connect(connectionName).

Wenn Sie eine Kommunikation zwischen Dateien in unterschiedlichen Domänen implementieren, lässt sich die Portierbarkeit der Datei mit dem empfangenden LocalConnection-Objekt erhöhen, indem Sie für connectionName einen String angeben, der mit einem Unterstrich (_) beginnt. Im Folgenden werden zwei mögliche Fälle erläutert:

• Wenn der String für connectionName nicht mit einem Unterstrich (_) beginnt, wird ein Präfix mit der Superdomäne und einen Doppelpunkt hinzugefügt (z. B. "myDomain:connectionName"). Dies stellt zwar sicher, dass es keinen Konflikt zwischen Ihrer Verbindung und gleichnamigen Verbindungen aus anderen Domänen gibt, allerdings müssen sendende LocalConnection-Objekte ebenfalls diese Superdomäne angeben (z. B. "myDomain:connectionName"). Wenn die Datei mit dem empfangenden LocalConnection-Objekt in eine andere Domäne verschoben wird, ändert der Player das Präfix entsprechend der neuen Superdomäne (z. B. "anotherDomain:connectionName"). Alle sendenden LocalConnection-Objekte müssen dann manuell bearbeitet werden, damit sie auf die neue Superdomäne verweisen.
• Wenn der String für connectionName mit einem Unterstrich beginnt (zum Beispiel, "_connectionName"), wird dem String kein Präfix hinzugefügt. Das heißt, empfangende und sendende LocalConnection-Objekte verwenden identische Strings für connectionName. Wenn das empfangende Objekt mit allowDomain() angibt, dass Verbindungen von allen Domänen zulässig sind, können Sie die Datei mit dem empfangenden LocalConnection-Objekt in eine andere Domäne verschieben, ohne die sendenden LocalConnection-Objekte zu ändern.

Nähere Informationen finden Sie in der Übersicht über die Klasse und in der Erörterung zu connectionName in send() sowie in den Einträgen allowDomain() und domain.

Hinweis: Doppelpunkte werden als Sonderzeichen zum Trennen der Superdomäne vom String connectionName verwendet. Ein String für connectionName, der einen Doppelpunkt enthält, ist nicht gültig.

Bedenken Sie beim Einsatz dieser Methode das Sicherheitsmodell von Flash Player. In der Standardeinstellung wird ein LocalConnection-Objekt mit der Sandbox der erstellenden Datei verknüpft. Domänenübergreifende Aufrufe für LocalConnection-Objekte sind nur dann zulässig, wenn Sie in der empfangenden Datei die Methode LocalConnection.allowDomain() aufrufen. Sie können eine Datei daran hindern, diese Methode aufzurufen, indem Sie auf der HTML-Seite, die den SWF-Inhalt enthält, den Parameter allowNetworking der Tags object und embed festlegen.In Adobe AIR unterliegt Inhalt in der Sicherheitssandbox der Anwendung (Inhalt, der mit der AIR-Anwendung installiert wird) nicht diesen Sicherheitseinschränkungen.

Weitere Informationen zum Thema Sicherheit finden Sie im Flash Player Developer Center im Abschnitt Sicherheit.

Parameter

Verwandte API-Elemente

Ruft die methodName-Methode für eine mit der connect(connectionName)-Methode geöffnete Verbindung auf (im empfangenden LocalConnection-Objekt). Das mit der send()-Methode verwendete Objekt ist das sendende LocalConnection-Objekt. Die SWF-Dateien, die das sendende und das empfangende Objekt enthalten, müssen auf demselben Client-Computer ausgeführt werden.

Die Menge der Daten, die diesem Befehl als Parameter übergeben werden können, ist auf 40 Kilobyte begrenzt. Wenn send() einen ArgumentError-Fehler auslöst, die verwendete Syntax hingegen korrekt ist, versuchen Sie, die send()-Anfragen in mehrere Befehle aufzuteilen, die jeweils weniger als 40 K Daten enthalten.

Wie unter connect() beschrieben, wird die aktuelle Superdomäne standardmäßig zu connectionName hinzugefügt. Wenn Sie den Datenaustausch zwischen verschiedenen Domänen implementieren, müssen Sie connectionName sowohl im sendenden als auch im empfangenden LocalConnection-Objekt so definieren, dass die aktuelle Superdomäne nicht zu connectionName hinzugefügt wird. Hierzu stehen Ihnen zwei Methoden zur Wahl:

• Beginnen Sie connectionName sowohl für das sendende als auch für das empfangende LocalConnection-Objekt mit einem Unterstrich (_). Geben Sie in der Datei mit dem empfangenden Objekt mit LocalConnection.allowDomain() an, dass Verbindungen von allen Domänen akzeptiert werden. Mit dieser Implementierung können Sie sendende und empfangende Dateien in jeder Domäne speichern.
• Schließen Sie die Superdomäne in connectionName in das sendende LocalConnection-Objekt ein, z. B. myDomain.com:myConnectionName. Geben Sie im empfangenden Objekt mit LocalConnection.allowDomain() an, dass Verbindungen von der angegebenen Superdomäne akzeptiert werden (in diesem Fall myDomain.com) oder dass Verbindungen von allen Domänen akzeptiert werden.

Hinweis: Sie können in connectionName im empfangenden LocalConnection-Objekt keine Superdomäne angeben - dies ist nur im sendenden LocalConnection-Objekt möglich.

Bedenken Sie beim Einsatz dieser Methode das Sicherheitsmodell von Flash Player. In der Standardeinstellung wird ein LocalConnection-Objekt mit der Sandbox der erstellenden Datei verknüpft. Domänenübergreifende Aufrufe für LocalConnection-Objekte sind nur dann zulässig, wenn Sie in der empfangenden Datei die Methode LocalConnection.allowDomain() aufrufen. Für SWF-Inhalt, der im Browser ausgeführt wird, können Sie eine Datei daran hindern, diese Methode aufzurufen, indem Sie auf der HTML-Seite, die den SWF-Inhalt beinhaltet, den Parameter allowNetworking der Tags object und embed festlegen. In Adobe AIR unterliegt Inhalt in der Sicherheitssandbox der Anwendung (Inhalt, der mit der AIR-Anwendung installiert wird) nicht diesen Sicherheitseinschränkungen.

Weitere Informationen zum Thema Sicherheit finden Sie im Flash Player Developer Center im Abschnitt Sicherheit.

Parameter

Verwandte API-Elemente

Wird ausgelöst, wenn eine Ausnahme asynchron ausgelöst wird – das heißt, aus nativem asynchronem Code.

Dieses Ereignis verfügt über die folgenden Eigenschaften:

Wird ausgelöst, wenn mit einem Aufruf von LocalConnection.send() versucht wird, Daten an eine andere Sicherheitssandbox zu senden.

Dieses Ereignis verfügt über die folgenden Eigenschaften:

Verwandte API-Elemente

Wird ausgelöst, wenn der Status eines LocalConnection-Objekts protokolliert wird. Bei erfolgreichem Aufruf von LocalConnection.send() weist die Eigenschaft level des Ereignisobjekts status den Wert "status" auf. Wenn der Aufruf fehlschlägt, weist die Eigenschaft level den Wert "error" auf. Wenn die empfangende Datei die Verbindung ablehnt, kann der Aufruf ohne Benachrichtigung an die sendende Datei fehlschlagen.

Dieses Ereignis verfügt über die folgenden Eigenschaften:

Verwandte API-Elemente

In der SWF-Datei „LocalConnectionSenderExample“ wird eine LocalConnection-Instanz erstellt. Wenn der Benutzer auf die Schaltfläche klickt, wird die Methode call() verwendet, um die Methode lcHandler in der SWF-Datei aufzurufen. Der Verbindungsname ist „myConnection“ und der Inhalt der TextField-Instanz wird als Parameter übergeben.

In der SWF-Datei „LocalConnectionReceiverExample“ wird eine LocalConnection-Instanz erstellt und die Methode connect() wird aufgerufen. Diese Methode kennzeichnet die SWF-Datei als Empfänger von Meldungen an die Verbindung mit dem Namen „myConnection“. Darüber hinaus umfasst diese Klasse eine öffentliche Methode mit dem Namen lcHandler(). Diese Methode wird in der SWF-Datei „LocalConnectionSenderExample“ aufgerufen. Beim Aufrufen dieser Methode wird der als Parameter übergebene Text an die TextField-Instanz auf der Bühne angehängt.

Hinweis: Zum Testen des Beispiels müssen beide SWF-Dateien gleichzeitig auf denselben Computer geladen werden.

// Code in LocalConnectionSenderExample.as
package {
    import flash.display.Sprite;
    import flash.events.MouseEvent;
    import flash.net.LocalConnection;
    import flash.text.TextField;
    import flash.text.TextFieldType;
    import flash.events.StatusEvent;
    import flash.text.TextFieldAutoSize;

    public class LocalConnectionSenderExample extends Sprite {
        private var conn:LocalConnection;
        
        // UI elements
        private var messageLabel:TextField;
        private var message:TextField;
        private var sendBtn:Sprite;
        
        public function LocalConnectionSenderExample() {
            buildUI();
            sendBtn.addEventListener(MouseEvent.CLICK, sendMessage);
            conn = new LocalConnection();
            conn.addEventListener(StatusEvent.STATUS, onStatus);
        }
        
        private function sendMessage(event:MouseEvent):void {
            conn.send("myConnection", "lcHandler", message.text);
        }
        
        private function onStatus(event:StatusEvent):void {
            switch (event.level) {
                case "status":
                    trace("LocalConnection.send() succeeded");
                    break;
                case "error":
                    trace("LocalConnection.send() failed");
                    break;
            }
        }
        
        private function buildUI():void {
            const hPadding:uint = 5;
            // messageLabel
            messageLabel = new TextField();
            messageLabel.x = 10;
            messageLabel.y = 10;
            messageLabel.text = "Text to send:";
            messageLabel.autoSize = TextFieldAutoSize.LEFT;
            addChild(messageLabel);
            
            // message
            message = new TextField();
            message.x = messageLabel.x + messageLabel.width + hPadding;
            message.y = 10;
            message.width = 120;
            message.height = 20;
            message.background = true;
            message.border = true;
            message.type = TextFieldType.INPUT;
            addChild(message);
            
            // sendBtn
            sendBtn = new Sprite();
            sendBtn.x = message.x + message.width + hPadding;
            sendBtn.y = 10;
            var sendLbl:TextField = new TextField();
            sendLbl.x = 1 + hPadding;
            sendLbl.y = 1;
            sendLbl.selectable = false;
            sendLbl.autoSize = TextFieldAutoSize.LEFT;
            sendLbl.text = "Send";
            sendBtn.addChild(sendLbl);
            sendBtn.graphics.lineStyle(1);
            sendBtn.graphics.beginFill(0xcccccc);
            sendBtn.graphics.drawRoundRect(0, 0, (sendLbl.width + 2 + hPadding + hPadding), (sendLbl.height + 2), 5, 5);
            sendBtn.graphics.endFill();
            addChild(sendBtn);
        }
    }
}