Utilisation de la classe FileReference

Flash Player 9 et les versions ultérieures, Adobe AIR 1.0 et les versions ultérieures

Un objet FileReference représente un fichier de données stocké sur un client ou un serveur. Les méthodes de la classe FileReference permettent à votre application de charger et d’enregistrer localement des fichiers de données et de transférer ces derniers entre la machine locale et un serveur distant.

La classe FileReference propose deux approches distinctes pour charger, transférer et enregistrer les fichiers de données. Depuis son introduction, la classe FileReference comprend les méthodes browse(), upload() et download(). La méthode browse() permet à l’utilisateur de sélectionner un fichier. La méthode upload() permet de transférer les données du fichier vers un serveur distant. La méthode download() permet d’extraire les données du serveur et de les enregistrer dans un fichier local. Depuis Flash Player 10 et Adobe AIR 1.5, la classe FileReference intègre les méthodes load() et save(). Grâce aux méthodes load() et save(), vous pouvez également accéder aux fichiers locaux et les enregistrer directement. L’utilisation de ces méthodes est similaire aux méthodes du même nom dont disposent les classes URLLoader et Loader.

Remarque : la classe File, qui étend la classe FileReference, et la classe FileStream proposent d’autres fonctions de manipulation des fichiers et du système de fichiers local. Les classes File et FileStream sont prises en charge dans AIR uniquement et non dans Flash Player.

Adobe recommande

Load and Save Local Files (disponible en anglais uniquement)

Kevin Hoyt
Dans cette vidéo, Kevin Hoyt explique qu’il est très facile de charger et d’enregistrer le contenu local avec Flash.

FileReference, classe

Chaque objet FileReference représente un fichier de données local hébergé sur la machine locale. Les propriétés de la classe FileReference contiennent des informations sur la taille, le type, le nom, l’extension, le créateur, la date de création et la date de modification du fichier.

Remarque : la propriété creator est prise en charge sous Mac OS uniquement. Toutes les autres plates-formes renvoient la valeur null.
Remarque : la propriété extension est prise en charge par Adobe AIR uniquement.

Pour créer une occurrence de la classe FileReference, procédez comme suit, au choix :

  • Utilisez l’opérateur new, comme indiqué dans le code suivant :
    import flash.net.FileReference; 
    var fileRef:FileReference = new FileReference();
  • Appelez la méthode FileReferenceList.browse(), qui ouvre une boîte de dialogue et invite l’utilisateur à sélectionner un ou plusieurs fichiers à télécharger. Elle crée ensuite un tableau d’objets FileReference si l’utilisateur réussit à sélectionner un ou plusieurs fichiers.

Une fois l’objet FileReference créé, vous pouvez procéder comme suit :

  • Appelez la méthode FileReference.browse(), qui ouvre une boîte de dialogue et invite l’utilisateur à sélectionner un fichier unique dans le système de fichiers local. Cette opération est généralement effectuée avant d’appeler la méthode FileReference.upload() ou FileReference.load(). La méthode FileReference.upload() charge le fichier sur un serveur distant. La méthode FileReference.load() ouvre un fichier local.

  • Appelez la méthode FileReference.download(). La méthode download ouvre une boîte de dialogue qui permet à l’utilisateur de sélectionner l’emplacement d’enregistrement d’un nouveau fichier. Elle télécharge ensuite les données du serveur et les stocke dans le nouveau fichier.

  • Appelez la méthode FileReference.load(). Cette méthode commence le chargement de données à partir d’un fichier précédemment sélectionné à l’aide de la méthode browse(). Il est impossible d’appeler la méthode load() tant que l’opération browse() n’est pas terminée (c’est-à-dire lorsque l’utilisateur sélectionne un fichier).

  • Appelez la méthode FileReference.save(). Cette méthode ouvre une boîte de dialogue et invite l’utilisateur à sélectionner un emplacement de fichier unique sur le système de fichiers local. Elle permet ensuite d’enregistrer les données à l’emplacement spécifié.

Remarque : vous ne pouvez exécuter qu’une seule méthode browse(), download() ou save() à la fois, car une seule boîte de dialogue peut être ouverte à un moment donné.

Les propriétés de l’objet FileReference, telles que name, size ou modificationDate, ne sont pas définies tant que l’un des événements suivants ne s’est pas produit :

  • La méthode FileReference.browse() ou FileReferenceList.browse() a été appelée et l’utilisateur a sélectionné un fichier dans la boîte de dialogue.

  • La méthode FileReference.download() a été appelée et l’utilisateur a stipulé un nouvel emplacement de fichier par le biais de la boîte de dialogue.

Remarque : lors d’un téléchargement, seule la propriété FileReference.name est renseignée avant la fin du téléchargement. Une fois que le fichier est téléchargé, toutes les propriétés sont disponibles.

Lors de l’exécution des appels de la méthode FileReference.browse(), FileReferenceList.browse(), FileReference.download(), FileReference.load() ou FileReference.save(), la plupart des lecteurs poursuivent la lecture du fichier SWF, ainsi que la distribution d’événements et l’exécution du code.

Pour les opérations de chargement ou téléchargement, un fichier SWF peut uniquement accéder aux fichiers de son propre domaine, ce qui comprend tous les domaines spécifiés par un fichier de régulation. Vous devez placer un fichier de régulation sur le serveur contenant le fichier, si ce serveur ne se trouve pas sur le même domaine que le fichier SWF ayant initié le chargement ou le téléchargement.

Voir FileReference.

Chargement de données à partir d’un fichier

La méthode FileReference.load() vous permet de charger des données en mémoire à partir d’un fichier local.

Remarque : le code doit tout d’abord appeler la méthode FileReference.browse() pour que l’utilisateur puisse sélectionner le fichier à charger. Cette restriction ne s’applique pas au contenu qui s’exécute dans le sandbox de sécurité de l’application Adobe AIR.

La méthode FileReference.load() renvoie une valeur immédiatement après avoir été appelée, mais les données en cours de chargement ne sont pas disponibles tout de suite. L’objet FileReference distribue des événements pour appeler les méthodes d’écouteur à chaque étape du processus de chargement.

L’objet FileReference distribue les événements suivants pendant le processus de chargement.

  • Evénement open (Event.OPEN) : distribué lorsque l’opération de chargement commence.

  • Evénement progress (ProgressEvent.PROGRESS) : distribué régulièrement lorsque le fichier lit des octets de données.

  • Evénement complete (Event.COMPLETE) : distribué en cas de réussite de l’opération de chargement.

  • Evénement ioError (IOErrorEvent.IO_ERROR) : distribué si le processus de chargement échoue en raison d’une erreur d’entrée/sortie lors de l’ouverture ou de la lecture des données du fichier.

Une fois que l’objet FileReference distribue l’événement complete, il est possible d’accéder aux données chargées comme un élément ByteArray dans la propriété data de l’objet FileReference.

L’exemple suivant indique comment inviter l’utilisateur à sélectionner un fichier, puis à charger les données de ce dernier en mémoire :

package 
{ 
     import flash.display.Sprite; 
    import flash.events.*;  
    import flash.net.FileFilter; 
    import flash.net.FileReference; 
    import flash.net.URLRequest; 
    import flash.utils.ByteArray; 
 
    public class FileReferenceExample1 extends Sprite 
    { 
        private var fileRef:FileReference; 
        public function FileReferenceExample1() 
        { 
            fileRef = new FileReference(); 
            fileRef.addEventListener(Event.SELECT, onFileSelected); 
            fileRef.addEventListener(Event.CANCEL, onCancel); 
            fileRef.addEventListener(IOErrorEvent.IO_ERROR, onIOError); 
            fileRef.addEventListener(SecurityErrorEvent.SECURITY_ERROR, 
                        onSecurityError); 
            var textTypeFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", 
                        "*.txt;*.rtf"); 
            fileRef.browse([textTypeFilter]); 
        } 
        public function onFileSelected(evt:Event):void 
        { 
            fileRef.addEventListener(ProgressEvent.PROGRESS, onProgress); 
            fileRef.addEventListener(Event.COMPLETE, onComplete); 
            fileRef.load(); 
        } 
 
        public function onProgress(evt:ProgressEvent):void 
        { 
            trace("Loaded " + evt.bytesLoaded + " of " + evt.bytesTotal + " bytes."); 
        } 
 
        public function onComplete(evt:Event):void 
        { 
            trace("File was successfully loaded."); 
            trace(fileRef.data); 
        } 
 
        public function onCancel(evt:Event):void 
        { 
            trace("The browse request was canceled by the user."); 
        } 
 
        public function onIOError(evt:IOErrorEvent):void 
        { 
            trace("There was an IO Error."); 
        } 
        public function onSecurityError(evt:Event):void 
        { 
            trace("There was a security error."); 
        } 
    } 
}

Le code d’exemple crée tout d’abord l’objet FileReference nommé fileRef, puis appelle sa méthode browse(). La méthode browse ouvre une boîte de dialogue et l’utilisateur est invité à sélectionner un fichier. Une fois le fichier sélectionné, le code appelle la méthode onFileSelected(). Cette méthode ajoute des écouteurs aux événements progress et complete, puis appelle la méthode load() de l’objet FileReference. Les autres méthodes de gestionnaire de cet exemple se contentent de générer des messages qui indiquent le déroulement de l’opération de chargement. Lorsque le chargement est terminé, l’application affiche le contenu du fichier chargé à l’aide de la méthode trace().

Dans Adobe AIR, la classe FileStream propose d’autres fonctionnalités de lecture des données dans un fichier local (voir Lecture et écriture de fichiers).

Enregistrement de données dans des fichiers locaux

La méthode FileReference.save() vous permet d’enregistrer des données dans un fichier local. Elle commence par ouvrir une boîte de dialogue qui permet à l’utilisateur d’entrer un nouveau nom de fichier et l’emplacement d’enregistrement du fichier. Une fois le nom de fichier et l’emplacement sélectionnés, les données sont écrites dans le nouveau fichier. Lorsque le fichier est enregistré, les propriétés de l’objet FileReference sont renseignées avec les propriétés du fichier local.

Remarque : le code ne doit appeler la méthode FileReference.save() qu’en réponse à un événement utilisateur, tel qu’un événement de type clic de souris ou pression de touche. Dans le cas contraire, une erreur est renvoyée. Cette restriction ne s’applique pas au contenu qui s’exécute dans le sandbox de sécurité de l’application Adobe AIR.

La méthode FileReference.save() est renvoyée juste après son appel. L’objet FileReference distribue ensuite des événements pour appeler les méthodes d’écouteur à chaque étape du processus d’enregistrement de fichier.

L’objet FileReference distribue les événements suivants au cours du processus d’enregistrement de fichier :

  • Evénement select (Event.SELECT) : distribué lorsque l’utilisateur indique l’emplacement et le nom du nouveau fichier à enregistrer.

  • Evénement cancel (Event.CANCEL) : distribué lorsque l’utilisateur clique sur le bouton Annuler dans la boîte de dialogue.

  • Evénement open (Event.OPEN) : distribué lorsque l’opération d’enregistrement commence.

  • Evénement progress (ProgressEvent.PROGRESS) : distribué régulièrement pendant l’enregistrement des octets de données dans le fichier.

  • Evénement complete (Event.COMPLETE) : distribué en cas de réussite de l’opération d’enregistrement.

  • Evénement ioError (IOErrorEvent.IO_ERROR) : distribué si le processus d’enregistrement échoue en raison d’une erreur d’entrée/sortie lors d’une tentative d’enregistrement des données dans le fichier.

Le type d’objet transmis dans le paramètre data de la méthode FileReference.save() détermine le mode d’écriture des données dans le fichier :

  • S’il s’agit d’une valeur String, les données sont enregistrées au format texte UTF-8.

  • S’il s’agit d’un objet XML, elles sont écrites dans un fichier XML en conservant l’ensemble du formatage.

  • S’il s’agit d’un objet ByteArray, leur contenu est écrit directement dans le fichier sans conversion.

  • S’il s’agit d’un autre type d’objet, la méthode FileReference.save() appelle la méthode toString() de l’objet, puis enregistre la valeur String résultante dans un fichier texte UTF-8. S’il est impossible d’appeler la méthode toString() de l’objet, une erreur est renvoyée.

Si la valeur du paramètre data est null, une erreur est renvoyée.

Le code suivant étend l’exemple précédent pour la méthode FileReference.load(). Une fois les données lues dans le fichier, cet exemple invite l’utilisateur à entrer un nom de fichier, puis enregistre les données dans un nouveau fichier :

package 
{ 
    import flash.display.Sprite; 
    import flash.events.*;  
    import flash.net.FileFilter; 
    import flash.net.FileReference; 
    import flash.net.URLRequest; 
    import flash.utils.ByteArray; 
 
    public class FileReferenceExample2 extends Sprite 
    { 
        private var fileRef:FileReference; 
        public function FileReferenceExample2() 
        { 
            fileRef = new FileReference(); 
            fileRef.addEventListener(Event.SELECT, onFileSelected); 
            fileRef.addEventListener(Event.CANCEL, onCancel); 
            fileRef.addEventListener(IOErrorEvent.IO_ERROR, onIOError); 
            fileRef.addEventListener(SecurityErrorEvent.SECURITY_ERROR, 
                        onSecurityError); 
            var textTypeFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", 
                        "*.txt;*.rtf"); 
            fileRef.browse([textTypeFilter]); 
        } 
        public function onFileSelected(evt:Event):void 
        { 
            fileRef.addEventListener(ProgressEvent.PROGRESS, onProgress); 
            fileRef.addEventListener(Event.COMPLETE, onComplete); 
            fileRef.load(); 
        } 
 
        public function onProgress(evt:ProgressEvent):void 
        { 
            trace("Loaded " + evt.bytesLoaded + " of " + evt.bytesTotal + " bytes."); 
        } 
        public function onCancel(evt:Event):void 
        { 
            trace("The browse request was canceled by the user."); 
        } 
        public function onComplete(evt:Event):void 
        { 
            trace("File was successfully loaded."); 
            fileRef.removeEventListener(Event.SELECT, onFileSelected); 
            fileRef.removeEventListener(ProgressEvent.PROGRESS, onProgress); 
            fileRef.removeEventListener(Event.COMPLETE, onComplete); 
            fileRef.removeEventListener(Event.CANCEL, onCancel); 
            saveFile(); 
        } 
        public function saveFile():void 
        { 
            fileRef.addEventListener(Event.SELECT, onSaveFileSelected); 
            fileRef.save(fileRef.data,"NewFileName.txt"); 
        } 
 
        public function onSaveFileSelected(evt:Event):void 
        { 
            fileRef.addEventListener(ProgressEvent.PROGRESS, onSaveProgress); 
            fileRef.addEventListener(Event.COMPLETE, onSaveComplete); 
            fileRef.addEventListener(Event.CANCEL, onSaveCancel); 
        } 
 
        public function onSaveProgress(evt:ProgressEvent):void 
        { 
            trace("Saved " + evt.bytesLoaded + " of " + evt.bytesTotal + " bytes."); 
        } 
         
        public function onSaveComplete(evt:Event):void 
        { 
            trace("File saved."); 
            fileRef.removeEventListener(Event.SELECT, onSaveFileSelected); 
            fileRef.removeEventListener(ProgressEvent.PROGRESS, onSaveProgress); 
            fileRef.removeEventListener(Event.COMPLETE, onSaveComplete); 
            fileRef.removeEventListener(Event.CANCEL, onSaveCancel); 
        } 
 
        public function onSaveCancel(evt:Event):void 
        { 
            trace("The save request was canceled by the user."); 
        } 
 
        public function onIOError(evt:IOErrorEvent):void 
        { 
            trace("There was an IO Error."); 
        } 
        public function onSecurityError(evt:Event):void 
        { 
            trace("There was a security error."); 
        } 
    } 
}

Au terme du chargement des données à partir du fichier, le code appelle la méthode onComplete(). La méthode onComplete() supprime les écouteurs associés aux événements de chargement, puis appelle la méthode saveFile(). La méthode saveFile() appelle la méthode FileReference.save(). La méthode FileReference.save() ouvre une nouvelle boîte de dialogue dans laquelle l’utilisateur entre un nouveau nom de fichier et l’emplacement d’enregistrement de ce dernier. Les autres méthodes d’écouteur d’événement tracent le déroulement du processus d’enregistrement du fichier jusqu’à ce qu’il soit terminé.

Dans Adobe AIR, la classe FileStream propose d’autres fonctionnalités d’écriture des données dans un fichier local (voir Lecture et écriture de fichiers).

Chargement de fichiers sur un serveur

Pour charger des fichiers sur un serveur, commencez par appeler la méthode browse() pour permettre à l’utilisateur de sélectionner un ou plusieurs fichiers. Après l’appel de la méthode FileReference.upload(), le fichier sélectionné est transféré sur le serveur. Si l’utilisateur sélectionne plusieurs fichiers à l’aide de la méthode FileReferenceList.browse(), Flash Player crée un tableau de fichiers sélectionnés appelé FileReferenceList.fileList. Vous pouvez alors utiliser la méthode FileReference.upload() pour charger chaque fichier individuellement.

Remarque : l’utilisation de la méthode FileReference.browse() ne vous permet de charger qu’un seul fichier à la fois. Pour autoriser l’utilisateur à charger plusieurs fichiers, faites appel à la méthode FileReferenceList.browse().

Par défaut, la boîte de dialogue de sélection de fichier du système d’exploitation permet à l’utilisateur de choisir tout type de fichier sur l’ordinateur local. Les développeurs peuvent toutefois filtrer les types de fichier à l’aide de la classe FileFilter, en transmettant un tableau d’occurrences de filtres de fichiers à la méthode browse() :

var imageTypes:FileFilter = new FileFilter("Images (*.jpg, *.jpeg, *.gif, *.png)", "*.jpg; *.jpeg; *.gif; *.png"); 
var textTypes:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", "*.txt; *.rtf"); 
var allTypes:Array = new Array(imageTypes, textTypes); 
var fileRef:FileReference = new FileReference(); 
fileRef.browse(allTypes);

Lorsque l’utilisateur a sélectionné les fichiers et cliqué sur le bouton Ouvrir dans la boîte de dialogue de sélection système, l’événement Event.SELECT est distribué. Si vous sélectionnez le fichier à charger à l’aide de la méthode FileReference.browse(), le code suivant envoie le fichier à un serveur Web :

var fileRef:FileReference = new FileReference(); 
fileRef.addEventListener(Event.SELECT, selectHandler); 
fileRef.addEventListener(Event.COMPLETE, completeHandler); 
try 
{ 
    var success:Boolean = fileRef.browse(); 
} 
catch (error:Error) 
{ 
    trace("Unable to browse for files."); 
} 
function selectHandler(event:Event):void 
{ 
    var request:URLRequest = new URLRequest("http://www.[yourdomain].com/fileUploadScript.cfm") 
    try 
    { 
        fileRef.upload(request); 
    } 
    catch (error:Error) 
    { 
        trace("Unable to upload file."); 
    } 
} 
function completeHandler(event:Event):void 
{ 
    trace("uploaded"); 
}
Avec la méthode FileReference.upload(), vous pouvez envoyer des données au serveur en utilisant les propriétés URLRequest.method et URLRequest.data en vue d’envoyer des variables à l’aide de la méthode POST ou GET.

Si vous tentez de charger un fichier à l’aide de la méthode FileReference.upload(), les événements suivants sont distribués :

  • Evénement open (Event.OPEN) : distribué lorsque l’opération de chargement commence.

  • Evénement progress (ProgressEvent.PROGRESS) : distribué régulièrement pendant le chargement des octets de données du fichier.

  • Evénement complete (Event.COMPLETE) : distribué en cas de réussite de l’opération de chargement.

  • Evénement httpStatus (HTTPStatusEvent.HTTP_STATUS) : distribué lorsque le processus de chargement échoue en raison d’une erreur HTTP.

  • Evénement httpResponseStatus (HTTPStatusEvent.HTTP_RESPONSE_STATUS) : distribué si un appel de la méthode upload() ou uploadUnencoded() tente d’accéder aux données via HTTP, et si Adobe AIR est capable de détecter et de renvoyer le code d’état de la requête.

  • Evénement securityError (SecurityErrorEvent.SECURITY_ERROR) : distribué lorsqu’une opération de chargement échoue en raison d’une violation de la sécurité.

  • Evénement uploadCompleteData (DataEvent.UPLOAD_COMPLETE_DATA) : distribué après réception des données par le serveur suite à un chargement réussi.

  • Evénement ioError (IOErrorEvent.IO_ERROR) : distribué si le processus de chargement échoue pour l’une des raisons suivantes :

    • Une erreur d’entrée/sortie se produit dans Flash Player pendant la lecture, l’écriture ou la transmission du fichier.

    • Le fichier SWF tente de charger un fichier sur un serveur nécessitant une authentification (un nom d’utilisateur et un mot de passe, par exemple). Au cours du chargement, Flash Player ne permet pas aux utilisateurs d’entrer des mots de passe.

    • Le paramètre url contient un protocole incorrect. La méthode FileReference.upload() doit utiliser HTTP ou HTTPS.

Flash Player n’offre pas une prise en charge complète des serveurs nécessitant une authentification. Seuls les fichiers SWF s’exécutant dans un navigateur, via le module d’extension du navigateur ou le contrôle Microsoft ActiveX®, peuvent fournir une boîte de dialogue pour inviter l’utilisateur à entrer un nom et un mot de passe d’authentification, et ce uniquement pour les téléchargements. Le transfert de fichiers échoue si le chargement est effectué à l’aide du module d’extension ou du contrôle ActiveX, ou si un chargement/téléchargement est effectué par le biais du lecteur autonome ou externe.

Pour créer un script serveur dans ColdFusion de manière à accepter les chargements de fichier en provenance de Flash Player, vous pouvez utiliser un code semblable à celui-ci :

<cffile action="upload" filefield="Filedata" destination="#ExpandPath('./')#" nameconflict="OVERWRITE" />

Ce code ColdFusion charge le fichier envoyé par Flash Player et l’enregistre dans le même répertoire que le modèle ColdFusion, en écrasant tout fichier existant du même nom. Cet exemple présente le minimum de code nécessaire à l’acceptation du chargement d’un fichier ; ce script ne doit pas être utilisé dans un environnement de production. Ajoutez de préférence un mécanisme de validation des données pour garantir que les utilisateurs chargent uniquement des types de fichiers autorisés, telle une image plutôt qu’un script côté serveur potentiellement dangereux.

Le code ci-après présente le chargement de fichiers via PHP, avec validation des données. Le script limite le nombre de fichiers chargés dans le répertoire cible à 10, vérifie que le fichier fait moins de 200 Ko et autorise uniquement le chargement et l’enregistrement de fichiers JPEG, GIF ou PNG.

<?php 
$MAXIMUM_FILESIZE = 1024 * 200; // 200KB 
$MAXIMUM_FILE_COUNT = 10; // keep maximum 10 files on server 
echo exif_imagetype($_FILES['Filedata']); 
if ($_FILES['Filedata']['size'] <= $MAXIMUM_FILESIZE) 
{ 
    move_uploaded_file($_FILES['Filedata']['tmp_name'], "./temporary/".$_FILES['Filedata']['name']); 
    $type = exif_imagetype("./temporary/".$_FILES['Filedata']['name']); 
    if ($type == 1 || $type == 2 || $type == 3) 
    { 
        rename("./temporary/".$_FILES['Filedata']['name'], "./images/".$_FILES['Filedata']['name']); 
    } 
    else 
    { 
        unlink("./temporary/".$_FILES['Filedata']['name']); 
    } 
} 
$directory = opendir('./images/'); 
$files = array(); 
while ($file = readdir($directory)) 
{ 
    array_push($files, array('./images/'.$file, filectime('./images/'.$file))); 
} 
usort($files, sorter); 
if (count($files) > $MAXIMUM_FILE_COUNT) 
{ 
    $files_to_delete = array_splice($files, 0, count($files) - $MAXIMUM_FILE_COUNT); 
    for ($i = 0; $i < count($files_to_delete); $i++) 
    { 
        unlink($files_to_delete[$i][0]); 
    } 
} 
print_r($files); 
closedir($directory); 
 
function sorter($a, $b) 
{ 
    if ($a[1] == $b[1]) 
    { 
        return 0; 
    } 
    else 
    { 
        return ($a[1] < $b[1]) ? -1 : 1; 
    } 
} 
?>

Vous pouvez transmettre des variables supplémentaires au script de chargement à l’aide de la méthode de requête POST ou GET. Pour envoyer des variables POST au script de chargement, vous pouvez utiliser le code suivant :

var fileRef:FileReference = new FileReference(); 
fileRef.addEventListener(Event.SELECT, selectHandler); 
fileRef.addEventListener(Event.COMPLETE, completeHandler); 
fileRef.browse(); 
function selectHandler(event:Event):void 
{ 
    var params:URLVariables = new URLVariables(); 
    params.date = new Date(); 
    params.ssid = "94103-1394-2345"; 
    var request:URLRequest = new URLRequest("http://www.yourdomain.com/FileReferenceUpload/fileupload.cfm"); 
    request.method = URLRequestMethod.POST; 
    request.data = params; 
    fileRef.upload(request, "Custom1"); 
} 
function completeHandler(event:Event):void 
{ 
    trace("uploaded"); 
}

L’exemple précédent crée un objet URLVariables à transmettre au script côté serveur distant. Dans les versions précédentes d’ActionScript, il était possible de transmettre des variables au script de chargement en passant des valeurs dans la chaîne de requête. ActionScript 3.0 vous permet de transmettre des variables au script distant à l’aide de l’objet URLRequest. Vous pouvez ainsi transmettre des données à l’aide de la méthode POST ou GET, ce qui simplifie et rationalise le transfert de gros volumes de données. Pour spécifier si les variables sont transmises à l’aide de la méthode de requête GET ou POST, il est possible de définir la propriété URLRequest.method sur URLRequestMethod.GET ou URLRequestMethod.POST, respectivement.

ActionScript 3.0 vous permet de remplacer le nom de champ par défaut du fichier à charger (Filedata) en ajoutant un deuxième paramètre à la méthode upload(), comme illustré dans l’exemple précédent (dans lequel la valeur par défaut Filedata est remplacée par Custom1).

Par défaut, Flash Player ne tente pas d’effectuer un chargement de test ; vous pouvez toutefois le faire en transmettant la valeur true comme troisième paramètre de la méthode upload(). L’objectif du test est de vérifier que le chargement véritable se fera sans problème et que l’authentification du serveur, si nécessaire, réussira.

Remarque : actuellement, le test du chargement s’effectue uniquement dans les versions Windows de Flash Player.

Le script serveur qui gère le chargement doit attendre une requête HTTP POST comportant les éléments suivants :

  • Content-Type avec la valeur multipart/form-data.

  • Content-Disposition avec comme attribut name « Filedata » et comme attribut filename le nom du fichier d’origine. Pour spécifier un attribut name, transmettez une valeur pour le paramètre uploadDataFieldName dans la méthode FileReference.upload().

  • Le contenu binaire du fichier.

Voici un exemple de requête HTTP POST :

POST /handler.asp HTTP/1.1 
Accept: text/* 
Content-Type: multipart/form-data; 
boundary=----------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6 
User-Agent: Shockwave Flash 
Host: www.mydomain.com 
Content-Length: 421 
Connection: Keep-Alive 
Cache-Control: no-cache 
 
------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6  
Content-Disposition: form-data; name="Filename" 
 
sushi.jpg  
------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6 
Content-Disposition: form-data; name="Filedata"; filename="sushi.jpg" 
Content-Type: application/octet-stream 
 
Test File  
------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6 
Content-Disposition: form-data; name="Upload" 
 
Submit Query 
------------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6 
(actual file data,,,)

L’exemple de requête HTTP POST suivant envoie trois variables POST : api_sig, api_key et auth_token, puis utilise la valeur de champ de données "photo" :

POST /handler.asp HTTP/1.1 
Accept: text/* 
Content-Type: multipart/form-data; 
boundary=----------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6 
User-Agent: Shockwave Flash 
Host: www.mydomain.com 
Content-Length: 421 
Connection: Keep-Alive 
Cache-Control: no-cache 
 
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 
Content-Disposition: form-data; name="Filename" 
 
sushi.jpg 
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 
Content-Disposition: form-data; name="api_sig" 
 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 
Content-Disposition: form-data; name="api_key" 
 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 
Content-Disposition: form-data; name="auth_token" 
 
XXXXXXXXXXXXXXXXXXXXXXX 
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 
Content-Disposition: form-data; name="photo"; filename="sushi.jpg" 
Content-Type: application/octet-stream 
 
(actual file data,,,) 
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 
Content-Disposition: form-data; name="Upload" 
 
Submit Query 
------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7--

Téléchargement de fichiers à partir d’un serveur

Vous pouvez autoriser les utilisateurs à télécharger des fichiers à partir d’un serveur grâce à la méthode FileReference.download(), qui prend deux paramètres : request et defaultFileName. Le premier paramètre est l’objet URLRequest contenant l’URL du fichier à télécharger. Le second est facultatif ; il permet de spécifier un nom de fichier par défaut qui apparaîtra dans la boîte de dialogue de téléchargement. Si vous ignorez le second paramètre, defaultFileName, le nom de fichier utilisé est dérivé de l’URL.

Le code suivant télécharge un fichier nommé index.xml à partir du même répertoire que le fichier SWF :

var request:URLRequest = new URLRequest("index.xml"); 
var fileRef:FileReference = new FileReference(); 
fileRef.download(request);

Pour utiliser comme nom par défaut currentnews.xml au lieu d’index.xml, spécifiez le paramètre defaultFileName, comme illustré par le fragment de code suivant :

var request:URLRequest = new URLRequest("index.xml"); 
var fileToDownload:FileReference = new FileReference(); 
fileToDownload.download(request, "currentnews.xml");

Le changement de nom du fichier peut s’avérer utile si le nom du fichier sur le serveur est peu évocateur ou généré automatiquement. Il est également judicieux de spécifier le paramètre defaultFileName lorsque vous téléchargez un fichier à l’aide d’un script côté serveur, au lieu d’effectuer un téléchargement direct. Par exemple, il est nécessaire de spécifier le paramètre defaultFileName si vous utilisez un script côté serveur qui télécharge des fichiers en fonction des variables URL qui lui sont transmises. Autrement, le nom par défaut du fichier téléchargé est le nom du script côté serveur.

Vous pouvez également envoyer des données au serveur avec l’appel de la méthode download() en ajoutant des paramètres à l’URL pour que le script serveur les analyse. L’extrait de code ActionScript 3.0 ci-après télécharge un document en fonction des paramètres transmis à un script ColdFusion :

package 
{ 
    import flash.display.Sprite; 
    import flash.net.FileReference; 
    import flash.net.URLRequest; 
    import flash.net.URLRequestMethod; 
    import flash.net.URLVariables; 
 
    public class DownloadFileExample extends Sprite 
    { 
        private var fileToDownload:FileReference; 
        public function DownloadFileExample() 
        { 
            var request:URLRequest = new URLRequest(); 
            request.url = "http://www.[yourdomain].com/downloadfile.cfm"; 
            request.method = URLRequestMethod.GET; 
            request.data = new URLVariables("id=2"); 
            fileToDownload = new FileReference(); 
            try 
            { 
                fileToDownload.download(request, "file2.txt"); 
            } 
            catch (error:Error) 
            { 
                trace("Unable to download file."); 
            } 
        } 
    } 
}

Le code suivant présente le script ColdFusion download.cfm, qui télécharge l’un des deux fichiers stockés sur le serveur en fonction de la valeur d’une variable URL :

<cfparam name="URL.id" default="1" /> 
<cfswitch expression="#URL.id#"> 
    <cfcase value="2"> 
        <cfcontent type="text/plain" file="#ExpandPath('two.txt')#" deletefile="No" /> 
    </cfcase> 
    <cfdefaultcase> 
        <cfcontent type="text/plain" file="#ExpandPath('one.txt')#" deletefile="No" /> 
    </cfdefaultcase> 
</cfswitch>

Classe FileReferenceList

La classe FileReferenceList permet à l’utilisateur de sélectionner un ou plusieurs fichiers à charger dans un script côté serveur. Le chargement de fichiers est géré par la méthode FileReference.upload(), qui doit être appelée pour chaque fichier sélectionné.

Le code suivant crée deux objets FileFilter (imageFilter et textFilter) et les transmet sous forme de tableau à la méthode FileReferenceList.browse(). Ainsi, la boîte de dialogue du système d’exploitation propose deux types de fichiers possibles.

var imageFilter:FileFilter = new FileFilter("Image Files (*.jpg, *.jpeg, *.gif, *.png)", "*.jpg; *.jpeg; *.gif; *.png"); 
var textFilter:FileFilter = new FileFilter("Text Files (*.txt, *.rtf)", "*.txt; *.rtf"); 
var fileRefList:FileReferenceList = new FileReferenceList(); 
try 
{ 
    var success:Boolean = fileRefList.browse(new Array(imageFilter, textFilter)); 
} 
catch (error:Error)  
{ 
    trace("Unable to browse for files."); 
}

L’utilisation de la classe FileReferenceList pour autoriser le chargement de fichiers est semblable à l’utilisation de FileReference.browse(), à la différence que FileReferenceList permet de sélectionner plusieurs fichiers. En cas de sélection de fichiers multiples, il est nécessaire de charger chacun des fichiers choisis à l’aide de FileReference.upload(), comme le montre le code suivant :

var fileRefList:FileReferenceList = new FileReferenceList(); 
fileRefList.addEventListener(Event.SELECT, selectHandler); 
fileRefList.browse(); 
 
function selectHandler(event:Event):void 
{ 
    var request:URLRequest = new URLRequest("http://www.[yourdomain].com/fileUploadScript.cfm"); 
    var file:FileReference; 
    var files:FileReferenceList = FileReferenceList(event.target); 
    var selectedFileArray:Array = files.fileList; 
    for (var i:uint = 0; i < selectedFileArray.length; i++) 
    { 
        file = FileReference(selectedFileArray[i]); 
        file.addEventListener(Event.COMPLETE, completeHandler); 
        try 
        { 
            file.upload(request); 
        } 
        catch (error:Error) 
        { 
            trace("Unable to upload files."); 
        } 
    } 
} 
function completeHandler(event:Event):void 
{ 
    trace("uploaded"); 
}

Comme l’événement Event.COMPLETE s’ajoute à chaque objet FileReference dans le tableau, Flash Player appelle la méthode completeHandler() à la fin du chargement de chacun des fichiers.