Flash CS3 Documentation

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

download (FileReference.download method)

Displays a dialog box in which the user can download a file from a remote server. Although Flash Player has no restriction on the size of files you can upload or download, the player officially supports uploads or downloads 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.

The FileReference.upload() and FileReference.download() functions are nonblocking. These functions return after they are called, before the file transmission is complete. In addition, if the FileReference object goes out of scope, any upload or download that has not yet been completed on that object is cancelled upon leaving the scope. So, be sure that your FileReference object will remain in scope for as long as the upload or download could be expected to continue.

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.

To send POST parameters to the server, set the value of FileReference.postData to your parameters. You can also send GET parameters 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:

• This method is not allowed if the calling SWF file is in an untrusted local sandbox.
• The default security setting denies 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 9 Security white paper at http://www.adobe.com/go/fp9_0_security
• The Flash Player 8 Security-Related API white paper at http://www.adobe.com/go/fp8_security_apis

Availability: ActionScript 1.0; Flash Player 8

Parameters

url:String - The URL of the file to download to the local computer. You can send GET parameters 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; 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.adobe.com/platform/whitepapers/platform_overview.pdf";
if(!fileRef.download(url, "FlashPlatform.pdf")) {
    trace("dialog box failed to open.");
}

See also

browse (FileReference.browse method), browse (FileReferenceList.browse method), upload (FileReference.upload method)

Flash CS3