Flash CS3 Documentation

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

upload (FileReference.upload method)

Starts the upload of a file selected by a user to 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. 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 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.

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" by default 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-- 

To send POST parameters to the server, set the value of FileReference.postData to your parameters. You can send GET parameters to the server with the upload() call by appending parameters to the URL.

If the file to be uploaded is bigger than approximately 10 KB, Windows Flash Player versions first send a test upload POST with zero content prior to uploading the actual file in order to verify that the transmission is likely to be successful. The second POST contains an actual file content. For smaller files, Flash Player does a single upload POST with the file to be uploaded. The Macintosh players currently do not do test upload POSTs.

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:

• 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 server script configured to handle upload through HTTP POST calls. The URL can be HTTP or, for secure uploads, HTTPS.

uploadDataFieldName:String - The field name that precedes the file data in the upload POST. This parameter is supported in Flash Player 9.0.28.0 and later, only. The uploadDataFieldName value must be non-null and a non-empty String. By default, the value of uploadDataFieldName is "Filedata":

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

testUpload:Boolean - A setting to request a test file upload. If testUpload is true, then for files larger than 10 KB, Flash Player will attempt a test file upload POST with a Content-Length of 0. The purpose of the test upload is to check whether the actual file upload will be successful and whether server authentication, if required, will succeed. By default, testUpload is false. At this time, a test upload is done only for the Windows players.

You can send GET parameters 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 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; your SWF file attempts to access a file from a server that is outside your SWF file'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);

See also

browse (FileReference.browse method), browse (FileReferenceList.browse method), download (FileReference.download method), fileList (FileReferenceList.fileList property)

Flash CS3