Flash 8 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. 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

Availability: ActionScript 1.0; Flash Player 8

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

See also

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

Version 8

Comments

Add Comment

shimi2 said on Sep 21, 2005 at 5:00 PM :

The FileReference.upload() and FileReference.download() functions are non-blocking. 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.

timdiacon said on Jan 16, 2006 at 2:07 AM :

Can the download function not be set up to download files from non http:// locations?

When creating projectors or sites which you want to run from a cd it would be very useful to be able to download files to the users computer from the disc. However as far as I am aware this is not currently possible.

shimi2 said on Feb 1, 2006 at 11:50 AM :

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

pickle jar said on Apr 3, 2006 at 8:47 AM :

Is there any function to cancel the download after it has started?

Cameron74 said on Jul 14, 2006 at 11:12 AM :

The previous post seems to be only a problem in Firefox 1.5 on windows XP. It works fine in I.E.

No screen name said on Apr 22, 2007 at 6:09 PM :

Hi, I understand that the file refercene has it's own scope but how to I
define this or add to it? Is there a way to download more than one file at
once?

cayennecode said on Jun 22, 2007 at 11:39 PM :

What about bypassing the dialog box, as traditional html download links do?
Automatically start the download to the users default download location.

Example: http://www.adobe.com/products/flashplayer/

stop w/the nickname said on Jul 18, 2007 at 8:07 AM :

I have followed the code in the example exactly , and after selecting, the onSelect event fires, but the file never downloads. the whole process just stops.......... IE with flash 8, Firefox 2 with flash 9....... please help.. anyone else run into issues?

No screen name said on Jan 21, 2009 at 11:13 AM :

i'm trying to call fileRef.download() after a sendAndLoad has executed and the target object has received all the variables from the script. So I have a loadvarsObj.onLoad function that calls the fileRef.download() method. However, the prompt does not show up and it returns a false. it works if i call it right after the sendAndLoad, but i want to wait for the send and load script to finish to call fileRef.download() and it seems when I do that, fileRef.download() fails. Any help?

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flash/8/main/00002210.html

Add Comment