LoaderContext  - AS3

Geeft aan of u een Loader-object kunt gebruiken voor het importeren van inhoud met uitvoerbare code, zoals een SWF-bestand, in de beveiligingssandbox van de aanroeper. Het gaat hierbij om twee importbewerkingen, namelijk de methode Loader.loadBytes() en de methode Loader.load() met LoaderContext.securityDomain = SecurityDomain.currentDomain. (De AIR-toepassingssandbox biedt geen ondersteuning voor de laatstgenoemde bewerking.) Als de eigenschap allowCodeImport is ingesteld op false, zijn deze importbewerkingen beperkt tot veilige bewerkingen, zoals het laden van afbeeldingen. Het laden van een normaal SWF-bestand zonder importbewerkingen met de methode Loader.load(), wordt niet beïnvloed door deze eigenschap.

Deze eigenschap is handig als u afbeeldingsinhoud in uw sandbox wilt importeren, bijvoorbeeld als u een afbeelding uit een ander domein wilt repliceren of verwerken, en u hiervoor een afbeeldingsbestand verwacht maar in werkelijkheid een SWF-bestand ontvangt, met alle risico's van dien. Aangezien SWF-bestanden ActionScript-code kunnen bevatten, brengt het importeren van een SWF-bestand veel meer risico's met zich mee dan het importeren van een afbeeldingsbestand.

Voor AIR-inhoud in de toepassingssandbox is de standaardwaarde false. Voor inhoud die niet uit de toepassing afkomstig is (waaronder alle Flash Player-inhoud), is de standaardwaarde true.

De eigenschap allowCodeImport is toegevoegd aan Flash Player 10.1 en AIR 2.0. Deze eigenschap is echter beschikbaar gesteld voor alle SWF-bestanden en AIR-toepassingen van alle versies wanneer de Flash-runtime hier ondersteuning voor biedt.

Verwante API-elementen

Verouderde eigenschap. Is vervangen door allowCodeImport, maar wordt om compatibiliteitsredenen nog steeds ondersteund. Voorheen was de enige bewerking die werd beïnvloed door allowLoadBytesCodeExecution de methode Loader.loadBytes(), maar vanaf Flash Player 10.1 en AIR 2.0 wordt de bewerking met betrekking tot importeren en laden van Loader.load() met LoaderContext.securityDomain = SecurityDomain.currentDomain eveneens beïnvloed. (De AIR-toepassingssandbox biedt geen ondersteuning voor de laatstgenoemde bewerking.) Door dit tweeledige effect was de eigenschapsnaam allowLoadBytesCodeExecution te specifiek geworden, dus nu is allowCodeImport de eigenschapsnaam met de voorkeur. Het instellen van allowCodeImport heeft invloed op de waarde van allowLoadBytesCodeExecution en omgekeerd.

Geeft aan of u een Loader-object kunt gebruiken voor het importeren van inhoud met uitvoerbare code, zoals een SWF-bestand, in de beveiligingssandbox van de aanroeper. Als deze eigenschap is ingesteld op false, zijn deze importbewerkingen beperkt tot veilige bewerkingen, zoals het laden van afbeeldingen.

Voor AIR-inhoud in de toepassingssandbox is de standaardwaarde false. In content van een andere toepassing is de standaardwaarde true.

Verwante API-elementen

Geeft het toepassingsdomein op dat moet worden gebruikt voor de methode Loader.load() of Loader.loadBytes(). Gebruik deze eigenschap uitsluitend wanneer u een SWF-bestand laadt dat in ActionScript 3.0 is geschreven (geen afbeelding of SWF-bestand dat in ActionScript 1.0 of ActionScript 2.0 is geschreven).

Elk beveiligingsdomein bestaat uit een of meer toepassingsdomeinen die door objecten ApplicationDomain worden vertegenwoordigd. Toepassingsdomeinen worden niet gebruikt voor beveiligingsdoeleinden; ze zijn bedoeld voor het beheer van samenwerkende stukken ActionScript-code. Wanneer u een SWF-bestand van een ander domein laadt en het in een afzonderlijk beveiligingsdomein laat plaatsen, kunt u niet kiezen in welk toepassingsdomein het geladen SWF-bestand wordt geplaatst. En als u een toepassingsdomein hebt opgegeven, wordt deze genegeerd. Als u echter een SWF-bestand in uw eigen beveiligingsdomein laadt (omdat het SWF-bestand uit uw eigen domein afkomstig is of u importeert het in een beveilgingsdomein), kunt u zelf het toepassingsdomein voor het geladen SWF-bestand kiezen.

U kunt een toepassingsdomein alleen vanuit uw eigen beveiligingsdomein doorgeven in LoaderContext.applicationDomain. Wanneer u probeert een toepassingsdomein door te geven van een willekeurig beveiligingsdomein, wordt een uitzondering SecurityError gegenereerd.

U kunt uit de volgende vier soorten ApplicationDomain-eigenschappen kiezen:

• Onderliggend domein van toepassingsdomein van de lader. Standaardinstelling. U kunt deze keuze expliciet aangeven met de syntaxis new ApplicationDomain(ApplicationDomain.currentDomain). Het geladen SWF-bestand kan nu de klassen van het bovenliggende domein direct gebruiken, bijvoorbeeld door new MyClassDefinedInParent() te schrijven. Het bovenliggende domein kan deze syntaxis echter niet gebruiken. Wanneer het bovenliggende domein de klassen van het onderliggende domein wil gebruiken, moet het ApplicationDomain.getDefinition() aanroepen om deze op te halen. Het voordeel van deze keuze is dat als het onderliggende domein een klasse definieert met dezelfde naam als een klasse die al door het bovenliggende domein is gedefinieerd, er geen fout wordt gegenereerd. Het onderliggende domein overerft de bovenliggende definitie van die klasse en de definitie van het onderliggende domein die het conflict veroorzaakt wordt niet meer gebruikt, tenzij het onderliggende of bovenliggende domein de methode ApplicationDomain.getDefinition() aanroept om het op te halen.
• Eigen toepassingsdomein van de lader. U gebruikt dit toepassingsdomein wanneer u ApplicationDomain.currentDomain gebruikt. Wanneer het laden is voltooid, kunnen de bovenliggende en onderliggende domeinen elkaars klassen rechtstreeks gebruiken. Wanneer het onderliggende domein een klasse probeert te definiëren met dezelfde naam als een klasse die al door het bovenliggende domein is gedefinieerd, wordt de bovenliggende klasse gebruikt en wordt de onderliggende klasse gegenereerd.
• Onderliggend domein van toepassingsdomein van het systeem. U gebruikt dit toepassingsdomein wanneer u new ApplicationDomain(null) gebruikt. Hierdoor worden het ladende domein en het domein waaruit wordt geladen volledig gescheiden, waardoor ze afzonderlijke versies van klassen met dezelfde naam kunnen definiëren zonder dat er conflicten ontstaan of de een de ander domineert. De enige manier waarop een van beide de klassen van de ander ziet, is door de methode ApplicationDomain.getDefinition() aan te roepen.
• Onderliggend domein van een ander toepassingsdomein. Soms hebt u een complexer hiërarchie van toepassingsdomeinen. U kunt een SWF-bestand in een willekeurig toepassingsdomein van uw eigen beveiligingsdomein laden. Met new ApplicationDomain(ApplicationDomain.currentDomain.parentDomain.parentDomain) wordt bijvoorbeeld een SWF-bestand in een nieuw onderliggend domein van het huidige bovenliggende domein van het bovenliggende domein geladen.

Wanneer het laden is voltooid, moet een van beide domeinen (dat bezig is met laden of waaruit wordt geladen) mogelijk zijn eigen toepassingsdomein of dat van het andere domein zoeken om ApplicationDomain.getDefinition() aan te roepen. Allebei kunnen ze een verwijzing ophalen naar het eigen toepassingsdomein met ApplicationDomain.currentDomain. Het ladende SWF-bestand kan een verwijzing naar het toepassingsdomein van het geladen SWF-bestand ophalen via Loader.contentLoaderInfo.applicationDomain. Wanneer de laadprocedure voor het geladen SWF-bestand bekend is, kan dit bestand naar het object ApplicationDomain van het ladende SWF-bestand navigeren. Wanneer het onderliggende item bijvoorbeeld standaard is geladen, vindt dit het toepassingsdomein van het SWF-bestand dat wordt geladen viaApplicationDomain.currentDomain.parentDomain.

Zie het gedeelte 'ApplicationDomain-klasse' van het hoofdstuk 'Clientsysteemomgeving' in de Adobe ActionScript 3.0-ontwikkelaarsgids.

Verwante API-elementen

Hiermee wordt aangegeven of moet worden geprobeerd een bestand met URL-beleid te downloaden van de server van het geladen object voordat het object zelf wordt geladen. Deze markering is van toepassing op de methode Loader.load(), maar niet op de methode Loader.loadBytes().

Stel deze markering in op true wanneer u een afbeelding (JPEG, GIF of PNG) laadt uit een ander domein dan het domein waarin het aanroepende SWF-bestand zich bevindt en u verwacht dat u de inhoud van die afbeelding via ActionScript moet openen. Afbeeldingsinhoud kan ook worden geopend door te verwijzen naar de eigenschap Loader.content om een kopie van een object Bitmap op te halen en door de methode BitmapData.draw() aan te roepen om een kopie van de pixels van de geladen afbeelding op te halen. Wanneer u een van deze bewerkingen probeert uit te voeren zonder checkPolicyFile te hebben opgegeven bij het laden, kan een uitzondering SecurityError optreden omdat het benodigde beleidsbestand nog niet is gedownload.

Wanneer u de methode Loader.load() aanroept terwijlLoaderContext.checkPolicyFile op true is ingesteld, wordt pas met het downloaden van het opgegeven object in URLRequest.url begonnen wanneer een relevant URL-beleidsbestand is gedownload of wanneer is vastgesteld dat een dergelijk beleidsbestand niet bestaat. In Flash Player of AIR worden eerst beleidsbestanden gebruikt die al zijn gedownload, vervolgens wordt geprobeerd de beleidsbestanden in behandeling te downloaden die in aanroepen naar de methode Security.loadPolicyFile() zijn opgegeven en ten slotte wordt geprobeerd een beleidsbestand te downloaden van de standaardlocatie die overeenkomt met URLRequest.url, dat /crossdomain.xml is op dezelfde server als URLRequest.url. In elk geval moet het gegeven beleidsbestand bestaan op URLRequest.url vanwege de locatie van het bestand, en moet het bestand toegang toestaan door middel van een of meer <allow-access-from>-tags.

Als u checkPolicyFile instelt op true, wordt de hoofddownload die is opgegeven in de methode Loader.load() pas geladen wanneer het beleidsbestand volledig is verwerkt. Wanneer het benodigde beleidsbestand bestaat en u de gebeurtenissen ProgressEvent.PROGRESS of Event.COMPLETE van de eigenschap contentLoaderInfo van het object Loader ontvangt, is het beleidsbestand gedownload en kunt u veilig bewerkingen uitvoeren waarvoor het beleidsbestand nodig is.

Wanneer u checkPolicyFile instelt op true en er geen relevant beleidsbestand wordt gevonden, ontvangt u pas een foutmelding wanneer u een bewerking probeert uit te voeren die een uitzondering SecurityError genereert. Zodra het object LoaderInfo echter een gebeurtenis ProgressEvent.PROGRESS of Event.COMPLETE verzendt, kunt u testen of een relevant beleidsbestand is gevonden door de waarde te controleren van de eigenschap LoaderInfo.childAllowsParent.

Wanneer u geen toegang op pixelniveau hoeft te hebben voor de afbeelding die u laadt, moet u de eigenschapcheckPolicyFile niet op true instellen. In dat geval is het niet nuttig te controleren of er een beleidsbestand is, omdat hierdoor mogelijk uw download vertraagd wordt gestart en onnodig netwerkbandbreedte wordt gebruikt.

Stel bovendien checkPolicyFile in op true wanneer u de methode Loader.load() gebruikt om een SWF-bestand te downloaden. Bevoegdheden tussen SWF-bestanden worden namelijk niet door beleidsbestanden beheerd, maar door de methode Security.allowDomain() en checkPolicyFile heeft geen effect wanneer u een SWF-bestand downloadt. In dat geval is het niet nuttig te controleren of er een beleidsbestand is, omdat hierdoor mogelijk het downloaden van het SWF-bestand wordt vertraagd en onnodig netwerkbandbreedte wordt gebruikt. (In Flash Player of AIR kan niet worden vastgesteld of uw hoofddownload een SWF-bestand of een afbeelding is, omdat het beleidsbestand wordt gedownload voordat de hoofddownload plaatsvindt.)

Ga zorgvuldig met checkPolicyFile om wanneer u een object downloadt van een URL waarvoor mogelijk HTTP-serveromleidingen worden gebruikt. Beleidsbestanden worden altijd opgehaald uit de overeenkomstige oorspronkelijke URL die u opgeeft in URLRequest.url. Wanneer het laatste object van een andere URL afkomstig is als gevolg van HTTP-omleidingen, zijn de oorspronkelijk gedownloade beleidsbestanden mogelijk niet van toepassing op de URL van het laatste object. Dit is de URL die van belang is in beveiligingskwesties. In dit geval kunt u de waarde van LoaderInfo.url bekijken nadat u een gebeurtenis ProgressEvent.PROGRESS of Event.COMPLETE hebt ontvangen die de definitieve URL van het object aangeeft. Vervolgens roept u de methode Security.loadPolicyFile() aan met de URL van een beleidsbestand die op de definitieve URL van het object is gebaseerd. Vervolgens pollt u de waarde van LoaderInfo.childAllowsParent totdat het true wordt.

U hoeft deze eigenschap niet in te stellen voor AIR-inhoud die wordt uitgevoerd in de toepassingssandbox. Inhoud in de sandbox van de AIR-toepassing kan de methode BitmapData.draw() aanroepen met de inhoud van elke geladen afbeelding als bron.

Verwante API-elementen

Hiermee wordt aangegeven of bitmapafbeeldingsgegevens moeten worden gedecodeerd wanneer deze worden gebruikt of wanneer ze worden geladen.

Onder het standaardbeleid ImageDecodingPolicy.ON_DEMAND worden de afbeeldingsgegevens door de runtime gedecodeerd wanneer de gegevens nodig zijn (voor weergave of voor andere doeleinden). In dit beleid wordt het decoderingsgedrag uit eerdere versies van de runtime gehandhaafd.

Onder het beleid ImageDecodingPolicy.ON_LOAD decodeert de runtime de afbeelding direct nadat deze is geladen en voordat de gebeurtenis complete wordt verzonden. Het decoderen van afbeeldingen tijdens het laden in plaats van wanneer u ze nodig hebt, leidt wellicht tot betere animaties en prestaties van de gebruikersinterface. U merkt de verbeteringen wanneer meerdere geladen afbeeldingen snel na elkaar worden weergegeven. Voorbeelden van afbeeldingen die snel worden weergegeven, zijn schuiflijsten of een Cover Flow-weergave. Daar staat tegenover dat het piekgeheugenverbruik van uw toepassing kan toenemen wanneer de beleidsinstelling onLoad altijd wordt gebruikt. Er kunnen meer gedecodeerde afbeeldingsgegevens in het geheugen staan dan wanneer de beleidsinstelling onDemand wordt gebruikt.

Bij beide beleidsinstellingen gebruikt de runtime hetzelfde cache- en verwijdergedrag nadat de afbeelding is gedecodeerd. De runtime kan de gedecodeerde gegevens op elk moment verwijderen en de afbeelding opnieuw decoderen wanneer dit weer nodig is.

Zo stelt u het beleid voor het decoderen van afbeeldingen in (bijvoorbeeld op 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);
     

Verwante API-elementen

Een object met de parameters die moeten worden doorgegeven aan het LoaderInfo-object van de inhoud.

Normaal gesproken wordt de waarde van de eigenschap contentLoaderInfo.parameters verkregen door het parseren van de URL die het verzoek indient. Als de parameters var wordt ingesteld, krijgt contentLoaderInfo.parameters zijn waarde van het LoaderContext-object, en niet van de URL die het verzoek indient. De parameters var accepteert alleen objecten met naam-waardeparen van het type String, vergelijkbaar met URL-parameters. Als het object geen naam-waardeparen van het type String bevat, treedt een IllegalOperationError op.

Met behulp van deze API kan een SWF-bestand dat wordt geladen zijn parameters doorsturen naar een geladen SWF-bestand. Deze functionaliteit is vooral handig wanneer u de methode loadBytes() gebruikt, aangezien u met LoadBytes geen parameters kunt doorgeven via de URL. De parameters kunnen alleen correct worden doorgegeven aan een ander AS3 SWF-bestand; AS1 SWF-bestanden en AS2 SWF-bestanden kunnen de parameters niet in een toegankelijke indeling ontvangen, ook al is het AS3 loaderInfo.parameters-object van AVM1Movie het doorgegeven object.

Neem bijvoorbeeld de volgende URL:

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

In de volgende code wordt de eigenschap LoaderContext.parameters gebruikt om een parameter te repliceren die is doorgegeven aan deze URL:

      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);
     

Gebruik de volgende trace-instructie nadat u deze code hebt uitgevoerd om te controleren of de parameter goed is doorgegeven:

trace(loaderInfo.parameters.foo);

Als de inhoud met succes is geladen, wordt met deze trace "bar" afgedrukt.

Het bovenliggende element waaraan de Loader probeert de geladen inhoud toe te voegen.

Wanneer de inhoud volledig is geladen, wordt het Loader-object het bovenliggende element van de inhoud. Als requestedContentParent is ingesteld, wordt het opgegeven object het bovenliggende element, tenzij deze toewijzing mislukt door een runtimefout. Dit opnieuw instellen van het bovenliggende element kan ook na de complete-gebeurtenis worden uitgevoerd, en zonder gebruik te maken van deze eigenschap. Als u het bovenliggende element echter opgeeft met LoaderContext.requestedContentParent, worden extra gebeurtenissen geëlimineerd.

Met LoaderContext.requestedContentParent wordt het gewenste bovenliggende element ingesteld voordat 'frame one'-scripts in de geladen inhoud worden uitgevoerd, maar nadat de constructor is uitgevoerd. Als de waarde van requestedContentParent is ingesteld op null (standaard), wordt het Loader-object het bovenliggende element van de inhoud.

Als de geladen inhoud bestaat uit een AVM1Movie-object, of als een fout optreedt wanneer addChild() wordt aangeroepen voor het requestedContentParent-object, gebeurt het volgende:

• Het Loader-object wordt het bovenliggende element van de geladen inhoud.
• De runtime verzendt een AsyncErrorEvent.

Als het opgevraagde bovenliggende element en de gelanden inhoud zich in verschillende beveiligingssandboxes bevinden en als het opgevraagde bovenliggende element geen toegang heeft tot de geladen inhoud, gebeurt het volgende:

• De Loader wordt het bovenliggende element van de geladen inhoud.
• De runtime verzendt een SecurityErrorEvent.

In de volgende code wordt requestedContentParent gebruikt om de geladen inhoud in een Sprite-object te plaatsen.

      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);
     

Wanneer deze code wordt uitgevoerd, wordt het onderliggende SWF-bestand in het werkgebied weergegeven. Dit feit bevestigt dat het Sprite-object dat u aan het werkgebied hebt toegevoegd, het bovenliggende object is van het geladen onderliggende SWF-bestand.

Geeft het beveiligingsdomein op dat moet worden gebruikt voor de bewerking Loader.load(). Gebruik deze eigenschap uitsluitend wanneer u een SWF-bestand laadt (geen afbeelding).

Het kiezen van een beveiligingsdomein is alleen relevant wanneer u een SWF-bestand laadt dat mogelijk van een ander domein afkomstig is (een andere server) dan het SWF-bestand dat bezig is met laden. Wanneer u een SWF-bestand uit uw eigen domein laadt, wordt deze altijd in uw beveiligingsdomein geplaatst. Maar wanneer u een SWF-bestand uit een ander domein laadt, hebt u de volgende twee opties: U kunt toestaan dat het geladen SWF-bestand in zijn 'natuurlijke' beveiligingsdomein wordt geplaatst, dat een andere is dan die van het SWF-bestand dat wordt geladen. Dit is dan het standaardbeveiligingsdomein. De andere optie is om op te geven dat u het geladen SWF-bestand in hetzelfde beveiligingsdomein wilt plaatsen als het ladende SWF-bestand door in te stellen datmyLoaderContext.securityDomain gelijk is aanSecurityDomain.currentDomain. Dit wordt importladen genoemd en is vanwege beveiligingsredenen gelijk aan het kopiëren van het geladen SWF-bestand naar uw eigen server waarna het bestand wordt geladen. U kunt importladen alleen toepassen wanneer de server van het geladen SWF-bestand een beleidsbestand heeft dat het domein van het ladende SWF-bestand vertrouwt.

U kunt alleen uw eigen beveiligingsdomein in LoaderContext.securityDomain doorgeven. Wanneer u probeert een ander beveiligingsdomein door te geven, wordt een uitzondering SecurityError geretourneerd.

Inhoud in de beveiligingssandbox van de AIR-toepassing kan geen inhoud van andere sandboxen laden naar het SecurityDomain.

Raadpleeg het hoofdstuk Beveiliging in de Adobe ActionScript 3.0-ontwikkelaarsgids voor meer informatie.

Verwante API-elementen

Maakt een nieuw object LoaderContext met de opgegeven instellingen. Zie de beschrijving van de eigenschappen van deze klasse voor volledige informatie over deze instellingen.

Verwante API-elementen