flash.net

Class FileReference

Object

public class FileReference
extends Object

Player version:

Flash Player 8

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

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

Property Summary
	`creationDate : Date` [read-only] The creation date of the file on the local disk.
	`creator : String` [read-only] The Macintosh creator type of the file.
	`modificationDate : Date` [read-only] The date that the file on the local disk was last modified.
	`name : String` [read-only] The name of the file on the local disk.
	`size : Number` [read-only] The size of the file on the local disk, in bytes.
	`type : String` [read-only] The file type.

Properties inherited from class Object

__proto__, __resolve, constructor, prototype

Event Summary
	`onCancel = function(fileRef:FileReference) {}` Invoked when the user dismisses the file-browsing dialog box.
	`onComplete = function(fileRef:FileReference) {}` Invoked when the upload or download operation has successfully completed.
	`onHTTPError = function(fileRef:FileReference, httpError:Number) {}` Invoked when an upload fails because of an HTTP error.
	`onIOError = function(fileRef:FileReference) {}` Invoked when an input/output error occurs.
	`onOpen = function(fileRef:FileReference) {}` Invoked when an upload or download operation starts.
	`onProgress = function(fileRef:FileReference, bytesLoaded:Number, bytesTotal:Number) {}` Invoked periodically during the file upload or download operation.
	`onSecurityError = function(fileRef:FileReference, errorString:String) {}` Invoked when an upload or download fails because of a security error.
	`onSelect = function(fileRef:FileReference) {}` Invoked when the user selects a file to upload or download from the file-browsing dialog box.

Constructor Summary
	`FileReference()` Creates a new FileReference object.

Method Summary
	`addListener(listener:Object) : Void` Registers an object to receive notification when a FileReference event listener is invoked.
	`browse([typelist:Array]) : Boolean` Displays a file-browsing dialog box in which the user can select a local file to upload.
	`cancel() : Void` Cancels any ongoing upload or download operation on this FileReference object.
	`download(url:String, [defaultFileName:String]) : Boolean` Displays a dialog box in which the user can download a file from a remote server.
	`removeListener(listener:Object) : Boolean` Removes an object from the list of objects that receive event notification messages.
	`upload(url:String) : Boolean` Starts the upload of a file selected by a user to a remote server.

Methods inherited from class Object

addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch

Property Detail

creationDate Property

public creationDate : Date [read-only]

Player version:

Flash Player 8

The creation date of the file on the local disk. If the FileReference object has not been populated, a call to get the value of this property returns null.

Example
The following example retrieves the creation date of a file selected by the user.

import flash.net.FileReference;

var listener:Object = new Object();
listener.onSelect = function(file:FileReference):Void {
    trace("creationDate: " + file.creationDate);
}

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

See also

FileReference.browse()

creator Property

public creator : String [read-only]

Player version:

Flash Player 8

The Macintosh creator type of the file. In Windows, this property is null. If the FileReference object has not been populated, a call to get the value of this property returns null.

Example
The following example retrieves the Macintosh creator type of a file selected by the user.

import flash.net.FileReference;

var listener:Object = new Object();
listener.onSelect = function(file:FileReference):Void {
    trace("creator: " + file.creator);
}

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

See also

FileReference.browse()

modificationDate Property

public modificationDate : Date [read-only]

Player version:

Flash Player 8

The date that the file on the local disk was last modified. If the FileReference object has not been populated, a call to get the value of this property returns null.

Example
The following example retrieves the modificationDate of a file selected by the user.

import flash.net.FileReference;

var listener:Object = new Object();
listener.onSelect = function(file:FileReference):Void {
    trace("modificationDate: " + file.modificationDate);
}

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

See also

FileReference.browse()

name Property

public name : String [read-only]

Player version:

Flash Player 8

The name of the file on the local disk. If the FileReference object has not been populated, a call to get the value of this property returns null.

All the properties of a FileReference object are populated by calling browse(). Unlike other FileReference properties, if you call download(), the name property is populated when onSelect is invoked.

Example
The following example retrieves the name of a file selected by the user.

import flash.net.FileReference;

var listener:Object = new Object();
listener.onSelect = function(file:FileReference):Void {
    trace("name: " + file.name);
}

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

See also

FileReference.browse()

size Property

public size : Number [read-only]

Player version:

Flash Player 8

The size of the file on the local disk, in bytes. If the FileReference object has not been populated, a call to get the value of this property returns null.

Example
The following example retrieves the size of a file selected by the user.

import flash.net.FileReference;

var listener:Object = new Object();
listener.onSelect = function(file:FileReference):Void {
    trace("size: " + file.size + " bytes");
}

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

See also

FileReference.browse()

type Property

public type : String [read-only]

Player version:

Flash Player 8

The file type. In Windows, this property is the file extension. On the Macintosh, this property is the four-character file type. If the FileReference object has not been populated, a call to get the value of this property returns null.

Example
The following example retrieves the type of a file selected by the user.

import flash.net.FileReference;

var listener:Object = new Object();
listener.onSelect = function(file:FileReference):Void {
    trace("type: " + file.type);
}

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

See also

FileReference.browse()

Event Detail

onCancel Event Listener

public onCancel = function(fileRef:FileReference) {}

Player version:

Flash Player 8

Invoked when the user dismisses the file-browsing dialog box. This dialog box is displayed when you call FileReference.browse(), FileReferenceList.browse(), or FileReference.download().

Parameters

fileRef:FileReference — The FileReference object that initiated the operation.

Example
The following example traces a message if the user dismisses the file-browsing dialog box. This method is triggered only if the user clicks Cancel or presses the Escape key after the dialog box is displayed.

import flash.net.FileReference;

var listener:Object = new Object();

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

var fileRef:FileReference = new FileReference();
fileRef.addListener(listener);
var url:String = "http://www.macromedia.com/platform/whitepapers/platform_overview.pdf";
if(!fileRef.download(url, "FlashPlatform.pdf")) {
    trace("dialog box failed to open.");
}

onComplete Event Listener

public onComplete = function(fileRef:FileReference) {}

Player version:

Flash Player 8

Invoked when the upload or download operation has successfully completed. Successful completion means that the entire file has been uploaded or downloaded.

Parameters

fileRef:FileReference — The FileReference object that initiated the operation.

Example
The following example traces out a message when the onComplete event is triggered.

import flash.net.FileReference;

var listener:Object = new Object();

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

var fileRef:FileReference = new FileReference();
fileRef.addListener(listener);
var url:String = "http://www.macromedia.com/platform/whitepapers/platform_overview.pdf";
fileRef.download(url, "FlashPlatform.pdf");

onHTTPError Event Listener

public onHTTPError = function(fileRef:FileReference, httpError:Number) {}

Player version:

Flash Player 8

Invoked when an upload fails because of an HTTP error.

Because of the way that Flash Player relies on the browser stack during file download, this error is not applicable for download failures. If a download fails because of an HTTP error, the error is reported as an I/O error.

Parameters

	`fileRef:FileReference` — The File Reference object that initiated the operation.

	`httpError:Number` — The HTTP error that caused this upload to fail. For example, an `httpError` of 404 indicates that a page is not found. HTTP error values can be found in sections 10.4 and 10.5 of the HTTP specification at ftp://ftp.isi.edu/in-notes/rfc2616.txt.

Example
The following example creates a FileReference object with a listener for each possible event including onHttpError. This listener is triggered only if the upload fails because of an HTTP error.

import flash.net.FileReference;

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

onIOError Event Listener

public onIOError = function(fileRef:FileReference) {}

Player version:

Flash Player 8

Invoked when an input/output error occurs.

This listener is invoked when the upload or download fails for any of the following reasons:

An input/output error occurs while the player is reading, writing, or transmitting the file.
The SWF file tries to upload a file to a server that requires authentication, such as a user name and password. During upload, Flash Player does not provide a means for users to enter passwords. If a SWF file tries to upload a file to a server that requires authentication, the upload fails.
The SWF file tries to download a file from a server that requires authentication, in the stand-alone or external player. During download, the stand-alone and external players do not provide a means for users to enter passwords. If a SWF file in these players tries to download a file from a server that requires authentication, the download fails. File download can succeed only in the ActiveX control and browser plug-in players.
The value passed to the url parameter in upload() contains an invalid protocol. Valid protocols are HTTP and HTTPS.

Important: Only Flash applications that are running in a browser — that is, using the browser plug-in or ActiveX control — can provide a dialog to prompt the user to enter a user name and password for authentication, and then only for downloads. For uploads that use the plug-in or ActiveX control, or that upload and download using either the standalone or external players, the file transfer fails.

Parameters

fileRef:FileReference — The FileReference object that initiated the operation.

Example
The following example traces a message when the onIOError event is triggered. For simplicity, none of the other event listeners are included in this example.

import flash.net.FileReference;

var listener:Object = new Object();

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

var fileRef:FileReference = new FileReference();
fileRef.addListener(listener);
fileRef.download("http://www.macromedia.com/NonExistentFile.pdf", "NonExistentFile.pdf");

onOpen Event Listener

public onOpen = function(fileRef:FileReference) {}

Player version:

Flash Player 8

Invoked when an upload or download operation starts.

Parameters

fileRef:FileReference — The FileReference object that initiated the operation.

Example
The following example traces a message when the onOpen event is triggered.

import flash.net.FileReference;

var listener:Object = new Object();

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

var fileRef:FileReference = new FileReference();
fileRef.addListener(listener);
var url:String = "http://www.macromedia.com/platform/whitepapers/platform_overview.pdf";
fileRef.download(url, "FlashPlatform.pdf");

onProgress Event Listener

public onProgress = function(fileRef:FileReference, bytesLoaded:Number, bytesTotal:Number) {}

Player version:

Flash Player 8

Invoked periodically during the file upload or download operation. The onProgress listener is invoked while the Flash Player transmits bytes to a server, and it is periodically invoked during the transmission, even if the transmission is ultimately not successful. To determine if and when the file transmission is successful and complete, use onComplete.

In some cases, onProgress listeners are not invoked; for example, if the file being transmitted is very small, or if the upload or download happens very quickly.

File upload progress cannot be determined on Macintosh platforms earlier than OS X 10.3. The onProgress event is called during the upload operation, but the value of the bytesLoaded parameter is -1, indicating that the progress cannot be determined.

Parameters

	`fileRef:FileReference` — The FileReference object that initiated the operation.

	`bytesLoaded:Number` — The number of bytes transmitted so far.

	`bytesTotal:Number` — The total size of the file to be transmitted, in bytes. If the size cannot be determined, the value is -1.

Example
The following example traces the progress of a download using the onProgress event listener.

import flash.net.FileReference;

var listener:Object = new Object();

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

var fileRef:FileReference = new FileReference();
fileRef.addListener(listener);
var url:String = "http://www.macromedia.com/platform/whitepapers/platform_overview.pdf";
fileRef.download(url, "FlashPlatform.pdf");

See also

FileReference.onComplete

onSecurityError Event Listener

public onSecurityError = function(fileRef:FileReference, errorString:String) {}

Player version:

Flash Player 8

Invoked when an upload or download fails because of a security error. The calling SWF file may have tried to access a SWF file outside its domain and does not have permission to do so. You can try to remedy this error by using a cross-domain policy file.

Parameters

	`fileRef:FileReference` — The FileReference object that initiated the operation.

	`errorString:String` — Describes the error that caused `onSecurityError` to be called. The value is "securitySandboxError".

Example
The following example creates a FileReference object with a listener for each possible event, including onSecurityError. The onSecurityError listener is triggered only if the upload fails because of a security error.

import flash.net.FileReference;

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

onSelect Event Listener

public onSelect = function(fileRef:FileReference) {}

Player version:

Flash Player 8

Invoked when the user selects a file to upload or download from the file-browsing dialog box. (This dialog box is displayed when you call FileReference.browse(), FileReferenceList.browse(), or FileReference.download().) When the user selects a file and confirms the operation (for example, by clicking OK), the properties of the FileReference object are populated.

The onSelect listener works slightly differently depending on what method invokes it. When onSelect is invoked after a browse() call, Flash Player can read all of the FileReference object's properties, because the file selected by the user is on the local file system. When onSelect is invoked after a download() call, Flash Player can read only the name property, because the file hasn't yet been downloaded to the local file system at the moment onSelect is invoked. When the file has been downloaded and onComplete invoked, then Flash Player can read all other properties of the FileReference object.

Parameters

fileRef:FileReference — The FileReference object that initiated the operation.

Example
The following example traces a message within the onSelect event listener.

import flash.net.FileReference;

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

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

Constructor Detail

FileReference Constructor

public FileReference()

Player version:

Flash Player 8

Creates a new FileReference object. When populated, a FileReference object represents a file on the user's local disk.

Example
The following example creates a new FileReference object and initiates the download of a PDF file.

import flash.net.FileReference;

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

var url:String = "http://www.macromedia.com/platform/whitepapers/platform_overview.pdf";
var fileRef:FileReference = new FileReference();
fileRef.addListener(listener);
fileRef.download(url, "FlashPlatform.pdf");

See also

FileReference.browse()

Method Detail

addListener Method

public addListener(listener:Object) : Void

Player version:

Flash Player 8

Registers an object to receive notification when a FileReference event listener is invoked.

Parameters

listener:Object — An object that listens for a callback notification from the FileReference event listeners.

Example
The following example adds a listener to an instance of FileReference.

import flash.net.FileReference;

var listener:Object = new Object();

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

var fileRef:FileReference = new FileReference();
fileRef.addListener(listener);
var url:String = "http://www.macromedia.com/platform/whitepapers/platform_overview.pdf";
fileRef.download(url, "FlashPlatform.pdf");

browse Method

public browse([typelist:Array]) : Boolean

Player version:

Flash Player 8

Displays a file-browsing dialog box in which the user can select a local file to upload. The dialog box is native to the user's operating system. When you call this method and the user successfully selects a file, the properties of this FileReference object are populated with the properties of that file. Each subsequent time that FileReference.browse() is called, the FileReference object's properties are reset to the file selected by the user in the dialog box.

Only one browse() or download() session can be performed at a time (because only one dialog box can be displayed at a time).

You can pass an array of file types to determine which files the dialog box displays.

Parameters

typelist:Array [optional] — An array of file types used to filter the files displayed in the dialog box. If you omit this parameter, all files are displayed. If you include this parameter, the array must contain one or more elements enclosed in curly braces { }. You can use one of two formats for the array:

A list of file type descriptions followed by their Windows file extensions only.
Each element in the array must contain a string that describes the file type and a semicolon-delimited list of Windows file extensions, with a wildcard character (*) preceding each extension. The syntax for each element is as follows:
[{description: "string describing the first set of file types", extension: "semicolon-delimited list of file extensions"}]
Example:
[{description: "Images", extension: "*.jpg;*.gif;*.png"}, {description: "Flash Movies", extension: "*.swf"}, {description: "Documents", extension: "*.doc;*.pdf"}]
A list of file type descriptions followed by their Windows file extensions and their Macintosh file types.
Each element in the array must contain a string that describes the file type; a semicolon-delimited list of Windows file extensions, with a wildcard character (*) preceding each extension; and a semicolon-delimited list of Macintosh file types, with a wildcard character (*) preceding each type. The syntax for each element is as follows:
[{description: "string describing the first set of file types", extension: "semicolon-delimited list of Windows file extensions", macType: "semicolon-delimited list of Macintosh file types"}]
Example:
[{description: "Image files", extension: "*.jpg;*.gif;*.png", macType: "JPEG;jp2_;GIFF"}, {description: "Flash Movies", extension: "*.swf", macType: "SWFL"}]

The two formats are not interchangeable in a single browse() call. You must use one or the other.

The list of extensions is used to filter the files in Windows, depending on the file selected by the user. It is not actually displayed in the dialog box. To display the file types for users, you must list the file types in the description string as well as in the extension list. The description string is displayed in the dialog box in Windows. (It is not used on the Macintosh.) On the Macintosh, if you supply a list of Macintosh file types, that list is used to filter the files. If you don't supply a list of Macintosh file types, the list of Windows extensions is used.

Returns

Boolean — Returns true if the parameters are valid and the file-browsing dialog box is displayed. Returns false if the dialog box is not displayed, if another browse session is already in progress, or if you use the typelist parameter but fail to provide a description or extension string in any element in the array.

Example
The following example displays a dialog box in which the user can select an image file to be uploaded.

import flash.net.FileReference;

var listener:Object = new Object();
listener.onSelect = function(file:FileReference):Void  {
    trace("Opened " + file.name);
}

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

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

cancel Method

public cancel() : Void

Player version:

Flash Player 8

Cancels any ongoing upload or download operation on this FileReference object.

Example
The following example downloads approximately half of the requested file and then cancels the download. This is obviously not a typical usage. You might more often use this method to allow users to click Cancel in a download status dialog box.

import flash.net.FileReference;

var listener:Object = new Object();

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

var fileRef:FileReference = new FileReference();
fileRef.addListener(listener);
var url:String = "http://www.macromedia.com/platform/whitepapers/platform_overview.pdf";
fileRef.download(url, "FlashPlatform.pdf");

download Method

public download(url:String, [defaultFileName:String]) : Boolean

Player version:

Flash Player 8

Displays a dialog box in which the user can download a file from a remote server. Flash Player can download files of up to 100 MB.

This method first opens an operating-system dialog box that asks the user to enter a filename and select a location on the local computer to save the file. When the user selects a location and confirms the download operation (for example, by clicking Save), the download from the remote server begins. Listeners receive events to indicate the progress, success, or failure of the download. To ascertain the status of the dialog box and the download operation after calling download(), your ActionScript code must listen for events by using event listeners such as onCancel, onOpen, onProgress, and onComplete.

When the file has successfully downloaded, the properties of the FileReference object are populated with the properties of the local file and the onComplete listener is invoked.

Only one browse() or download() session can be performed at a time (because only one dialog box can be displayed at a time).

This method supports downloading of any file type, with either HTTP or HTTPS. You can also send data to the server with the download() call by appending parameters to the URL, for the server script to parse.

Note: If your server requires user authentication, only SWF files that are running in a browser—that is, using the browser plug-in or ActiveX control—can provide a dialog box to prompt the user for a user name and password for authentication, and only for downloads. For uploads using the plug-in or ActiveX control, and for uploads and downloads using the stand-alone or external player, the file transfer fails.

When using this method, consider the Flash Player security model:

Not allowed if the calling SWF file is in an untrusted local sandbox.
The default is to deny access between sandboxes. A website can enable access to a resource by adding a cross-domain policy file.

For more information, see the following:

"Understanding Security" in Learning ActionScript 2.0 in Flash
The Flash Player 8 Security white paper at http://www.macromedia.com/go/fp8_security
The Flash Player 8 Security-Related API white paper at http://www.macromedia.com/go/fp8_security_apis

Parameters

	`url:String` — The URL of the file to download to the local computer. You can send data to the server with the `download()` call by appending parameters to the URL, for the server script to parse. For example: `http://www.myserver.com/picture.jpg?userID=jdoe` On some browsers, URL strings are limited in length. Lengths greater than 256 characters may fail on some browsers or servers.

	`defaultFileName:String` [optional] — The default filename displayed in the dialog box, for the file to be downloaded. This string cannot contain the following characters: / \ : * ? " < > \| % If you omit this parameter, the filename of the remote URL is parsed out and used as the default.

Returns

Boolean — A value of true if the dialog box in which a user can select a file is displayed. If the dialog box is not displayed, the method returns false. The dialog box could fail to be displayed for any of the following reasons:

You did not pass a value for the url parameter.
The parameters passed are of the incorrect type or format.
The url parameter has a length of 0.
A security violation occurred; that is, your SWF file attempted to access a file from a server that is outside your SWF file's security sandbox.
Another browse session is already in progress. A browse session can be started by FileReference.browse(), FileReferenceList.browse(), or FileReference.download().
The protocol is not HTTP or HTTPS.

Example
The following example attempts to download a file using the download method. Notice that there are listeners for all of the events.

import flash.net.FileReference;

var listener:Object = new Object();

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

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.onIOError = function(file:FileReference):Void {
    trace("onIOError: " + file.name);
}

var fileRef:FileReference = new FileReference();
fileRef.addListener(listener);
var url:String = "http://www.macromedia.com/platform/whitepapers/platform_overview.pdf";
if(!fileRef.download(url, "FlashPlatform.pdf")) {
    trace("dialog box failed to open.");
}

removeListener Method

public removeListener(listener:Object) : Boolean

Player version:

Flash Player 8

Removes an object from the list of objects that receive event notification messages.

Parameters

listener:Object — An object that listens for a callback notification from the FileReference event listeners.

Returns

Boolean — Returns true if the object specified in the listener parameter was successfully removed. Otherwise, this method returns false.

Example
The following example removes an event listener using the removeListener method. If a user cancels the download, the listener is removed so that it no longer receives events from that FileReference object.

import flash.net.FileReference;

var listener:Object = new Object();

listener.onCancel = function(file:FileReference):Void {
    trace(file.removeListener(this)); // true
}

var fileRef:FileReference = new FileReference();
fileRef.addListener(listener);
var url:String = "http://www.macromedia.com/platform/whitepapers/platform_overview.pdf";
fileRef.download(url, "FlashPlatform.pdf");

upload Method

public upload(url:String) : Boolean

Player version:

Flash Player 8

Starts the upload of a file selected by a user to a remote server. Flash Player can upload files of up to 100 MB. You must call FileReference.browse() or FileReferenceList.browse() before calling this method.

Listeners receive events to indicate the progress, success, or failure of the upload. Although you can use the FileReferenceList object to let users select multiple files to upload, you must upload the files one by one. To do so, iterate through the FileReferenceList.fileList array of FileReference objects.

The file is uploaded to the URL passed in the url parameter. The URL must be a server script configured to accept uploads. Flash Player uploads files using the HTTP POST method. The server script that handles the upload should expect a POST request with the following elements:

A Content-Type element of multipart/form-data
A Content-Disposition element with a name attribute set to "Filedata" and a filename attribute set to the name of the original file
The binary contents of the file

Here is a sample POST request:

     Content-Type: multipart/form-data; boundary=AaB03x
     --AaB03x 
     Content-Disposition: form-data; name="Filedata"; filename="example.jpg" 
     Content-Type: application/octet-stream
     ... contents of example.jpg ... 
     --AaB03x--

You can send data to the server with the upload() call by appending parameters to the URL.

Note: If your server requires user authentication, only SWF files running in a browser—that is, using the browser plug-in or ActiveX control—can provide a dialog box to prompt the user for a user name and password for authentication, and only for downloads. For uploads that use the plug-in or ActiveX control, and for uploads and downloads that use the stand-alone or external player, the file transfer fails.

When using this method, consider the Flash Player security model:

Not allowed if the calling SWF file is in an untrusted local sandbox.
The default is to deny access between sandboxes. A website can enable access to a resource by adding a cross-domain policy file.

For more information, see the following:

"Understanding Security" in Learning ActionScript 2.0 in Flash
The Flash Player 8 Security white paper at http://www.macromedia.com/go/fp8_security
The Flash Player 8 Security-Related API white paper at http://www.macromedia.com/go/fp8_security_apis

Parameters

url:String — The URL of the server script configured to handle upload through HTTP POST calls. The URL can be HTTP or, for secure uploads, HTTPS.

You can send data to the server with the upload() call by appending parameters to the URL; for example, http://www.myserver.com/upload.cgi?userID=jdoe

On some browsers, URL strings are limited in length. Lengths greater than 256 characters may fail on some browsers or servers.

Returns

Boolean — A value of false in any of the following situations:

FileReference.browse() has not yet been successfully called on this object, or if FileReferenceList.browse() has not yet been successfully called with this object in its filelist array.
The protocol is not HTTP or HTTPS.
A security violation occurs; that is, if your SWF file attempts to access a file from a server that is outside your SWF files's security sandbox.
The url parameter is of the incorrect type or format.
The call does not have the correct number of parameters.

Example
The following example shows an implementation of the upload() method by first prompting the user to select a file to upload, then handling the onSelect and onCancel listeners, and finally handling the results of the actual file upload.

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

Properties | Events | Methods

Flash 8 ActionScript 2.0 Language Reference

Class FileReference

creationDate Property

creator Property

modificationDate Property

name Property

size Property

type Property

onCancel Event Listener

onComplete Event Listener

onHTTPError Event Listener

onIOError Event Listener

onOpen Event Listener

onProgress Event Listener

onSecurityError Event Listener

onSelect Event Listener

FileReference Constructor

addListener Method

browse Method

cancel Method

download Method

removeListener Method

upload Method