LoaderContext  - AS3

Indique si vous pouvez utiliser un objet Loader en vue d’importer du contenu avec du code exécutable, tel qu’un fichier SWF, dans le sandbox de sécurité de l’appelant. Il existe deux opérations d’importation : la méthode Loader.loadBytes() et la méthode Loader.load() avec LoaderContext.securityDomain = SecurityDomain.currentDomain. (La dernière opération n’est pas prise en charge dans le sandbox de l’application AIR.) Lorsque la propriété allowCodeImport est définie sur false, ces opérations d’importation sont limitées à des opérations sécurisées, telles que le chargement d’images. Le chargement normal de fichiers SWF non importés avec la méthode Loader.load() n’est pas affecté par la valeur de cette propriété.

Cette propriété est utile lorsque vous souhaitez importer le contenu de l’image dans le sandbox, notamment lorsque vous souhaitez répliquer ou traiter une image à partir d’un autre domaine, mais ne souhaitez pas prendre le risque de recevoir un fichier SWF alors que vous n’attendiez qu’un fichier d’image. Etant donné que les fichiers SWF peuvent contenir du code ActionScript, l’importation d’un fichier SWF est une opération beaucoup plus risquée que l’importation d’un fichier image.

Dans le contenu AIR dans le sandbox de l’application, la valeur par défaut est false. Dans le contenu hors application (qui inclut la totalité du contenu dans Flash Player), la valeur par défaut est true.

La propriété allowCodeImport a été ajoutée à Flash Player 10.1 et AIR 2.0. Toutefois, cette propriété est disponible pour les fichiers SWF et les applications AIR de toutes les versions lorsque le moteur d’exécution de Flash la prend en charge.

Eléments de l’API associés

Propriété héritée, remplacée par allowCodeImport, mais toujours prise en charge pour des raisons de compatibilité. Auparavant, la seule opération affectée par allowLoadBytesCodeExecution était la méthode Loader.loadBytes() ; à partir de Flash Player 10.1 et AIR 2.0, l’opération d’importation/chargement de Loader.load() avec LoaderContext.securityDomain = SecurityDomain.currentDomain est également affectée. (La dernière opération n’est pas prise en charge dans le sandbox de l’application AIR.) A cause de ce double effet, le nom de la propriété allowLoadBytesCodeExecution était trop spécifique. Par conséquent, on lui préfère à présent le nom allowCodeImport. Que vous définissiez allowCodeImport ou allowLoadBytesCodeExecution, les deux valeurs en sont affectées.

Indique si vous pouvez utiliser un objet Loader en vue d’importer du contenu avec du code exécutable, tel qu’un fichier SWF, dans le sandbox de sécurité de l’appelant. Si cette propriété est définie sur false, ces opérations d’importation sont limitées à des opérations sécurisées, telles que le chargement d’images.

Dans le contenu AIR dans le sandbox de l’application, la valeur par défaut est false. Dans le contenu hors application, la valeur par défaut est true.

Eléments de l’API associés

Spécifie le domaine d’application à utiliser pour la méthode Loader.load() ou Loader.loadBytes(). Utilisez cette propriété uniquement lors du chargement d’un fichier SWF écrit dans ActionScript 3.0 (et non pas une image ou un fichier SWF écrit au format ActionScript 1.0 ou ActionScript 2.0).

Tout domaine de sécurité est divisé en un ou plusieurs domaines d’application, représentés par les objets ApplicationDomain. Les domaines d’application n’ont pas de rôle de sécurité ; ils servent à gérer les unités de code ActionScript qui doivent coopérer. Si vous chargez un fichier SWF provenant d’un autre domaine, puis autorisez son placement dans un domaine de sécurité distinct, vous ne pouvez pas contrôler le domaine d’application dans lequel le ficher SWF est placé. Si vous avez spécifié un domaine d’application, ce choix sera ignoré. Cependant, si vous chargez un fichier SWF dans votre propre domaine de sécurité, soit parce que le fichier SWF provient de votre domaine, soit parce que vous l’importez dans votre domaine de sécurité, puis vous pouvez contrôler le domaine d’application du fichier SWF chargé.

Vous devez transmettre le domaine d’application à partir de votre propre domaine de sécurité dans LoaderContext.applicationDomain. Toute tentative de transmission d’un domaine d’application à partir de tout autre domaine de sécurité renvoie une exception SecurityError.

Vous disposez de quatre choix concernant le type de propriété ApplicationDomain à utiliser :

• Enfant du domaine d’application du chargeur. La valeur par défaut. Vous pouvez représenter de façon explicite ce choix avec la syntaxe new ApplicationDomain(ApplicationDomain.currentDomain). Ceci permet au fichier SWF d’utiliser les classes parent de façon directe, par exemple en écrivant new MyClassDefinedInParent(). Le parent, cependant, ne permet pas d’utiliser cette syntaxe. Si le parent souhaite utiliser les classes de l’enfant, il doit appeler ApplicationDomain.getDefinition() pour les extraire. L’avantage de ce choix est que, si l’enfant définit une classe du même nom que la classe qui est déjà définie par le parent, aucune erreur ne se produit ; l’enfant hérite simplement de la définition de cette classe à partir de son parent et toute définition de l’enfant qui entraîne un conflit reste inutilisée, sauf si l’enfant ou le parent appelle la méthode ApplicationDomain.getDefinition() pour l’extraire.
• Domaine d’application de la classe loader. Employez ce domaine d’application lorsque vous utilisez ApplicationDomain.currentDomain. Une fois le chargement terminé, le parent et l’enfant peuvent exploiter leurs classes respectives de façon directe. Si l’enfant tente de définir une classe avec le même nom que celle déjà définie par le parent, la classe du parent est utilisée et celle de l’enfant est ignorée.
• Enfant du domaine d’application du système. Utilisez ce domaine d’application lors de l’utilisation de new ApplicationDomain(null). Cette opération permet de distinguer les objets de chargement des objets chargés, afin de définir des versions distinctes des classes du même nom, sans conflit ou problèmes de priorité. Seule la méthode ApplicationDomain.getDefinition() permet aux deux parties de voir les classes de l’autre.
• Enfant d’un autre domaine d’application. De façon occasionnelle, vous pouvez avoir à faire à une hiérarchie de domaines d’application plus complexe. Vous pouvez charger un fichier SWF dans un domaine d’application à partir de votre propre domaine de sécurité. Par exemple, new ApplicationDomain(ApplicationDomain.currentDomain.parentDomain.parentDomain) charge un fichier SWF dans un nouvel enfant du grand-parent du domaine actuel.

Une fois le chargement terminé, les deux parties (en cours de chargement ou chargées) peuvent avoir à rechercher leur propre domaine d’application, ou le domaine d’application de l’autre partie, afin d’appeler ApplicationDomain.getDefinition(). Chaque partie peut extraire une référence vers son propre domaine d’application à l’aide de ApplicationDomain.currentDomain. Le fichier SWF de chargement peut extraire une référence au domaine d’application du fichier SWF à l’aide de Loader.contentLoaderInfo.applicationDomain. Si le fichier SWF a identifié son mode de chargement, il peut retrouver l’objet ApplicationDomain du fichier SWF en cours de chargement. Par exemple, si l’enfant a été chargé à l’aide de la méthode par défaut, il peut déterminer le domaine d’application du fichier SWF à l’aide de ApplicationDomain.currentDomain.parentDomain.

Pour plus d’informations, voir la section « Classe ApplicationDomain » du chapitre « Environnement du système client » du Guide du développeur d’ActionScript 3.0.

Eléments de l’API associés

Spécifie si l’application doit tenter de télécharger un fichier de régulation d’URL à partir du serveur de l’objet chargé avant de commencer à charger ce dernier. Cet indicateur s’applique à la méthode Loader.load(), mais pas à la méthode Loader.loadBytes().

Définissez cet indicateur sur true lorsque vous chargez une image (JPEG, GIF ou PNG) en dehors du domaine du fichier SWF qui procède à l’appel et lorsque vous pensez avoir besoin d’accéder au contenu de cette image à partir d’ActionScript. Parmi les exemples d’accès au contenu de l’image, citons le référencement de la propriété Loader.content pour obtenir un objet Bitmap et l’appel à la méthode BitmapData.draw() pour obtenir une copie des pixels de l’image chargée. Si vous tentez l’une de ces opérations sans avoir spécifié checkPolicyFile lors du chargement, vous risquez de subir une exception SecurityError dans la mesure où le fichier de régulation requis n’a pas encore été téléchargé.

Lorsque vous appelez la méthode Loader.load() avec LoaderContext.checkPolicyFile défini sur true, l’application ne commence pas le téléchargement de l’objet spécifié dans URLRequest.url avant d’avoir téléchargé avec succès un fichier de régulation d’URL adéquat ou déterminé que ce fichier de régulation n’existe pas. Flash Player ou AIR analyse en premier lieu les fichiers de régulation ayant déjà été téléchargés, tente de télécharger tous les fichiers de stratégie en attente spécifiés lors des appels à la méthode Security.loadPolicyFile(), puis tente de télécharger un fichier de stratégie à l’emplacement par défaut, qui correspond à URLRequest.url, soit /crossdomain.xml sur le même serveur que URLRequest.url. Dans tous les cas, le fichier de régulation donné doit exister à URLRequest.url, sur la base de l’emplacement du fichier de régulation, et le fichier doit autoriser l’accès par le biais d’une ou plusieurs balises <allow-access-from>.

Si vous définissez checkPolicyFile sur true, le téléchargement principal spécifié dans la méthode Loader.load() ne charge pas tant que le traitement du fichier de régulation n’est pas complètement terminé. Par conséquent, tant que le fichier de régulation requis existe, dès la réception des événements ProgressEvent.PROGRESS ou Event.COMPLETE à partir de la propriété contentLoaderInfo de votre objet Loader, le téléchargement du fichier de régulation se termine et vous pouvez procéder de façon sûre aux opérations qui nécessitent ce fichier de régulation.

Si vous définissez checkPolicyFile sur true et si aucun fichier de régulation n’est trouvé, vous ne recevrez aucune indication d’erreur jusqu’à ce que vous tentiez une opération qui renvoie une exception SecurityError. Cependant, lorsque l’objet LoaderInfo distribue un événement ProgressEvent.PROGRESS ou Event.COMPLETE, vous pouvez déterminer si un fichier de régulation a été détecté en vérifiant la valeur de la propriété LoaderInfo.childAllowsParent.

Si l’accès au niveau des pixels de l’image en cours de chargement est requis, vous ne pouvez pas définir la propriété checkPolicyFile sur true. La vérification d’un fichier de stratégie dans ce cas est contre-productive, dans la mesure où elle risque de retarder le début de votre téléchargement et risque de consommer la bande passante du réseau de façon inutile.

Evitez également de définir checkPolicyFile sur true si vous utilisez la méthode Loader.load() pour télécharger un fichier SWF. Ceci est dû au fait que les autorisations SWF vers SWF ne sont pas contrôlées par les fichiers de stratégies, mais par la méthode Security.allowDomain(), ce qui a pour conséquence que checkPolicyFile n’a pas d’effet lorsque vous chargez le fichier SWF. La vérification d’un fichier de stratégie dans ce cas est contre-productive, dans la mesure où elle risque de retarder le téléchargement du fichier SWF et risque de consommer la bande passante du réseau de façon inutile (Flash Player ou AIR ne peut pas déterminer si votre téléchargement principal sera un fichier SWF ou une image, dans la mesure où le téléchargement du fichier de régulation a lieu avant le téléchargement principal).

Si vous téléchargez un objet à partir d’une URL qui peut utiliser des redirections HTTP côté serveur, servez-vous de checkPolicyFile avec précaution. Les fichiers de régulation sont toujours récupérés de l’URL initiale correspondante que vous spécifiez dans URLRequest.url. Si l’objet final provient d’une URL différente en conséquence de redirections HTTP, les fichiers de régulation initialement téléchargés peuvent ne pas être applicables à l’URL finale de l’objet, autrement dit l’URL à prendre en compte dans les décisions relatives à la sécurité. Si vous vous trouvez dans cette situation, le code examine la valeur LoaderInfo.url après avoir reçu un événement ProgressEvent.PROGRESS ou Event.COMPLETE, ce qui permet d’obtenir l’URL finale de l’objet. La méthode Security.loadPolicyFile() est ensuite appelée avec une URL de fichier de régulation basée sur l’URL finale de l’objet. La valeur de LoaderInfo.childAllowsParent est ensuite vérifiée régulièrement jusqu’à ce qu’elle ait la valeur true.

Il n’est pas nécessaire que vous définissiez cette propriété pour le contenu AIR s’exécutant dans le sandbox de l’application. Le contenu dans le sandbox de l’application AIR peut appeler la méthode BitmapData.draw() à l’aide de l’une des images chargées comme source.

Plus d’exemples

Informations complémentaires

Eléments de l’API associés

Indique s’il convient de décoder les données de l’image bitmap lors de leur utilisation ou de leur chargement.

Sous la stratégie par défaut, ImageDecodingPolicy.ON_DEMAND, le moteur d’exécution décode les données image lorsque les données sont nécessaires (à des fins d’affichage ou à d’autres fins). Cette stratégie conserve le comportement de décodage utilisé par les versions précédentes du moteur d’exécution.

Sous la stratégie ImageDecodingPolicy.ON_LOAD, le moteur d’exécution décode l’image immédiatement après son chargement et avant la distribution de l’événement complete. Le décodage d’images au chargement plutôt qu’à la demande peut améliorer l’animation et les performances de l’interface utilisateur. Vous pouvez constater ces améliorations lorsque plusieurs images chargées s’affichent en succession rapide. Le défilement de listes ou la commande Cover Flow sont des exemples d’affichage rapide d’images. D’autre part, l’utilisation sans discernement de la stratégie onLoad peut augmenter l’utilisation maximale de la mémoire de votre application. La mémoire peut contenir davantage de données image décodées que sous la stratégie onDemand.

Quelle que soit la stratégie choisie, le moteur d’exécution utilise la même mémoire cache et le même comportement de purge une fois l’image décodée. Le moteur d’exécution peut à tout moment vider les données décodées et décoder à nouveau l’image dès que cela est nécessaire.

Pour définir la stratégie de décodage de l’image (par exemple sur 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);
     

Eléments de l’API associés

Objet contenant les paramètres à transmettre à l’objet LoaderInfo du contenu.

Normalement, la valeur de la propriété contentLoaderInfo.parameters est obtenue en analysant l’URL de demande. Si la variable parameters est définie, la propriété contentLoaderInfo.parameters obtient sa valeur à partir de l’objet LoaderContext, et non à partir de l’URL de demande. La variable parameters prend en charge uniquement les objets contenant des paires de chaînes nom/valeur similaires aux paramètres de l’URL. Si l’objet ne contient pas de paires de chaînes nom/valeur, une erreur IllegalOperationError est renvoyée.

Le but de cette API est d’activer le fichier SWF de chargement pour transférer ses paramètres à un fichier SWF chargé. Cette fonctionnalité est particulièrement utile lorsque vous utilisez la méthode loadBytes(), car LoadBytes ne permet pas la transmission de paramètres via l’URL. Il est uniquement possible de transmettre correctement les paramètres à un autre fichier SWF AS3 ; un fichier SWF AS1 ou AS2 ne peut pas recevoir les paramètres dans une forme accessible, bien que l’objet loaderInfo.parameters AS3 d’AVM1Movie soit l’objet transféré.

Considérons par exemple l’URL qui suit :

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

Le code suivant utilise la propriété LoaderContext.parameters pour reproduire un paramètre transmis à cette 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);
     

Pour vérifier que le paramètre a été correctement transmis, utilisez l’instruction trace suivante après avoir exécuté ce code :

trace(loaderInfo.parameters.foo);

Si le contenu est chargé correctement, cette trace imprime "bar".

Parent auquel l’objet Loader va tenter d’ajouter le contenu chargé.

Lorsque le contenu est entièrement chargé, l’objet Loader devient normalement le parent du contenu. Si la propriété requestedContentParent est définie, l’objet qu’elle spécifie devient le parent, à moins qu’une erreur d’exécution empêche l’affectation. Il est également possible d’effectuer ce changement de parent après l’événement complete sans utiliser cette propriété. Indiquer le parent avec LoaderContext.requestedContentParent permet toutefois d’éliminer les événements supplémentaires.

LoaderContext.requestedContentParent définit le parent désiré avant l’exécution des scripts de la première image dans le contenu chargé et après l’exécution du constructeur. Si la propriété requestedContentParent est définie sur null (valeur par défaut), l’objet Loader devient le parent du contenu.

Si le contenu chargé est un objet AVM1Movie, ou si une erreur est renvoyée lorsque addChild() est appelée sur l’objet requestedContentParent, les actions suivantes se produisent :

• L’objet Loader devient le parent du contenu chargé.
• Le moteur d’exécution distribue un événement AsyncErrorEvent.

Si le parent demandé et le contenu chargé se trouvent dans des sandbox de sécurité différents, et si le parent demandé n’a pas accès au contenu chargé, les actions suivantes se produisent :

• L’objet Loader devient le parent du contenu chargé.
• Le moteur d’exécution distribue un événement SecurityErrorEvent.

Le code suivant utilise requestedContentParent pour placer le contenu chargé dans un objet Sprite :

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

Lors de l’exécution de ce code, le fichier SWF enfant s’affiche sur la scène. Ce fait confirme que l’objet Sprite que vous venez d’ajouter à la scène est le parent du fichier child.swf chargé.

Spécifie le domaine de sécurité à utiliser pour une opération Loader.load(). Utilisez cette propriété uniquement lors du chargement d’un fichier SWF (et non pas une image).

Le choix du domaine de sécurité n’a de sens que si vous chargez un fichier SWF pouvant provenir d’un autre domaine (un autre serveur) que le fichier SWF de chargement. Lorsque vous chargez un fichier SWF provenant de votre propre domaine, ce dernier est placé dans votre domaine de sécurité. Cependant, lorsque vous chargez un fichier SWF à partir d’un domaine différent, vous disposez de deux options. Vous pouvez autoriser le placement du fichier SWF chargé dans le domaine de sécurité « naturel », qui est différent de celui du fichier SWF de chargement. Il s’agit de la valeur par défaut. L’autre consiste à spécifier que vous souhaitez placer le fichier SWF chargé dans le même domaine de sécurité que le fichier SWF de chargement, en définissant myLoaderContext.securityDomain comme égal à SecurityDomain.currentDomain. Cette opération est appelée chargement en vue de l’importation et est équivalente, pour des raisons de sécurité, à la copie du fichier SWF chargé sur votre propre serveur et à son chargement à partir de cet endroit. Pour que le chargement en vue de l’importation réussisse, le serveur du fichier SWF doit disposer d’un fichier de régulation pour lequel le domaine de chargement du fichier SWF fait partie des domaines de confiance.

Vous pouvez transmettre votre propre domaine de sécurité uniquement dans LoaderContext.securityDomain. Toute tentative de transmission vers un autre domaine de sécurité renvoie une exception SecurityError.

Le contenu du sandbox de sécurité de l’application AIR ne peut pas charger le contenu d’autres sandbox dans son domaine de sécurité.

Pour plus d’informations, voir le chapitre « Sécurité » du Guide du développeur d’ActionScript 3.0.

Plus d’exemples

Informations complémentaires

Eléments de l’API associés

Crée un objet LoaderContext avec les paramètres spécifiés. Pour compléter les détails de ces paramètres, voir les descriptions des propriétés de cette classe.

Eléments de l’API associés