LoaderContext  - AS3

Legt fest, ob Sie ein Loader-Objekt zum Importieren von Inhalt mit ausführbarem Code, zum Beispiel eine SWF-Datei, in die Sicherheitssandbox des Aufrufers verwenden können. Es gibt zwei betroffenen Importoperationen: die Loader.loadBytes()-Methode und die Loader.load()-Methode mit LoaderContext.securityDomain = SecurityDomain.currentDomain. (Die letztgenannte Operation wird in der AIR-Anwendungssandbox nicht unterstützt.) Wenn die allowCodeImport-Eigenschaft den Wert false hat sind diese Importoperationen auf sichere Operation, zum Beispiel das Laden von Bildern, beschränkt. Normale, nicht importierende SWF-Dateien, die mit der Loader.load()-Methode laden, sind vom Wert dieser Eigenschaft nicht betroffen.

Diese Eigenschaft ist hilfreich, wenn Sie Bildinhalte in Ihre Sandbox importieren möchten - zum Beispiel, wenn Sie ein Bild aus einer anderen Domäne replizieren oder verarbeiten möchten - aber nicht das Risiko eingehen möchten, eine SWF-Datei zu empfangen, wenn Sie nur eine Bilddatei erwartet haben. Da SWF-Dateien ActionScript-Code enthalten können, ist das Importieren einer SWF-Datei viel riskanter als das Importieren einer Bilddatei.

In AIR-Material in der Anwendungssandbox ist der Standardwert false. In Nicht-Anwendungsinhalten (wozu alle Inhalte in Flash Player gehören) ist der Standardwert true.

Die allowCodeImport-Eigenschaft wurde in Flash Player 10.1 und AIR 2.0 hinzugefügt. Diese Eigenschaft steht jedoch SWF-Dateien und AIR-Anwendungen aller Versionen zur Verfügung, wenn die Flash-Laufzeitumgebung dies unterstützt.

Verwandte API-Elemente

Alte Eigenschaft, die durch allowCodeImport ersetzt wurde, aus Kompatibilitätsgründen aber weiterhin unterstützt wird. Zuvor die einzige Operation, die von allowLoadBytesCodeExecution betroffen war, die Loader.loadBytes()-Methode, ab Flash Player 10.1 und AIR 2.0 ist jedoch auch die Import-Ladefunktion von Loader.load() mit LoaderContext.securityDomain = SecurityDomain.currentDomain betroffen. (Die letztgenannte Operation wird in der AIR-Anwendungssandbox nicht unterstützt.) Dieser Doppeleffekt führte dazu, dass der Eigenschaftenname allowLoadBytesCodeExecution zu spezifisch wurde, weshalb jetzt der Name allowCodeImport bevorzugt wird. Die Einstellung von allowCodeImport oder allowLoadBytesCodeExecution wirkt sich auf beide Werte aus.

Legt fest, ob Sie ein Loader-Objekt zum Importieren von Inhalt mit ausführbarem Code, zum Beispiel eine SWF-Datei, in die Sicherheitssandbox des Aufrufers verwenden können. Wenn diese Eigenschaft den Wert false hat sind diese Importoperationen auf sichere Operation, zum Beispiel das Laden von Bildern, beschränkt.

In AIR-Material in der Anwendungssandbox ist der Standardwert false. In anwendungsfremdem Inhalt ist der Standardwert true.

Verwandte API-Elemente

Gibt die Anwendungsdomäne an, die für die Loader.load()- oder Loader.loadBytes()-Methode verwendet werden soll. Verwenden Sie diese Eigenschaft nur beim Laden einer SWF-Datei, die in ActionScript 3.0 geschrieben wurde (nicht beim Laden eines Bilds oder einer SWF-Datei, die in ActionScript 1.0 oder ActionScript 2.0 geschrieben wurde).

Jede Sicherheitsdomäne ist in eine oder mehrere Anwendungsdomänen unterteilt, die durch ApplicationDomain-Objekte angegeben werden. Anwendungsdomänen dienen keinen Sicherheitszwecken, sondern der Verwaltung kooperierender Einheiten des ActionScript-Codes. Wenn Sie eine SWF-Datei von einer anderen Domäne laden und festlegen, dass die SWF-Datei in einer anderen Sicherheitsdomäne abgelegt werden kann, können Sie die Anwendungsdomäne nicht auswählen, in der die geladene SWF-Datei abgelegt wird. Wenn Sie eine Anwendungsdomäne angegeben haben, wird diese Auswahl ignoriert. Wenn Sie jedoch eine SWF-Datei in Ihre eigene Sicherheitsdomäne laden, da die SWF-Datei aus Ihrer eigenen Domäne stammt oder Sie sie in Ihre Sicherheitsdomäne importieren, können Sie die Anwendungsdomäne für die geladene SWF-Datei auswählen.

Sie können eine Anwendungsdomäne für LoaderContext.applicationDomain nur über Ihre eigene Sicherheitsdomäne übergeben. Beim Versuch, eine Anwendungsdomäne über eine andere Sicherheitsdomäne zu übergeben, wird eine SecurityError-Ausnahme ausgelöst.

Für die ApplicationDomain-Eigenschaft können Sie vier verschiedene Optionen auswählen:

• Untergeordnete Domäne von ApplicationDomain des ladenden Objekts Dies ist die Standardoption. Sie können diese Auswahl explizit mit der Syntax new ApplicationDomain(ApplicationDomain.currentDomain) angeben. Damit kann die geladene SWF-Datei direkt die Klassen der übergeordneten Domäne verwenden, beispielsweise durch Schreiben von new MyClassDefinedInParent(). Die übergeordnete Domäne kann diese Syntax jedoch nicht verwenden. Die übergeordnete Domäne kann die Klassen der untergeordneten Domäne nur verwenden, indem ApplicationDomain.getDefinition() aufgerufen wird, um die Klassen abzurufen. Der Vorteil dieser Auswahl liegt darin, dass kein Fehler ausgegeben wird, wenn die untergeordnete Domäne eine Klasse mit demselben Namen wie eine Klasse definiert, die bereits in der übergeordneten Domäne festgelegt ist. Die Unterklasse übernimmt einfach die Definition der übergeordneten Domäne für die entsprechende Klasse. Die widersprüchliche Definition der untergeordneten Domäne wird erst verwendet, wenn sie durch die untergeordnete oder übergeordnete Domäne durch Aufrufen der ApplicationDomain.getDefinition()-Methode abgerufen wird.
• Eigene ApplicationDomain des ladenden Objekts Sie können diese Anwendungsdomäne bei Verwendung von ApplicationDomain.currentDomain verwenden. Nach Abschluss des Ladevorgangs können in der übergeordneten und der untergeordneten Domäne jeweils die Klassen der anderen Domäne verwendet werden. Wenn die untergeordnete Domäne eine Klasse mit demselben Namen wie eine bereits in der übergeordneten Domäne festgelegte Klasse definiert, wird die Superklasse verwendet und die Unterklasse ignoriert.
• Untergeordnete Domäne von ApplicationDomain des Systems Sie können diese Anwendungsdomäne bei Verwendung von new ApplicationDomain(null) verwenden. Damit sind das ladende und das geladene Objekt vollkommen getrennt. Sie können gesonderte Versionen von Klassen mit demselben Namen erstellen, ohne dass Konflikte auftreten oder Prioritäten festgelegt werden. Die Klassen der jeweils anderen Seite werden nur durch Aufrufen der ApplicationDomain.getDefinition()-Methode angezeigt.
• Untergeordnete Domäne einer anderen ApplicationDomain Gelegentlich liegt möglicherweise eine komplexere ApplicationDomain-Hierarchie vor. Sie können eine SWF-Datei in einer beliebigen ApplicationDomain Ihrer eigenen SecurityDomain laden. Über new ApplicationDomain(ApplicationDomain.currentDomain.parentDomain.parentDomain) wird eine SWF-Datei beispielsweise in einer neuen untergeordneten Domäne der übergeordneten Domäne der übergeordneten Domäne der aktuellen Domäne geladen.

Nach Abschluss eines Ladevorgangs muss auf beiden Seiten (ladendes Objekt und geladenes Objekt) möglicherweise die eigene ApplicationDomain oder die ApplicationDomain der anderen Seite gesucht werden, um ApplicationDomain.getDefinition() aufzurufen. Jede Seite kann mithilfe von ApplicationDomain.currentDomain einen Verweis auf die eigene Anwendungsdomäne abrufen. Die ladende SWF-Datei kann über Loader.contentLoaderInfo.applicationDomain einen Verweis auf die ApplicationDomain der geladenen SWF-Datei abrufen. Wenn in der geladenen SWF-Datei die Art und Weise des Ladevorgangs bekannt ist, kann das ApplicationDomain-Objekt der ladenden SWF-Datei aufgerufen werden. Wenn die untergeordnete Domäne beispielsweise standardmäßig geladen wurde, kann die Anwendungsdomäne der ladenden SWF-Datei über ApplicationDomain.currentDomain.parentDomain abgerufen werden.

Weitere Informationen finden Sie im Abschnitt „ApplicationDomain-Klasse“ im Kapitel „Clientsystem-Umgebung“ im ActionScript 3.0 Entwicklerhandbuch.

Verwandte API-Elemente

Gibt an, ob der Anwendung vor dem Laden des eigentlichen Objekts eine URL-Richtliniendatei vom Server des zu ladenden Objekts herunterladen soll. Dieser Merker kann auf die Loader.load()-Methode, jedoch nicht auf die Loader.loadBytes()-Methode angewendet werden.

Setzen Sie diesen Merker auf true, wenn Sie ein Bild (JPEG-, GIF- oder PNG-Datei) von außerhalb der Domäne der aufrufenden SWF-Datei laden und davon ausgehen, dass Sie über ActionScript auf den Inhalt des Bilds zugreifen müssen. Beispiele für den Zugriff auf Bildinhalte sind u. a. Verweise auf die Loader.content-Eigenschaft zum Abrufen eines Bitmap-Objekts oder Aufrufe der BitmapData.draw()-Methode zum Abrufen einer Kopie der Pixel im geladenen Bild. Wenn Sie einen dieser Vorgänge starten, ohne während des Ladevorgangs einen Wert für checkPolicyFile angegeben zu haben, wird möglicherweise eine SecurityError-Ausnahme ausgegeben, da die erforderliche Richtliniendatei noch nicht heruntergeladen wurde.

Wenn Sie die Loader.load()-Methode aufrufen und LoaderContext.checkPolicyFile auf true gesetzt ist, beginnt die Anwendung erst dann, das in URLRequest.url angegebene Objekt herunterzuladen, wenn sie entweder eine relevanten URL-Richtliniendatei heruntergeladen oder festgestellt hat, dass keine Richtliniendatei existiert. Flash Player bzw. AIR berücksichtigen zuerst Richtliniendateien, die bereits heruntergeladen wurden, versuchen dann, eventuelle in Aufrufen der Security.loadPolicyFile()-Methode anstehende Richtliniendateien herunterzuladen, und dann, eine Richtliniendatei vom Standardpfad herunterzuladen, der URLRequest.url entspricht und der /crossdomain.xml auf dem gleichen Server wie URLRequest.url ist. In jedem Fall muss die gegebene Richtliniendatei unter URLRequest.url auf Grundlage des Speicherorts der Richtliniendatei vorhanden sein und die Datei muss den Zugriff mittels eines oder mehrerer <allow-access-from>-Tags zulassen.

Wenn Sie checkPolicyFile auf true setzen, wird der Hauptdownload, der in der Loader.load()-Methode angegeben ist, nicht geladen, bevor die Richtliniendatei vollständig verarbeitet wurde. Wenn die erforderliche Richtliniendatei vorhanden ist und ProgressEvent.PROGRESS- oder Event.COMPLETE-Ereignisse von der contentLoaderInfo-Eigenschaft des Loader-Objekts zurückgegeben wurden, ist der Download der Richtliniendatei abgeschlossen. Sie können dann Vorgänge durchführen, bei denen die Richtliniendatei erforderlich ist.

Wenn Sie checkPolicyFile auf true setzen und keine entsprechende Richtliniendatei vorhanden ist, wird eine Fehlermeldung erst bei einem Vorgang ausgegeben, bei dem eine SecurityError-Ausnahme ausgelöst wird. Nachdem das LoaderInfo-Objekt ein ProgressEvent.PROGRESS- oder Event.COMPLETE-Ereignis ausgelöst hat, können Sie jedoch testen, ob eine entsprechende Richtliniendatei gefunden wurde, indem Sie den Wert der LoaderInfo.childAllowsParent-Eigenschaft überprüfen.

Wenn Sie keinen Zugriff auf Pixelebene auf das geladene Bild benötigen, setzen Sie die checkPolicyFile-Eigenschaft auf true. In diesem Fall ist es nicht erforderlich, nach einer Richtliniendatei zu suchen, da dies möglicherweise den Start des Downloads verzögert und unter Umständen unnötigerweise Netzwerkbandbreite beansprucht.

Setzen Sie checkPolicyFile zudem nicht auf true, wenn Sie eine SWF-Datei mit der Loader.load()-Methode herunterladen. Dies liegt darin begründet, dass SWF-zu-SWF-Berechtigungen nicht über Richtliniendateien sondern durch die Security.allowDomain()-Methode gesteuert werden. Daher hat checkPolicyFile beim Laden einer SWF-Datei keine Auswirkung. In diesem Fall ist es nicht erforderlich, nach einer Richtliniendatei zu suchen, da dies möglicherweise den Download der SWF-Datei verzögert und unter Umständen unnötigerweise Netzwerkbandbreite beansprucht. (In Flash Player oder AIR kann nicht festgestellt werden, ob eine SWF-Datei oder ein Bild heruntergeladen wird, da die Richtliniendatei vor diesem Download heruntergeladen wird.)

Bei Verwendung von checkPolicyFile beim Herunterladen eines Objekts von einer URL, bei der möglicherweise serverseitige HTTP-Weiterleitungen verwendet werden, ist Folgendes zu beachten: Richtliniendateien werden immer von der entsprechenden ursprünglichen URL abgerufen, die Sie in URLRequest.url angeben. Wenn das endgültige Objekt aufgrund von HTTP-Weiterleitungen von einer anderen URL stammt, gelten die ursprünglich heruntergeladenen Richtliniendateien möglicherweise nicht für die endgültige URL des Objekts. Dies ist jedoch die URL, die bei Sicherheitsentscheidungen von Bedeutung ist. In diesem Fall können Sie den Wert von LoaderInfo.url nach dem Empfangen eines ProgressEvent.PROGRESS- oder Event.COMPLETE-Ereignisses überprüfen, in dem die endgültige URL des Objekts angegeben ist. Rufen Sie dann die Security.loadPolicyFile()-Methode mit der URL einer Richtliniendatei auf, die auf der endgültigen URL des Objekts beruht. Rufen Sie anschließend den Wert von LoaderInfo.childAllowsParent auf, bis er sich in true ändert.

Sie brauchen diese Eigenschaft nicht für AIR-Inhalt einstellen, der in der Anwendungssandbox ausgeführt wird. Inhalt in der AIR-Anwendungssandbox kann die BitmapData.draw()-Methode über einen beliebigen geladenen Bildinhalt als Quelle aufrufen.

Verwandte API-Elemente

Gibt an, ob Bitmapbilddaten dekodiert werden, wenn sie gebraucht werden, oder wenn sie geladen wurden.

Mit der Standardrichtlinie, ImageDecodingPolicy.ON_DEMAND dekodiert die Laufzeitumgebung die Bilddaten, wenn die Daten (für die Anzeige oder zu anderen Zwecken) gebraucht werden. Diese Richtlinie behält das Verhalten bei, das frühere Versionen der Laufzeitumgebung verwendet haben.

Mit der Richtlinie ImageDecodingPolicy.ON_LOAD dekodiert die Laufzeitumgebung die Bilder sofort, nachdem sie geladen wurden, und bevor das complete-Ereignis abgesetzt wird. Das Dekodieren von Bildern beim Laden statt bei Bedarf kann die Leistung der Animation und der Benutzeroberfläche steigern. Sie können Verbesserungen bemerken, wenn mehrere geladene Bilder in schneller Folge angezeigt werden. Beispiele für die schnelle Anzeige mehrerer Bilder sind Bildlauflisten oder Cover-Flow-Steuerungen. Auf der anderen Seite kann die Verwendung der onLoad-Richtlinie aber auch dazu führen, dass die Speichernutzung Ihrer Anwendung unvermittelt ansteigen kann. Es können sich mehr dekodierte Bilddaten im Arbeitsspeicher befinden als dies mit der onDemand-Richtlinie der Fall wäre.

Mit beiden Richtlinien verwendet die Laufzeitumgebung dasselbe Cache- und Flush-Verhalten, nachdem das Bild dekodiert wurde. Die Laufzeitumgebung kann die dekodierten Daten jederzeit aus dem Arbeitsspeicher entfernen und das Bild erneut dekodieren, wenn es wieder benötigt wird.

So legen Sie die Richtlinie für die Bilddekodierung fest (zum Beispiel auf ON_LOAD):

     var loaderContext:LoaderContext = new LoaderContext(); 
     loaderContext.imageDecodingPolicy = ImageDecodingPolicy.ON_LOAD 
     var loader:Loader = new Loader(); 
     loader.load(new URLRequest("http://www.adobe.com/myimage.png"), loaderContext);
     

Verwandte API-Elemente

Ein Objekt, das die Parameter enthält, die an das LoaderInfo-Objekt des Inhalts übergeben werden sollen.

Normalerweise wird der Wert der contentLoaderInfo.parameters-Eigenschaft durch die Analyse der anfordernden URL erhalten. Wenn parameters gesetzt wurde, bezieht contentLoaderInfo.parameters seinen Wert vom LoaderContext-Objekt anstatt von der anfordernden URL. Die Variable parameters akzeptiert nur Objekte, die Namen-Wert-Stringpaare enthalten, ähnlich wie URL-Parameter. Wenn das Objekt keine Namen-Wert-Stringpaare enthält, wird ein IllegalOperationError ausgegeben.

Der Zweck dieser API ist es, der ladenden SWF-Datei zu ermöglichen, ihre Parameter an eine geladene SWF-Datei weiterzuleiten. Diese Funktion ist besonders hilfreich, wenn Sie die loadBytes()-Methode verwenden, da LoadBytes kein Mittel bereitstellt, Parameter über die URL weiterzugeben. Parameter lassen sich nur an eine andere AS3-SWF-Dteai weiterleiten; eine AS1- oder AS2-SWF-Datei kann die Parameter nicht in einer zugänglichen Form erhalten, obwohl das loaderInfo.parameters-AS3-Objekt des AVM1Movies das weitergegebene Objekt ist.

Betrachten Sie zum Beispiel die folgende URL:

http://yourdomain/users/jdoe/test01/child.swf?foo=bar;

Der folgende Code verwendet die LoaderContext.parameters-Eigenschaft, um einen an diese URL übergebenen Parameter zu replizieren:

      import flash.system.LoaderContext; 
      import flash.display.Loader; 
      var l:Loader = new Loader(); 
      var lc:LoaderContext = new LoaderContext; 
      lc.parameters = { "foo": "bar" }; 
      l.load(new URLRequest("child.swf"), lc);
     

Um zu überprüfen, ob der Parameter korrekt übergeben wurde, verwenden Sie die folgende trace-Anweisung, nachdem Sie den Code ausgeführt haben:

trace(loaderInfo.parameters.foo);

Wenn der Inhalt erfolgreich geladen wurde, gibt diese trace-Anweisung „bar“ aus.

Das übergeordnete Element, dem der Loader den geladenen Inhalt hinzuzufügen versucht.

Nachdem der Inhalt vollständig geladen wurde, wird das Loader-Objekt normalerweise zum übergeordneten Element des Inhalts. Wenn requestedContentParent festgelegt wurde, wird das dadurch angegebene Objekt zum übergeordneten Element, solange kein Laufzeitfehler die Zuweisung verhindert. Diese Neuzuweisung des übergeordneten Elements kann auch nach dem complete-Ereignis ohne Verwendung dieser Eigenschaft erfolgen. Bei der Angabe des übergeordneten Elements durch LoaderContext.requestedContentParent sind jedoch keine zusätzlichen Ereignisse erforderlich.

LoaderContext.requestedContentParent legt das gewünschte übergeordnete Element fest, bevor Skripts aus Bild Eins im geladenen Inhalt ausgeführt werden, aber nachdem der Konstruktor ausgeführt wurde. Wenn requestedContentParent den Wert null hat (den Standardwert), wird das Loader-Objekt das übergeordnete Element des Inhalts.

Wenn es sich bei dem geladenen Inhalt um ein AVM1Movie-Objekt handelt, oder wenn beim Aufruf von addChild() für das requestedContentParent-Objekt ein Fehler auftritt, geschieht Folgendes:

• Das Loader-Objekt wird das übergeordnete Element des geladenen Inhalts.
• Die Laufzeitumgebung setzt ein AsyncErrorEvent ab.

Wenn das angeforderte übergeordnete Element und der geladene Inhalt sich in unterschiedlichen Sicherheits-Sandboxen befinden, und wenn das angeforderte übergeordnete Element keinen Zugriff auf den geladenen Inhalt hat, geschieht Folgendes:

• Der Loader wird das übergeordnete Element des geladenen Inhalts.
• Die Laufzeitumgebung setzt ein SecurityErrorEvent ab.

Der folgende Code verwendet requestedContentParent, um den geladenen Inhalt in einem Sprite-Objekt zu platzieren:

      import flash.system.LoaderContext; 
      import flash.display.Loader; 
      import flash.display.Sprite; 
     
      var lc:LoaderContext = new LoaderContext(); 
      var l:Loader = new Loader(); 
      var s:Sprite = new Sprite(); 
      lc.requestedContentParent = s; 
      addChild(s); 
      l.load(new URLRequest("child.swf"), lc);
     

Wenn dieser Code ausgeführt wird, erscheint die untergeordnete SWF-Datei auf der Bühne. Diese Tatsache bestätigt, dass das Sprite-Objekt, das Sie der Bühne hinzugefügt haben, das übergeordnete Element der geladenen untergeordneten SWF-Datei ist.

Gibt die bei einem Loader.load()-Vorgang zu verwendende Sicherheitsdomäne an. Verwenden Sie diese Eigenschaft nur beim Laden einer SWF-Datei (und nicht beim Laden eines Bilds).

Die Auswahl der Sicherheitsdomäne ist nur beim Laden einer SWF-Datei von Bedeutung, die möglicherweise von einer anderen Domäne (einem anderen Server) als die ladende SWF-Datei stammt. Wenn Sie eine SWF-Datei von Ihrer eigenen Domäne laden, wird sie immer in Ihrer Sicherheitsdomäne abgelegt. Wenn Sie jedoch eine SWF-Datei von einer anderen Domäne laden, stehen Ihnen zwei Optionen zur Verfügung. Sie können festlegen, dass die geladene SWF-Datei in ihrer „natürlichen“ Sicherheitsdomäne abgelegt wird, die sich von der der ladenden SWF-Datei unterscheidet. Dies ist die Standardeinstellung. Die andere Möglichkeit besteht darin, dass Sie festlegen, dass die geladene SWF-Datei in der gleichen Sicherheitsdomäne wie die ladende SWF-Datei abgelegt wird. Setzen Sie dazu myLoaderContext.securityDomain auf den gleichen Wert wie SecurityDomain.currentDomain. Dies wird als importiertes Laden bezeichnet und entspricht sicherheitstechnisch dem Kopieren der geladenen SWF-Datei auf Ihren Server und dem anschließenden Laden der Datei von diesem Server. Damit das importierte Laden erfolgreich durchgeführt wird, muss der Server der geladenen SWF-Datei über eine Richtliniendatei verfügen, die in der Domäne der ladenden SWF-Datei als vertrauenswürdig eingestuft ist.

Sie können für LoaderContext.securityDomain nur Ihre eigene Sicherheitsdomäne übergeben. Beim Versuch, andere Sicherheitsdomänen zu übergeben, wird eine SecurityError-Ausnahme ausgegeben.

Material in der AIR-Anwendungs-Sandbox kann kein Material aus anderen Sandboxen in seine SecurityDomain laden.

Weitere Informationen finden Sie im Kapitel „Sicherheit“ des ActionScript 3.0 Entwicklerhandbuchs.

Verwandte API-Elemente

Erstellt ein neues LoaderContext-Objekt mit den angegebenen Einstellungen. Ausführliche Informationen zu diesen Einstellungen finden Sie in den Beschreibungen der Eigenschaften für diese Klasse.

Verwandte API-Elemente