Operazioni di caricamento e scaricamento dei file -- Flash CS3

Tramite la classe FileReference è possibile aggiungere la capacità di caricare e scaricare file tra client e server. Agli utenti viene richiesto di selezionare un file da caricare, o un percorso in cui scaricarlo, tramite una finestra di dialogo, ad esempio Apri nel sistema operativo Windows.

Ogni oggetto FileReference che si crea con ActionScript fa riferimento a un singolo file sul disco rigido dell'utente. L'oggetto dispone di proprietà che contengono informazioni su dimensione, tipo, nome, data di creazione e data di modifica del file.

Un'istanza della classe FileReference può essere creata in due modi. È possibile utilizzare l'operatore new come illustrato nel codice riportato di seguito:

import flash.net.FileReference;
var myFileReference:FileReference = new FileReference();

In alternativa, è possibile chiamare il metodo FileReferenceList.browse() che apre una finestra di dialogo nel sistema dell'utente, nella quale viene richiesto di selezionare uno o più file da caricare, quindi crea un array di oggetti FileReference se l'utente riesce a selezionare uno o più file. Ogni oggetto FileReference rappresenta un file selezionato dall'utente nella finestra di dialogo. Nelle proprietà FileReference (ad esempio name, size o modificationDate) di un oggetto FileReference non sono contenuti dati, finché non si verifica una delle seguenti condizioni:

Mentre le chiamate al metodo FileReference.browse(), FileReferenceList.browse() o FileReference.download() sono in esecuzione, la maggior parte dei lettori continua la riproduzione del file SWF.

Sezioni

Classe FileReference

La classe FileReference consente di caricare e scaricare i file tra il computer di un utente e un server. Una finestra di dialogo del sistema operativo richiede all'utente di selezionare un file da caricare o un percorso per lo scaricamento. Ogni oggetto FileReference fa riferimento a un singolo file sul disco dell'utente e ha delle proprietà che contengono informazioni relative a dimensioni, tipo, nome, data di creazione, data di modifica e generatore del file.

Per le operazioni di caricamento e scaricamento, un file SWF può accedere ai file solo dal proprio dominio, compresi gli eventuali domini specificati da un file dei criteri di accesso a più domini. È necessario collocare un file di criteri sul file server nel caso il file SWF che inizializza il caricamento o scaricamento non abbia lo stesso dominio del file server.

Lo script server che gestisce il caricamento del file deve prevedere una richiesta POST HTTP con gli elementi seguenti:

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

Il seguente esempio di richiesta POST HTTP invia tre variabili POST: api_sig, api_key e auth_token e utilizza "photo" come valore personalizzato per il nome del campo dati di caricamento:

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

Caricamento di file su un server

Per caricare dei file su un server, chiamare innanzi tutto il metodo browse() per consentire all'utente di selezionare uno o più file. Dopo che è stato chiamato il metodo FileReference.upload(), il file selezionato viene trasferito sul server. Se l'utente seleziona più file utilizzando il metodo FileReferenceList.browse(), viene creato automaticamente un array dei file selezionati denominato FileReferenceList.fileList. A questo punto è possibile utilizzare il metodo FileReference.upload() per caricare ogni file individualmente.

Per impostazione predefinita, la finestra di dialogo del selettore del sistema consente agli utenti di selezionare qualsiasi tipo di file dal computer locale, tuttavia gli sviluppatori possono specificare uno o più filtri per tipi di file personalizzati utilizzando la classe FileFilter e passando un array di istanze di FileFilter al metodo 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);

Dopo che l'utente ha selezionato i file e ha fatto clic sul pulsante Apri nel selettore del sistema, viene inviato l'evento Event.SELECT. Se per selezionare un file da caricare è stato utilizzato il metodo FileReference.browse(), per inviare il file a un server Web è necessario il codice riportato di seguito:

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

Quando si tenta di caricare il file utilizzando il metodo FileReference.upload(), è possibile che venga inviato uno qualsiasi dei seguenti eventi:

Se si crea uno script server in ColdFusion per accettare il caricamento di un file da Flash Player, è possibile utilizzare codice analogo a quello riportato di seguito:

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

Questo codice ColdFusion carica il file inviato da Flash Player e lo salva nella stessa directory del modello di ColdFusion, sovrascrivendo gli eventuali file con lo stesso nome. Il codice sopra riportato rappresenta la quantità minima di codice necessaria per accettare il caricamento di un file; non utilizzare questo script in un ambiente di produzione. Idealmente è opportuno aggiungere la convalida dei dati per assicurare che gli utenti carichino solo i tipi di file accettati, ad esempio un'immagine anziché uno script sul lato server potenzialmente pericoloso.

Il codice riportato di seguito illustra il caricamento di file utilizzando PHP e include la convalida dei dati. Lo script limita a 10 il numero di file caricati nella directory di caricamento, assicura che le dimensioni del file siano inferiori a 200 KB e consente il caricamento e il salvataggio nel file system solo di file JPEG, GIF o 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;
    }
}
?>

È possibile passare variabili aggiuntive allo script di caricamento utilizzando il metodo di richiesta POST o GET. Per inviare variabili POST aggiuntive allo script di caricamento, è possibile utilizzare il codice riportato di seguito:

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

Nell'esempio precedente viene creato un nuovo oggetto URLVariables che viene passato allo script sul lato server remoto. Nelle versioni precedenti di ActionScript era possibile passare variabili allo script di caricamento sul server mediante valori inclusi nella stringa di query. ActionScript 3.0 consente di passare le variabili allo script remoto utilizzando un oggetto URLRequest, che consente di passare i dati utilizzando il metodo POST o GET; in questo modo diventa inoltre più semplice passare set di dati più estesi. Per specificare se le variabili vengono passate utilizzando il metodo di richiesta GET o POST, è possibile impostare la proprietà URLRequest.method rispettivamente su URLRequestMethod.GET o su URLRequestMethod.POST.

ActionScript 3.0 consente inoltre di ignorare il nome di campo del file di caricamento predefinito Filedata fornendo un secondo parametro al metodo upload(), come illustrato nell'esempio precedente (dove il valore predefinito Filedata è stato sostituito con Custom1).

Per impostazione predefinita, Flash Player non tenta di inviare un caricamento di prova, anche se è possibile ignorare questa impostazione passando il valore true come terzo parametro al metodo upload(). Lo scopo del caricamento di prova è di verificare se il caricamento del file vero e proprio darà esito positivo, così come l'autenticazione sul server (se richiesta).

Scaricamento di file da un server

È possibile consentire agli utenti di scaricare i file da un server utilizzando il metodo FileReference.download(), che accetta due parametri: request e defaultFileName. Il primo parametro è l'oggetto URLRequest che contiene l'URL del file da scaricare. Il secondo parametro è facoltativo e consente di specificare un nome file predefinito che verrà visualizzato nella finestra di dialogo di scaricamento del file. Se si omette il secondo parametro, defaultFileName, viene utilizzato il nome file dall'URL specificato.

Il codice riportato di seguito consente di scaricare un file di nome index.xml dalla stessa directory del documento SWF:

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

Per impostare il nome predefinito su currentnews.xml anziché su index.xml, specificare il parametro defaultFileName, come illustrato nello snippet di codice seguente:

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

La capacità di rinominare un file può risultare molto utile se il nome file del server non è intuitivo o è stato generato dal server. È inoltre opportuno specificare il parametro defaultFileName quando si scarica un file utilizzando uno script sul lato server, anziché direttamente. Ad esempio, è necessario specificare il parametro defaultFileName se si utilizza uno script sul lato server che scarica i file in base alle variabili URL passate. Diversamente, il nome predefinito del file scaricato corrisponde al nome dello script sul lato server.

È possibile inviare dati al server tramite il metodo download() aggiungendo dei parametri all'URL, che lo script server deve analizzare. Lo snippet di codice ActionScript 3.0 riportato di seguito consente di scaricare un documento in base ai parametri passati a uno 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.");
            }
        }
    }
}

Il codice riportato di seguito illustra lo script ColdFusion, download.cfm, che scarica uno dei due file dal server, a seconda del valore di una variabile 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 consente all'utente di selezionare uno o più file da caricare in uno script sul lato server. Il caricamento del file viene gestito dal metodo FileReference.upload(), che deve essere chiamato su ogni file selezionato dall'utente.

Il codice riportato di seguito crea due oggetti FileFilter (imageFilter e textFilter) e li passa in un array al metodo FileReferenceList.browse(). Di conseguenza, nella finestra di dialogo dei file del sistema operativo vengono visualizzati due possibili filtri per i tipi di file.

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.");
}

Consentire all'utente di selezionare e caricare uno o più file utilizzando la classe FileReferenceList equivale a utilizzare FileReference.browse() per selezionare i file, anche se FileReferenceList consente di selezionare più di un file. Per caricare più file, è necessario utilizzare FileReference.upload() per caricare ogni file selezionato, come illustrato dal codice riportato di seguito:

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

Poiché l'evento Event.COMPLETE viene aggiunto a ogni singolo oggetto FileReference nell'array, viene chiamato automaticamente il metodo completeHandler() al termine del caricamento di ogni file.