Flash CS3 Documentation

ActionScript 2.0 Language Reference > ActionScript classes > FileReference (flash.net.FileReference)

FileReference (flash.net.FileReference)

Object
    |
    +-flash.net.FileReference

public class FileReference
extends Object

The FileReference class provides a means to upload and download files between a user's computer and a server. An operating-system dialog box prompts the user to select a file to upload or a location for download. Each FileReference object refers to a single file on the user's hard disk and has properties that contain information about the file's size, type, name, creation date, modification date, and creator type (Macintosh only).

FileReference instances are created in two ways:

• When you use the new operator with the FileReference constructor: var myFileReference = new FileReference();
• When you call FileReferenceList.browse(), which creates an array of FileReference objects

During an upload operation, all of the properties of a FileReference object are populated by calls to FileReference.browse() or FileReferenceList.browse(). During a download operation, the name property is populated when onSelect has been invoked; all other properties are populated when onComplete has been invoked.

The browse() method opens an operating-system dialog box which prompts the user to select any local file for upload. The FileReference.browse() method lets the user select a single file; the FileReferenceList.browse() method lets the user select multiple files. After a successful call to the browse() method, call the FileReference.upload() method to upload one file at a time. The FileReference.download() method prompts the user for a location to save the file and initiates downloading from a remote URL.

The FileReference and FileReferenceList classes do not let you set the default file location for the dialog box generated by browse() and download() calls. The default location shown in the dialog box is the most recently browsed folder, if that location can be determined, or the desktop. The classes do not allow you to read from or write to the transferred file. They do not allow the SWF file that initiated the upload or download to access the uploaded or downloaded file or the file's location on the user's disk.

The FileReference and FileReferenceList classes also do not provide methods for authentication. With servers that require authentication, you can download files with the Flash Player browser plug-in, but uploading (on all players) and downloading (on the stand-alone or external player) fails. Use FileReference event listeners to ascertain whether operations have successfully completed and to handle errors.

For uploading and downloading operations, a SWF file can access files only within its own domain, including any domains that are specified by a cross-domain policy file. If the SWF that is initiating the upload or download doesn't come from the same domain as the file server, you must put a policy file on the file server.

While calls to the FileReference.browse(), FileReferenceList.browse(), or FileReference.download()methods are executing, SWF file playback pauses on the following platforms: Flash Players for Linux, the Flash Player plug-in for Mac OS X, the external Flash Player for Macintosh, and the stand-alone player for Mac OS X 10.1 and earlier. The SWF file continues to run in all players for Windows and in the stand-alone player for Macintosh on Mac OS X 10.2 and later.

Availability: ActionScript 1.0; Flash Player 8

Example

The following example creates a FileReference object that prompts the user to select an image or text file to be uploaded. It also listens for any possible event.

import flash.net.FileReference;

var allTypes:Array = new Array();
var imageTypes:Object = new Object();
imageTypes.description = "Images (*.jpg, *.jpeg, *.gif, *.png)";
imageTypes.extension = "*.jpg; *.jpeg; *.gif; *.png";
allTypes.push(imageTypes);

var textTypes:Object = new Object();
textTypes.description = "Text Files (*.txt, *.rtf)";
textTypes.extension = "*.txt;*.rtf";
allTypes.push(textTypes);

var listener:Object = new Object(); 

listener.onSelect = function(file:FileReference):Void {
    trace("onSelect: " + file.name);
    if(!file.upload("http://www.yourdomain.com/yourUploadHandlerScript.cfm")) {
        trace("Upload dialog failed to open.");
    }
}

listener.onCancel = function(file:FileReference):Void {
    trace("onCancel");
}

listener.onOpen = function(file:FileReference):Void {
    trace("onOpen: " + file.name);
}

listener.onProgress = function(file:FileReference, bytesLoaded:Number, bytesTotal:Number):Void {
    trace("onProgress with bytesLoaded: " + bytesLoaded + " bytesTotal: " + bytesTotal);
}

listener.onComplete = function(file:FileReference):Void {
    trace("onComplete: " + file.name);
}

listener.onHTTPError = function(file:FileReference):Void {
    trace("onHTTPError: " + file.name);
}

listener.onIOError = function(file:FileReference):Void {
    trace("onIOError: " + file.name);
}

listener.onSecurityError = function(file:FileReference, errorString:String):Void {
    trace("onSecurityError: " + file.name + " errorString: " + errorString);
}

var fileRef:FileReference = new FileReference();
fileRef.addListener(listener);
fileRef.browse(allTypes);

See also

FileReferenceList (flash.net.FileReferenceList)

Property summary

Properties inherited from class Object

Event summary

Constructor summary

Method summary

Methods inherited from class Object

Flash CS3