LoaderContext  - AS3

Anger om du kan använda ett Loader-objekt för att importera innehåll med körbar kod, t.ex. en SWF-fil, till anroparens säkerhetssandlåda. Det finns två importåtgärder som påverkas: metoden Loader.loadBytes() och metoden Loader.load() med LoaderContext.securityDomain = SecurityDomain.currentDomain. (Den senare åtgärden stöds inte i programsandlådan i AIR.) Importåtgärderna begränsas till säkra åtgärder, t.ex. inläsning av bilder, om egenskapen allowCodeImport är false. Normal inläsning av en SWF-fil utan import med metoden Loader.load() påverkas inte av den här egenskapens värde.

Egenskapen är användbar när du vill importera bildinnehåll till sandlådan, t.ex. om du vill replikera eller bearbeta en bild från en annan domän men vill undvika säkerhetsrisken med att ta emot en SWF-fil när endast en bildfil förväntades. Eftersom SWF-filer kan innehålla ActionScript-kod är det mycket mer riskfyllt att importera en SWF-fil än en bildfil.

I AIR-innehåll i sandlådan application är standardvärdet false. Standardvärdet är true för allt innehåll utom program (dvs. allt innehåll i Flash Player).

Egenskapen allowCodeImport lades till i Flash Player 10.1 och AIR 2.0. Egenskapen blir dock tillgänglig för SWF-filer och AIR-program oavsett version när Flash körtidsmodulen har stöd för den.

Relaterade API-element

Äldre egenskap som ersatts av allowCodeImport men som fortfarande stöds för kompatibilitet. Tidigare var metoden Loader.loadBytes() den enda åtgärden som påverkades av allowLoadBytesCodeExecution, men från och med Flash Player 10.1 och AIR 2.0 påverkas även importinläsningsåtgärden för Loader.load() med LoaderContext.securityDomain = SecurityDomain.currentDomain. (Den senare åtgärden stöds inte i programsandlådan i AIR.) Denna dubbla effekten gjorde egenskapsnamnet allowLoadBytesCodeExecution för specifikt, därför föredras egenskapsnamnet allowCodeImport numera. Värdet för båda påverkas om antingen allowCodeImport eller allowLoadBytesCodeExecution ställs in.

Anger om du kan använda ett Loader-objekt för att importera innehåll med körbar kod, t.ex. en SWF-fil, till anroparens säkerhetssandlåda. Importåtgärderna begränsas till säkra åtgärder, t.ex. inläsning av bilder, om egenskapen är false.

I AIR-innehåll i sandlådan application är standardvärdet false. I icke-programrelaterat innehåll är standardvärdet true.

Relaterade API-element

Anger vilken programdomän som ska användas för metoden Loader.load() eller Loader.loadBytes(). Använd bara den här egenskapen när du läser in en SWF-fil som är skriven i ActionScript 3.0 (inte en bild eller en SWF-fil som är skriven i ActionScript 1.0 eller ActionScript 2.0).

Alla säkerhetsdomäner är indelade i en eller fler programdomäner som motsvaras av ApplicationDomain-objekt. Programdomäner har ingen säkerhetsfunktion, utan används för att hantera samverkande enheter av ActionScript-kod. Om du läser in en SWF-fil från en annan domän och tillåter att den placeras i en separat säkerhetsdomän, kan du inte välja i vilken programdomän den inlästa SWF-filen ska placeras. Eventuella val av programdomäner kommer att ignoreras. Men om du läser in en SWF-fil i din egen säkerhetsdomän, antingen på grund av att SWF-filen kommer från din egen domän eller för att du importerar den till din säkerhetsdomän, kan du styra val av programdomän för den inlästa SWF-filen.

Du kan bara skicka en programdomän från din egen säkerhetsdomän i LoaderContext.applicationDomain. Om du försöker skicka en programdomän från en annan säkerhetsdomän utlöses ett SecurityError-undantag.

Du kan välja mellan fyra typer av ApplicationDomain-egenskaper:

• Child of loader's ApplicationDomain. Standardtypen. Du kan framställa det här valet explicit med syntaxen new ApplicationDomain(ApplicationDomain.currentDomain). Detta gör att den inlästa SWF-filen kan använda det överordnade objektets klasser direkt, till exempel genom att skriva new MyClassDefinedInParent(). Det överordnade objektet kan dock inte använda syntaxen. Om det överordnade vill använda de underordnade klasserna måste den anropa ApplicationDomain.getDefinition() för att hämta dem. Fördelen med det valet är att inget felmeddelande utlöses om det underordnade objektet definierar en klass med samma namn som en klass som redan definierats av det överordnade objektet. Det underordnade ärver då det överordnades definition av den klassen och det underordnades definition som är i konflikt används inte, såvida inte antingen det underordnade eller det överordnade anropar metoden ApplicationDomain.getDefinition() för att hämta den.
• Loader's own ApplicationDomain. Den här programdomänen använder du med ApplicationDomain.currentDomain. När inläsningen är klar kan de överordnade och underordnade objekten använda varandras klasser direkt. Om det underordnade objektet försöker definiera en klass med samma namn som en klass som redan definierats av det överordnade objektet används den överordnade klassen och den underordnade ignoreras.
• Child of the system ApplicationDomain. Det här programmet använder du med new ApplicationDomain(null). På detta sätt åtskiljs inläsare och inläsningsobjekt helt och hållet, och kan definiera separata versioner av klasser med samma namn utan att hamna i konflikt eller överskugga varandra. Det enda sättet de olika sidorna kan se den andras klasser är genom att anropa metoden ApplicationDomain.getDefinition().
• Child of some other ApplicationDomain. I vissa fall kan du ha en mer komplicerad ApplicationDomain-hierarki. Du kan läsa in en SWF-fil till vilket ApplicationDomain-objekt som helst från ditt eget SecurityDomain-objekt. Som exempel kan new ApplicationDomain(ApplicationDomain.currentDomain.parentDomain.parentDomain) läsa in en SWF-fil till ett underordnat objekt av den aktuella domänens överordnades överordnade objekt.

När inläsningen är klar kan vilken som helst av sidorna (den som läser in eller den som blir inläst), behöva hitta sin egen programdomän, eller den andres programdomän, för att kunna anropa ApplicationDomain.getDefinition(). Vilken som helst av sidorna kan hämta en referens till den egna programdomänen med hjälp av ApplicationDomain.currentDomain. Den SWF-fil som läser in kan hämta en referens till ApplicationDomain-objektet för den SWF-fil som läses in via Loader.contentLoaderInfo.applicationDomain. Om den inlästa SWF-filen vet hur den lästes in, kan den hitta ApplicationDomain-objektet för den inläsande SWF-filen. Om det underordnade objektet lästes in på standardsättet, kan den hitta den inläsande SWF-filens programdomän med hjälp av ApplicationDomain.currentDomain.parentDomain.

Mer information finns i avsnittet om ApplicationDomain-klassen i kapitlet ”Klientsystemmiljö” i Utvecklarhandbok för Adobe ActionScript 3.0.

Relaterade API-element

Anger om programmet ska försöka hämta en URL-principfil från det inlästa objektets server innan objektet börjar läsas in. Flaggan kan användas för metoden Loader.load() men inte metoden Loader.loadBytes().

Ställ in flaggan på true när du läser in en bild (JPG, GIF eller PNG) från en annan domän än den anropande SWF-filens egen domän och du förväntar dig att komma åt bildens innehåll från ActionScript. Ett sätt att få åtkomst till bildens innehåll är via referens till egenskapen Loader.content för att få ett Bitmap-objekt, och via anrop till metoden BitmapData.draw() för att få en kopia av den inlästa bildens pixlar. Om du försöker utföra någon av dessa åtgärder utan att ha angett checkPolicyFile vid inläsningen kan du få ett SecurityError-undantag på grund av att den principfil som behövs inte har laddats ned ännu.

Om du anropar metoden Loader.load() med LoaderContext.checkPolicyFile inställt på true börjar inte programmet hämta det angivna objektet i URLRequest.url förrän det antingen har hämtat en relevant URL-principfil eller identifierat att någon sådan principfil inte finns. Flash Player eller AIR börjar med principfiler som redan har hämtats och försöker sedan hämta eventuella väntande principfiler som anges i anrop till metoden Security.loadPolicyFile(). Sedan försöker Flash Player hämta en principfil från den standardplats som motsvarar URLRequest.url, vilket är detsamma som /crossdomain.xml på samma server som URLRequest.url. I samtliga fall måste den aktuella principfilen finnas på URLRequest.url genom sin plats och den måste bevilja åtkomst med hjälp av en eller flera <allow-access-from>-taggar.

Om du anger checkPolicyFile till true läses den huvudsakliga nedladdning som har angetts i metoden Loader.load() inte in förrän bearbetningen av principfilen har slutförts. Förutsatt att principfilen du behöver finns, och så snart du har fått eventuella ProgressEvent.PROGRESS- eller Event.COMPLETE-händelser från contentLoaderInfo-egenskapen för Loader-objektet är därför principfilsnedladdningen klar och du kan börja utföra åtgärder som behöver principfilen.

Om du ställer in checkPolicyFile på true och ingen relevant principfil hittas får du inget felmeddelande förrän du försöker utföra en åtgärd som orsakar ett SecurityError-undantag. När LoaderInfo-objektet väl har skickat en ProgressEvent.PROGRESS- eller Event.COMPLETE-händelse, kan du testa om en relevant principfil hittats genom att undersöka värdet för LoaderInfo.childAllowsParent-egenskapen.

Om du inte behöver åtkomst på pixelnivå till bilden du läser in, bör du inte ställa in egenskapen checkPolicyFile på true. Att söka efter en principfil är onödigt i det här fallet. Det fördröjer nedladdningen och använder bandbredd i onödan.

Undvik också att ställa in checkPolicyFile på true om du använder metoden Loader.load() för att ladda ned en SWF-fil. Detta beror på att SWF-till-SWF-behörighet inte styrs av principfiler utan av metoden Security.allowDomain(), och därför har checkPolicyFile ingen effekt när du läser in en SWF-fil. Att söka efter en principfil är onödigt i det här fallet. Det fördröjer nedladdningen av SWF-filen och använder bandbredd i onödan. (Flash Player eller AIR kan inte avgöra om den huvudsakliga hämtningen är en SWF-fil eller en bild eftersom principfilsnedladdningen görs före den huvudsakliga hämtningen.)

Var försiktig med checkPolicyFile om du hämtar ett objekt från en URL-adress där HTTP-omdirigeringar på serversidan kanske används. Principfiler hämtas alltid från den inledande URL som du anger i URLRequest.url. Om det slutliga objektet kommer från en annan URL-adress på grund av HTTP-omdirigeringar kanske de ursprungligen laddade ned principfilerna inte gäller för objektets slutliga URL-adress, det vill säga den URL-adress som gäller ur säkerhetssynpunkt. Om du befinner dig i den här situationen kan du undersöka värdet för LoaderInfo.url när du har fått en ProgressEvent.PROGRESS- eller Event.COMPLETE-händelse, som innehåller objektets slutliga URL-adress. Anropa metoden Security.loadPolicyFile() med en principfils URL-adress som är baserad på objektets slutliga URL-adress. Fråga sedan efter värdet på LoaderInfo.childAllowsParent tills det blir true.

Du behöver inte ställa in den här egenskapen för AIR-innehåll som körs i programsandlådan. Innehåll i AIR-programsandlådan kan anropa metoden BitmapData.draw() genom att använda valfritt inläst bildinnehåll som källa.

Relaterade API-element

Anger om bitmappbilddata ska avkodas när de används eller när de läses in.

Enligt standardregeln ImageDecodingPolicy.ON_DEMAND, kommer bilddata att avkodas när dessa data behövs (för visning eller andra syften). Regeln underhåller det avkodningsbeteende som användes i tidigare körningsversioner.

Under regeln ImageDecodingPolicy.ON_LOAD kommer bilden att avkodas under körning omedelbart efter det att den lästs in och innan complete-händelsen skickats. Bildavkodning vid inläsningen i stället för vid behov kan förbättra prestandan för animering och användargränssnitt. Du märker förbättringar när flera inlästa bilder visas snabbt efter varandra. Exempel på snabba bildvisningar är rullningslister och kontrollflöden. Å andra sidan kan användning av onLoad-regeln godtyckligt öka programmets minnesanvändning. Med onDemand-regeln kan fler avkodade bilder finnas i minnet samtidigt.

För båda reglerna gäller att under körningen används samma cache- och rensningsbeteende som efter det att bilden avkodats. Under körningen kan avkodade data resas när som helst och bilden kan omkodas igen nästa gång detta krävs.

Så här ställer du in avkodningsregeln (till exempel för 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);
     

Relaterade API-element

Ett objekt som innehåller de parametrar som behövs för att skicka LoaderInfo-objektet till innehållet.

I normalfallet erhålls värdet för egenskapen contentLoaderInfo.parameters genom tolkning av den begärande URL:en. Om var-parametrarna är inställda, hämtas värdet för contentLoaderInfo.parameters från LoaderContext-objektet och inte från den begärande URL:en. Var-parametrarna accepterar endast objekt som innehåller namnvärdessträngpar, ungefär som URL-parametrar. Om objektet inte innehåller namnvärdessträngpar genereras ett IllegalOperationError.

Avsikten med denna API är att låta den inläsande SWF-filen skicka dess parametrar till en inläst SWF-fil. Den här funktionen är speciellt användbar när du använder metoden loadBytes() eftersom LoadBytes saknar möjlighet att skicka parametrar med URL:en. Det går att skicka parametrar bara till en annan AS3 SWF-fil. En AS1- eller AS2 SWF-fil kan inte ta emot parametrar i en godtagbar form även om AS3 loaderInfo.parameters-objektet för AVM1Movie kommer att vara det skickade objektet.

Titta på följande URL-exempel:

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

I följande kod används LoaderContext.parameters-egenskapen för att reproducera en parameter som skickas till denna 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);
     

Du verifierar att parametern skickas korrekt genom att använda följande trace-programsats sedan du kört koden.

trace(loaderInfo.parameters.foo);

Om innehållet läses in kommer denna trace-sats att skriva ut "bar".

Det överordnade objekt till vilket Loader försöker att lägga till det inlästa innehållet.

När allt innehåll har lästs in, blir Loader-objektet i normalfallet överordnat innehållet. Om requestedContentParent är inställt, kommer det objekt som det anger att bli överordnat, såvida ett körningsfel inte förhindrar tilldelningen. Denna överordning kan också göras efter händelsen complete utan att den här egenskapen behöver användas. Om emellertid den överordnade anges med LoaderContext.requestedContentParent elimineras extra händelser.

LoaderContext.requestedContentParent anger den önskade överordnade innan första bildruteskriptet i det inlästa innehåller körs, men efter det att konstruktorn har körts. Om requestedContentParent är null (standard), blir Loader-objektet överordnat innehållet.

Om det inlästa innehållet är ett AVM1Movie-objekt eller om ett fel inträffar när addChild() anropas i requestedContentParent-objektet, kommer följande åtgärder att inträffa:

• Loader-objektet överordnas det inlästa innehållet.
• Vid körning skickas en AsyncErrorEvent.

Om den begärda överordnade och det inlästa innehållet finns i olika säkerhetsmiljöer och om den begärda överordnade inte har åtkomst till det inlästa innehållet, kommer följande åtgärder att inträffa:

• Loader-objektet överordnas det inlästa innehållet.
• Vid körning skickas en SecurityErrorEvent.

I följande kod används requestedContentParent för att placera det inlästa innehållet i ett Sprite-objekt:

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

När koden körs visas den underordnade SWF-filen på scenen. Detta bekräftar att Sprite-objektet som du lade till på scenen är överordnad den inlästa child.swf-filen.

Anger vilken säkerhetsdomän som ska användas för en Loader.load()-åtgärd. Använd bara den här egenskapen när du läser in en SWF-fil (inte en bild).

Valet av säkerhetsdomäner är bara viktigt om du läser in en SWF-fil som kanske kommer från en annan domän (en annan server) än den SWF-fil som läser in. Om du läser in en SWF-fil från din egen domän placeras den alltid i din säkerhetsdomän. Men när du läser in en SWF-fil från en annan domän har du två alternativ. Du kan tillåta att den inlästa SWF-filen ska placeras på den naturliga säkerhetsdomänen, vilken inte är densamma som den inläsande SWF-filens. Detta är standardalternativet. Du kan också ange att den inlästa SWF-filen ska placeras i samma säkerhetsdomän som den inläsande filen, genom att ställa in att myLoaderContext.securityDomain är lika med SecurityDomain.currentDomain. Detta kallas import av inläsning och är säkerhetsmässigt likvärdigt med att kopiera den inlästa SWF-filen till din egen server och läsa in den därifrån. För att importen av inläsningen ska fungera måste den inlästa SWF-filens server ha en principfil som betror den inläsande filens domän.

Du kan bara skicka din egen säkerhetsdomän i LoaderContext.securityDomain. Om du försöker skicka någon annan säkerhetsdomän utlöses ett SecurityError-undantag.

Innehåll i säkerhetssandlådan för AIR-programmet kan inte läsa in innehåll från andra sandlådor till SecurityDomain.

Ytterligare information finns i kapitlet ”Säkerhet” i Utvecklarhandbok för Adobe ActionScript 3.0.

Relaterade API-element

Skapar ett nytt LoaderContext-objekt med de angivna inställningarna. Mer information om de här inställningarna finns i beskrivningen av klassens egenskaper.

Relaterade API-element