Chargement de données externesFlash Player 9 et ultérieur, Adobe AIR 1.0 et ultérieur ActionScript 3.0 comprend des mécanismes permettant de charger des données depuis des sources externes. Ces sources peuvent fournir un contenu statique, tel que des fichiers texte, ou un contenu dynamique généré par un script Web. Les données peuvent être formatées de plusieurs façons, et ActionScript propose une fonctionnalité permettant de décoder les données et d’y accéder. Vous pouvez également envoyer des données au serveur externe lors de leur récupération. Utilisation de la classe URLRequestUn grand nombre d’API qui chargent des données externes font appel à la classe URLRequest pour définir les propriétés de la requête réseau requise. Propriétés de la classe URLRequestVous pouvez définir les propriétés suivantes d’un objet URLRequest dans tout sandbox de sécurité :
AIR permet de définir d’autres propriétés de la classe URLRequest, dont ne dispose que le contenu AIR qui s’exécute dans le sandbox de sécurité d’application. Le contenu du sandbox d’application peut également définir des URL à l’aide des nouveaux modèles d’URL (parallèlement aux modèles standard tels que file et http).
Remarque : la classe HTMLLoader possède des propriétés associées pour les paramètres associés au contenu chargé par un objet HTMLLoader. Pour plus d’informations, voir A propos de la classe HTMLLoader.
Définition des paramètres par défaut des objets URLRequest (AIR uniquement)La classe URLRequestDefaults permet de définir les paramètres par défaut propres à une application des objets URLRequest. Par exemple, le code suivant définit les valeurs par défaut des propriétés manageCookies et useCache. Tous les nouveaux objets URLRequest utiliseront les valeurs spécifiées de ces propriétés au lieu des valeurs par défaut standard : URLRequestDefaults.manageCookies = false; URLRequestDefaults.useCache = false; Remarque : la classe URLRequestDefaults est réservée au contenu qui s’exécute dans Adobe AIR. Elle n’est pas prise en charge dans Flash Player.
La classe URLRequestDefaults inclut une méthode setLoginCredentialsForHost() qui vous permet de spécifier un nom d’utilisateur et un mot de passe par défaut pour un hôte spécifique. L’hôte, défini dans le paramètre hostname de la méthode, peut être un domaine, tel que "www.example.com", ou un domaine et un numéro de port, par exemple "www.example.com:80". Notez que "example.com", "www.example.com" et "sales.example.com" sont considérés comme hôtes uniques. Ces informations d’identification ne sont utilisées que lorsque le serveur les demande. Si l’utilisateur s’est déjà authentifié (à l’aide de la boîte de dialogue d’authentification, par exemple), appeler la méthode setLoginCredentialsForHost() ne modifie pas l’utilisateur authentifié. Le code suivant permet de définir le nom d’utilisateur et le mot de passe par défaut à utiliser pour les requêtes envoyées à www.example.com : URLRequestDefaults.setLoginCredentialsForHost("www.example.com", "Ada", "love1816$X"); Les paramètres URLRequestDefaults ne s’appliquent qu’au domaine d’application actuel, à une exception près. Les informations d’identification transmises à la méthode setLoginCredentialsForHost() sont utilisées pour les requêtes effectuées dans tout domaine de l’application AIR. Pour plus d’informations, voir la classe URLRequestDefaults dans le manuel Guide de référence ActionScript 3.0 pour la plate-forme Adobe Flash. Modèles d’URILes modèles d’URI standard, tel le modèle ci-dessous, peuvent être utilisés dans les requêtes effectuées à partir de tout sandbox de sécurité : http: et https:A utiliser pour les URL Internet standard (comme elles sont utilisées dans un navigateur Web). file:Utilisez file: pour spécifier l’URL d’un fichier qui réside dans le système de fichiers local. Exemple : file:///c:/AIR Test/test.txt Dans AIR, vous disposez également des modèles suivants lorsque vous définissez l’URL d’un contenu s’exécutant dans le sandbox de sécurité de l’application : app:Le modèle app: permet de spécifier un chemin relatif au répertoire racine de l’application installée. Par exemple, le chemin suivant pointe vers un sous-répertoire de ressources du répertoire de l’application installée : app:/resources Lorsqu’une application AIR est lancée à l’aide de l’application de débogage du lanceur AIR (ADL), le répertoire d’application correspond à celui qui contient le fichier descripteur d’application. app-storage:Le modèle app:storage permet de spécifier un chemin relatif au répertoire de stockage de données de l’application. Pour chaque application installée (et utilisateur), AIR crée un répertoire de stockage d’application unique. Cet emplacement est utile pour stocker des données spécifiques à l’application concernée. Par exemple, le chemin suivant pointe vers un fichier prefs.xml dans un sous-répertoire de paramètres du répertoire de stockage de l’application : app-storage:/settings/prefs.xml L’emplacement du répertoire de stockage de l’application dépend du nom d’utilisateur, de l’ID d’application et de l’ID d’éditeur (le cas échéant) :
Remarque : depuis la version 1.5.3 d’AIR, certaines applications AIR ne possèdent pas d’identifiant d’éditeur.
L’URL (et la propriété url) d’un objet File créé avec File.applicationStorageDirectory utilise le modèle d’URI app-storage, comme suit : var dir:File = File.applicationStorageDirectory; dir = dir.resolvePath("preferences"); trace(dir.url); // app-storage:/preferences mailto :Vous pouvez utiliser le modèle mailto dans les objets URLRequest transmis à la fonction navigateToURL(). Voir Ouverture d’une URL dans une autre application. Vous pouvez faire appel à un objet URLRequest basé sur l’un de ces modèles d’URI pour définir la requête d’URL d’un certain nombre d’objets, tels qu’un objet FileStream ou Sound. Vous pouvez par ailleurs utiliser ces modèles dans le contenu HTML qui s’exécute dans AIR. Il est ainsi possible d’y faire appel dans l’attribut src d’une balise img. Néanmoins, vous ne pouvez utiliser ces modèles d’URI spécifiques à AIR (app: et app-storage:) que dans le contenu du sandbox de sécurité de l’application. Pour plus d’informations, voir Sécurité AIR. Modèles d’URI interdits (dans AIR)Certaines API permettent de lancer le contenu dans un navigateur Web. Pour des raisons de sécurité, certains modèles d’URI sont interdits lors de l’utilisation de ces API dans AIR. La liste des modèles non autorisés dépend du sandbox de sécurité du code utilisant l’API. Pour plus d’informations, voir Ouverture d’une URL dans une autre application. Définition des variables URLBien qu’il soit possible d’ajouter directement des variables à la chaîne de l’URL, il s’avère souvent plus facile de définir toute variable requise par une requête à l’aide de la classe URLVariables. Les méthodes permettant d’ajouter des paramètres à un objet URLVariables sont au nombre de trois :
L’exemple suivant illustre les trois méthodes et indique comment affecter les variables à un objet URLRequest : var urlVar:URLVariables = new URLVariables( "one=1&two=2" ); urlVar.decode("amp=" + encodeURIComponent( "&" ) ); urlVar.three = 3; urlVar.amp2 = "&&"; trace(urlVar.toString()); //amp=%26&2=%26%26&one=1&two=2&three=3 var urlRequest:URLRequest = new URLRequest( "http://www.example.com/test.cfm" ); urlRequest.data = urlVar; Lorsque vous définissez des variables au sein du constructeur URLVariables ou à l’aide de la méthode URLVariables.decode(), veillez à coder au format URL les caractères dont la signification est particulière dans une chaîne d’URI. Ainsi, lorsque vous insérez une esperluette dans un nom de paramètre ou une valeur, vous devez la coder de sorte à remplacer & par %26, car l’esperluette fait office de délimiteur de paramètres. Vous disposez à cet effet de la fonction de niveau supérieur encodeURIComponent(). Utilisation de la classe URLLoaderLa classe URLLoader permet d’envoyer une requête à un serveur et d’accéder aux informations renvoyées. Vous disposez également de la classe URLLoader pour accéder aux fichiers du système de fichiers local dans les contextes où l’accès aux fichiers locaux est autorisé (le sandbox local avec système de fichiers de Flash Player et le sandbox d’application AIR, par exemple). La classe URLLoader télécharge des données à partir d’une URL sous forme de texte, de données binaires ou de variables codées au format URL. La classe URLLoader distribue des événements tels que complete, httpStatus, ioError, open, progress et securityError. Le modèle de gestion des événements d’ActionScript 3.0 est sensiblement différent du modèle d’ActionScript 2.0, qui utilisait les gestionnaires d’événement LoadVars.onData, LoadVars.onHTTPStatus et LoadVars.onLoad. Pour plus d’informations sur la gestion des événements en ActionScript 3.0, voir Gestion des événements. Les données téléchargées ne sont pas disponibles tant que le téléchargement n’est pas terminé. Pour surveiller la progression du téléchargement (nombre d’octets chargés et nombre total d’octets), écoutez la distribution de l’événement progress. Toutefois, si le chargement d’un fichier est rapide, l’événement progress risque de ne pas être distribué. Une fois que le téléchargement d’un fichier est terminé, l’événement complete est distribué. En définissant la propriété dataFormat de la classe URLLoader, vous pouvez recevoir les données sous forme de texte, de données binaires brutes ou d’objet URLVariables. La méthode URLLoader.load() (et éventuellement le constructeur de la classe URLLoader) gère un seul paramètre, request, qui correspond à un objet URLRequest. Un objet URLRequest contient toutes les informations d’une requête HTTP unique, telles que l’URL cible, la méthode de requête (GET ou POST), d’autres informations d’en-tête et le type MIME. Pour charger un paquet XML dans un script côté serveur, par exemple, vous pouvez utiliser le code ci-après : var secondsUTC:Number = new Date().time; var dataXML:XML = <clock> <time>{secondsUTC}</time> </clock>; var request:URLRequest = new URLRequest("http://www.yourdomain.com/time.cfm"); request.contentType = "text/xml"; request.data = dataXML.toXMLString(); request.method = URLRequestMethod.POST; var loader:URLLoader = new URLLoader(); loader.load(request); L’extrait ci-dessus crée un document XML appelé dataXML, qui contient le paquet XML à envoyer au serveur. L’exemple définit la propriété contentType de l’objet URLRequest sur "text/xml" et affecte le document XML à la propriété data de l’objet URLRequest. Il crée enfin un objet URLLoader et envoie la requête au script distant par le biais de la méthode load(). Utilisation de la classe URLStreamLa classe URLStream permet d’accéder aux données en cours de téléchargement au fur et à mesure de leur arrivée. Elle permet également de fermer un flux continu avant la fin du téléchargement. Les données téléchargées sont disponibles au format binaire brut. Lorsque vous lisez les données issues d’un objet URLStream, faites appel à la propriété bytesAvailable pour déterminer si les données disponibles sont suffisantes avant de les lire. Une exception EOFError est renvoyée si vous essayez de lire des données qui ne sont pas disponibles. Evénement httpResponseStatus (AIR)Dans Adobe AIR, la classe URLStream distribue un événement httpResponseStatus en plus de l’événement httpStatus. L’événement httpResponseStatus est envoyé avant toute donnée de réponse. L’événement httpResponseStatus (représenté par la classe HTTPStatusEvent) inclut une propriété responseURL, qui correspond à l’URL que la réponse a renvoyée, et une propriété responseHeaders, qui est un tableau d’objets URLRequestHeader représentant les en-têtes de réponse que la réponse a renvoyés. Chargement de données à partir de documents externesLorsque vous programmez des applications dynamiques, il peut s’avérer utile de charger des données issues de fichiers externes ou de scripts côté serveur. Vous pouvez ainsi programmer des applications dynamiques sans avoir à les modifier ou les recompiler. Par exemple, si vous créez une application « conseil du jour », vous pouvez écrire un script côté serveur qui récupère un conseil au hasard dans une base de données et l’enregistre dans un fichier texte une fois par jour. Votre application peut ensuite charger le contenu du fichier texte statique au lieu d’envoyer une requête à la base de données à chaque fois. L’extrait de code suivant crée un objet URLRequest et URLLoader, qui charge le contenu d’un fichier texte externe nommé params.txt : var request:URLRequest = new URLRequest("params.txt"); var loader:URLLoader = new URLLoader(); loader.load(request); Par défaut, si vous ne définissez aucune méthode de requête, Flash Player et AIR chargent le contenu à l’aide de la méthode HTTP GET. Pour envoyer la requête avec la méthode POST, définissez la propriété request.method sur POST à l’aide de la constante statique URLRequestMethod.POST, comme l’illustre le code suivant :
var request:URLRequest = new URLRequest("sendfeedback.cfm"); request.method = URLRequestMethod.POST; Le document externe, params.txt, chargé au moment de l’exécution, contient les données suivantes : monthNames=January,February,March,April,May,June,July,August,September,October,November,December&dayNames=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday Le fichier contient deux paramètres, monthNames et dayNames. Chacun des paramètres contient une liste séparée par des virgules qui est analysée sous forme de chaîne. Vous pouvez transformer cette liste en tableau à l’aide de la méthode String.split(). ![]() Une fois les données chargées, l’événement complete est distribué et le contenu du document externe peut alors être utilisé dans la propriété data de URLLoader, comme l’illustre le code suivant :
function completeHandler(event) { var loader2 = event.target; air.trace(loader2.data); } Si le document distant contient des paires nom-valeur, vous pouvez analyser les données à l’aide de la classe URLVariables en transmettant le contenu du fichier chargé, comme suit : private function completeHandler(event:Event):void { var loader2:URLLoader = URLLoader(event.target); var variables:URLVariables = new URLVariables(loader2.data); trace(variables.dayNames); } Chaque paire nom-valeur issue du fichier externe devient une nouvelle propriété de l’objet URLVariables. Chaque propriété de cet objet dans l’exemple de code précédent est traité comme une chaîne. Si la valeur de la paire nom-valeur est une liste d’éléments, vous pouvez convertir la chaîne en tableau en appelant la méthode String.split(), comme suit : var dayNameArray:Array = variables.dayNames.split(","); ![]() Au lieu de charger le contenu du fichier distant sous forme de chaîne et de créer un objet URLVariables, vous pouvez attribuer à la propriété URLLoader.dataFormat la valeur de l’une des propriétés statiques de la classe URLLoaderDataFormat. Les trois valeurs possibles de la propriété URLLoader.dataFormat sont les suivantes :
Le code suivant montre comment vous pouvez automatiquement analyser les données chargées dans un objet URLVariables en attribuant à la propriété URLLoader.dataFormat la valeur URLLoaderDataFormat.VARIABLES. package { import flash.display.Sprite; import flash.events.*; import flash.net.URLLoader; import flash.net.URLLoaderDataFormat; import flash.net.URLRequest; public class URLLoaderDataFormatExample extends Sprite { public function URLLoaderDataFormatExample() { var request:URLRequest = new URLRequest("http://www.[yourdomain].com/params.txt"); var variables:URLLoader = new URLLoader(); variables.dataFormat = URLLoaderDataFormat.VARIABLES; variables.addEventListener(Event.COMPLETE, completeHandler); try { variables.load(request); } catch (error:Error) { trace("Unable to load URL: " + error); } } private function completeHandler(event:Event):void { var loader:URLLoader = URLLoader(event.target); trace(loader.data.dayNames); } } } Remarque : la valeur par défaut de URLLoader.dataFormat est URLLoaderDataFormat.TEXT.
Comme le montre l’exemple suivant, le chargement de données XML à partir d’un fichier externe s’effectue comme le chargement de données URLVariables. Vous pouvez créer une occurrence d’URLRequest et une occurrence d’URLLoader et vous en servir pour télécharger un document XML distant. Lorsque le fichier est complètement téléchargé, l’événement Event.COMPLETE est distribué et le contenu du fichier externe est converti en occurrence de XML, que vous pouvez analyser avec les méthodes et propriétés XML. package { import flash.display.Sprite; import flash.errors.*; import flash.events.*; import flash.net.URLLoader; import flash.net.URLRequest; public class ExternalDocs extends Sprite { public function ExternalDocs() { var request:URLRequest = new URLRequest("http://www.[yourdomain].com/data.xml"); var loader:URLLoader = new URLLoader(); loader.addEventListener(Event.COMPLETE, completeHandler); try { loader.load(request); } catch (error:ArgumentError) { trace("An ArgumentError has occurred."); } catch (error:SecurityError) { trace("A SecurityError has occurred."); } } private function completeHandler(event:Event):void { var dataXML:XML = XML(event.target.data); trace(dataXML.toXMLString()); } } } Communication avec des scripts externesOutre le chargement de fichiers de données externes, la classe URLVariables permet d’envoyer des variables à un script côté serveur et de traiter la réponse du serveur. Cela s’avère utile, par exemple, si vous programmez un jeu et souhaitez envoyer le score de l’utilisateur à un serveur afin de vérifier s’il faut l’ajouter à la liste des scores les plus élevés ; ou encore envoyer les informations de connexion de l’utilisateur au serveur pour validation. Un script côté serveur peut traiter le nom d’utilisateur et le mot de passe, les comparer à une base de données et confirmer en retour la validité des informations fournies par l’utilisateur. L’extrait de code ci-après crée un objet URLVariables nommé variables, qui génère une nouvelle variable appelée name. Ensuite, un objet URLRequest est créé pour spécifier l’URL du script côté serveur à laquelle doivent être envoyées les variables. Vous pouvez alors définir la propriété method de l’objet URLRequest pour envoyer les variables sous forme de requête HTTP POST . Pour ajouter l’objet URLVariables à la requête URL, définissez la propriété data de l’objet URLRequest sur l’objet URLVariables créé plus tôt. Enfin, l’occurrence de URLLoader est créée et la méthode URLLoader.load() appelée ; cette dernière lance la requête. var variables:URLVariables = new URLVariables("name=Franklin"); var request:URLRequest = new URLRequest(); request.url = "http://www.[yourdomain].com/greeting.cfm"; request.method = URLRequestMethod.POST; request.data = variables; var loader:URLLoader = new URLLoader(); loader.dataFormat = URLLoaderDataFormat.VARIABLES; loader.addEventListener(Event.COMPLETE, completeHandler); try { loader.load(request); } catch (error:Error) { trace("Unable to load URL"); } function completeHandler(event:Event):void { trace(event.target.data.welcomeMessage); } Le code suivant reprend le contenu du document Adobe ColdFusion® greeting.cfm utilisé dans l’exemple précédent : <cfif NOT IsDefined("Form.name") OR Len(Trim(Form.Name)) EQ 0> <cfset Form.Name = "Stranger" /> </cfif> <cfoutput>welcomeMessage=#UrlEncodedFormat("Welcome, " & Form.name)# </cfoutput> |
![]() |