ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
FileReference

Package | flash.net
Class | public class FileReference
Inheritance | FileReference EventDispatcher Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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 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 the `FileReferenceList.browse()` method, which creates an array of FileReference objects.

During an upload operation, all the properties of a FileReference object are populated by calls to the `FileReference.browse()` or `FileReferenceList.browse()` methods. During a download operation, the `name` property is populated when the `select` event is dispatched; all other properties are populated when the `complete` event is dispatched.

The `browse()` method opens an operating-system dialog box that prompts the user to select a 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 that the `browse()` or `download()` methods generate. 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. Listen for FileReference events to determine whether operations complete successfully and to handle errors.

For content running in Adobe AIR outside of the application security sandbox, uploading and downloading operations can access files only within its own domain and within any domains that a URL policy file specifies. Put a policy file on the file server if the content initiating the upload or download doesn't come from the same domain as the file server.

The following sample HTTP `POST` request is sent from Flash Player to a server-side script if no parameters are specified:

      POST /handler.cfm HTTP/1.1
      Accept: text/*
      Content-Type: multipart/form-data;
      boundary=----------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
      User-Agent: Shockwave Flash
      Host: www.example.com
      Content-Length: 421
      Connection: Keep-Alive
      Cache-Control: no-cache

      ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
      Content-Disposition: form-data; name="Filename"

      MyFile.jpg
      ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
      Content-Disposition: form-data; name="photo"; filename="MyFile.jpg"
      Content-Type: application/octet-stream

      FileDataHere
      ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
      Content-Disposition: form-data; name="Upload"

      Submit Query
      ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7--

Flash Player sends the following HTTP `POST` request if the user specifies the parameters `"api_sig"`, `"api_key"`, and `"auth_token"`:

      POST /handler.cfm HTTP/1.1
      Accept: text/*
      Content-Type: multipart/form-data;
      boundary=----------Ij5ae0ae0KM7GI3KM7ei4cH2ei4gL6
      User-Agent: Shockwave Flash
      Host: www.example.com
      Content-Length: 421
      Connection: Keep-Alive
      Cache-Control: no-cache

      ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
      Content-Disposition: form-data; name="Filename"

      MyFile.jpg
      ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
      Content-Disposition: form-data; name="api_sig"

      XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
      ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
      Content-Disposition: form-data; name="api_key"

      XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
      ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
      Content-Disposition: form-data; name="auth_token"

      XXXXXXXXXXXXXXXXXXXXXX
      ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
      Content-Disposition: form-data; name="photo"; filename="MyFile.jpg"
      Content-Type: application/octet-stream

      FileDataHere
      ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7
      Content-Disposition: form-data; name="Upload"

      Submit Query
      ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7--

View the examples

See also

FileReferenceList
Working with file upload and download

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | creationDate : Date [read-only] The creation date of the file on the local disk. | FileReference
|  | creator : String [read-only] The Macintosh creator type of the file. | FileReference
|  | data : ByteArray [read-only] The ByteArray representing the loaded file after a successful call to load(). | FileReference
|  | modificationDate : Date [read-only] The date that the file on the local disk was last modified. | FileReference
|  | name : String [read-only] The name of the file on the local disk. | FileReference
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object
|  | size : uint [read-only] The size of the file on the local disk in bytes. | FileReference
|  | type : String [read-only] The file type. | FileReference

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | FileReference() Creates a new FileReference object. | FileReference
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | EventDispatcher
|  | browse(typeFilter:Array = null):Boolean Displays a file-browsing dialog box that lets the user select a file to upload. | FileReference
|  | cancel():void Cancels any ongoing upload or download operation on this FileReference object. | FileReference
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | download(request:URLRequest, defaultFileName:String = null):void Opens a dialog box that lets the user download a file from a remote server. | FileReference
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | load():void Starts the load of a local file selected by a user. | FileReference
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | save(data:*, defaultFileName:String = null):void Opens a dialog box that lets the user save a file to the local filesystem. | FileReference
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | upload(request:URLRequest, uploadDataFieldName:String = "Filedata", testUpload:Boolean = false):void Starts the upload of a file selected by a user to a remote server. | FileReference
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | Dispatched when Flash Player gains operating system focus and becomes active. | EventDispatcher
|  | cancel | Dispatched when a file upload or download is canceled through the file-browsing dialog box by the user. | FileReference
|  | complete | Dispatched when download is complete or when upload generates an HTTP status code of 200. | FileReference
|  | deactivate | Dispatched when Flash Player loses operating system focus and is becoming inactive. | EventDispatcher
|  | httpStatus | Dispatched when an upload fails and an HTTP status code is available to describe the failure. | FileReference
|  | ioError | Dispatched when the upload or download fails. | FileReference
|  | open | Dispatched when an upload or download operation starts. | FileReference
|  | progress | Dispatched periodically during the file upload or download operation. | FileReference
|  | securityError | Dispatched when a call to the FileReference.upload() or FileReference.download() method tries to upload a file to a server or get a file from a server that is outside the caller's security sandbox. | FileReference
|  | select | Dispatched when the user selects a file for upload or download from the file-browsing dialog box. | FileReference
|  | uploadCompleteData | Dispatched after data is received from the server after a successful upload. | FileReference

Property Detail

creationDate | property

`creationDate:Date` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

Implementation
`public function get creationDate():Date`
Throws

| `IllegalOperationError` — If the `FileReference.browse()`, `FileReferenceList.browse()`, or `FileReference.download()` method was not called successfully, an exception is thrown with a message indicating that functions were called in the incorrect sequence or an earlier call was unsuccessful. In this case, the value of the `creationDate` property is `null`.
| `IOError` — If the file information cannot be accessed, an exception is thrown with a message indicating a file I/O error.

See also

FileReference.browse()

creator | property |

`creator:String` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

Implementation
`public function get creator():String`
Throws

| `IllegalOperationError` — On Macintosh, if the `FileReference.browse()`, `FileReferenceList.browse()`, or `FileReference.download()` method was not called successfully, an exception is thrown with a message indicating that functions were called in the incorrect sequence or an earlier call was unsuccessful. In this case, the value of the `creator` property is `null`.

See also

FileReference.browse()
Working with file upload and download

data | property |

`data:ByteArray` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The ByteArray representing the loaded file after a successful call to `load()`.

Implementation
`flash10 function get data():ByteArray`
Throws

| `IllegalOperationError` — If the `FileReference.load()` method was not called successfully, an exception is thrown with a message indicating that functions were called in the incorrect sequence or an earlier call was unsuccessful. In this case, the value of the `data` property is `null`.
| `IOError` — If the file cannot be opened or read, or if a similar error is encountered in accessing the file, an exception is thrown with a message indicating a file I/O error. In this case, the value of the `data` property is `null`.

See also

FileReference.browse()
FileReference.load()

modificationDate | property |

`modificationDate:Date` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

Implementation
`public function get modificationDate():Date`
Throws

| `IllegalOperationError` — If the `FileReference.browse()`, `FileReferenceList.browse()`, or `FileReference.download()` method was not called successfully, an exception is thrown with a message indicating that functions were called in the incorrect sequence or an earlier call was unsuccessful. In this case, the value of the `modificationDate` property is `null`.
| `IOError` — If the file information cannot be accessed, an exception is thrown with a message indicating a file I/O error.

See also

FileReference.browse()

name | property |

`name:String` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The name of the file on the local disk. If the FileReference object was not populated (by a valid call to `FileReference.download()` or `FileReference.browse()`), Flash Player throws an error when you try to get the value of this property.

All the properties of a FileReference object are populated by calling the `browse()` method. Unlike other FileReference properties, if you call the `download()` method, the `name` property is populated when the `select` event is dispatched.

Implementation
`public function get name():String`
Throws

| `IllegalOperationError` — If the `FileReference.browse()`, `FileReferenceList.browse()`, or `FileReference.download()` method was not called successfully, an exception is thrown with a message indicating that functions were called in the incorrect sequence or an earlier call was unsuccessful.

See also

FileReference.browse()

size | property |

`size:uint` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The size of the file on the local disk in bytes. If `size` is 0, an exception is thrown.

Implementation
`public function get size():uint`
Throws

| `IllegalOperationError` — If the `FileReference.browse()`, `FileReferenceList.browse()`, or `FileReference.download()` method was not called successfully, an exception is thrown with a message indicating that functions were called in the incorrect sequence or an earlier call was unsuccessful. In this case, the value of the `size` property is 0.
| `IOError` — If the file cannot be opened or read, or if a similar error is encountered in accessing the file, an exception is thrown with a message indicating a file I/O error. In this case, the value of the `size` property is `0`.

See also

FileReference.browse()

type | property |

`type:String` [read-only]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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 was not populated, a call to get the value of this property returns `null`.

Implementation
`public function get type():String`
Throws

| `IllegalOperationError` — If the `FileReference.browse()`, `FileReferenceList.browse()`, or `FileReference.download()` method was not called successfully, an exception is thrown with a message indicating that functions were called in the incorrect sequence or an earlier call was unsuccessful. In this case, the value of the `type` property is `null`.

Constructor Detail

FileReference | () | Constructor

`public function FileReference()`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

See also

FileReference.browse()
Method Detail

browse | () | method

`public function browse(typeFilter:Array = null):Boolean`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Displays a file-browsing dialog box that lets the user select a file to upload. The dialog box is native to the user's operating system. The user can select a file on the local computer or from other systems, for example, through a UNC path on Windows.

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 the `FileReference.browse()` method is called, the FileReference object's properties are reset to the file that the user selects in the dialog box. Only one `browse()` or `download()` session can be performed at a time (because only one dialog box can be invoked at a time).

Using the `typeFilter` parameter, you can determine which files the dialog box displays.

Parameters

| `typeFilter:Array` (default = `null`)`` — An array of FileFilter instances used to filter the files that are displayed in the dialog box. If you omit this parameter, all files are displayed. For more information, see the FileFilter class.

Returns

| `Boolean` — Returns `true` if the parameters are valid and the file-browsing dialog box opens. The `browse` method returns `false` if the dialog box does not open, 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.

Events

| `select:`Event`` — Dispatched when the user successfully selects an item from the Browse file chooser.
| `cancel:`Event`` — Dispatched when the user cancels the file upload Browse window.

Throws

| `IllegalOperationError` — Thrown in the following situations: 1) Another FileReference or FileReferenceList browse session is in progress; only one file browsing session may be performed at a time. 2) A setting in the user's mms.cfg file prohibits this operation.
| `ArgumentError` — If the `typeFilter` array contains FileFilter objects that are incorrectly formatted, an exception is thrown. For information on the correct format for FileFilter objects, see the FileFilter class.

See also

select event
cancel event
FileReference.download()
FileReferenceList.browse()
Working with file upload and download

cancel | () | method |

`public function cancel():void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Cancels any ongoing upload or download operation on this FileReference object. Calling this method does not dispatch the `cancel` event; that event is dispatched only when the user cancels the operation by dismissing the file upload or download dialog box.

download | () | method |

`public function download(request:URLRequest, defaultFileName:String = null):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Opens a dialog box that lets the user 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.

The `download()` 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 such as `cancel`, `open`, `progress`, and `complete`.

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 is not yet completed on that object is canceled upon leaving the scope. Be sure that your FileReference object remains in scope for as long as the upload or download is expected to continue.

When the file is downloaded successfully, the properties of the FileReference object are populated with the properties of the local file. The `complete` event is dispatched if the download is successful.

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

This method supports downloading of any file type, with either HTTP or HTTPS.

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 using the plug-in or ActiveX control, or for uploads and downloads using the stand-alone or external player, the file transfer fails.

When you use this method , consider the security model:

- Loading operations are not allowed if the calling SWF file is in an untrusted local sandbox.
- The default behavior is to deny access between sandboxes. A website can enable access to a resource by adding a URL policy file.

However, content in the `application` security sandbox (content installed with the AIR application) is not restricted by these security limitations.

For more information related to security, see the following:

- The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs
- The "Understanding AIR Security" section of the "Getting started with Adobe AIR" chapter in the Developing AIR Applications book.
- The Flash Player Developer Center Topic: Security

Parameters

| `request:URLRequest` — The URLRequest object. The `url` property of the URLRequest object should contain the URL of the file to download to the local computer. If this parameter is `null`, an exception is thrown. To send `POST` or GET parameters to the server, set the value of `URLRequest.data` to your parameters, and set `URLRequest.method` to either `URLRequestMethod.POST` or `URLRequestMethod.GET`. On some browsers, URL strings are limited in length. Lengths greater than 256 characters may fail on some browsers or servers.
| `defaultFileName:String` (default = `null`)`` — The default filename displayed in the dialog box for the file to be downloaded. This string must not contain the following characters: / \ : * ? " < > | % If you omit this parameter, the filename of the remote URL is parsed and used as the default.

Events

| `open:`Event`` — Dispatched when a download operation starts.
| `progress:`ProgressEvent`` — Dispatched periodically during the file download operation.
| `complete:`Event`` — Dispatched when the file download operation successfully completes.
| `cancel:`Event`` — Dispatched when the user dismisses the dialog box.
| `select:`Event`` — Dispatched when the user selects a file for download from the dialog box.
| `securityError:`SecurityErrorEvent`` — Dispatched when a download fails because of a security error.
| `ioError:`IOErrorEvent`` — Dispatched for any of the following reasons: An input/output error occurs while the file is being read or transmitted. The SWF file tries to download a file from a server that requires authentication, within the standalone or external player. During download, the standalone 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.

Throws

| `IllegalOperationError` — Thrown in the following situations: 1) Another browse session is in progress; only one file browsing session can be performed at a time. 2) The value passed to `request` does not contain a valid path or protocol. 3) The filename to download contains prohibited characters. 4) A setting in the user's mms.cfg file prohibits this operation.
| `SecurityError` — Local untrusted SWF files may not communicate with the Internet. To avoid this situation, reclassify this SWF file as local-with-networking or trusted. This exception is thrown with a message indicating the filename and the URL that may not be accessed because of local file security restrictions.
| `ArgumentError` — If `url.data` is of type ByteArray, an exception is thrown. For use with the `FileReference.upload()` and `FileReference.download()` methods, `url.data` can only be of type URLVariables or String.
| `MemoryError` — This error can occur for the following reasons: 1) Flash Player cannot convert the `URLRequest.data` parameter from UTF8 to MBCS. This error is applicable if the URLRequest object passed to the `FileReference.download()` method is set to perform a GET operation and if `System.useCodePage` is set to `true`. 2) Flash Player cannot allocate memory for the `POST` data. This error is applicable if the URLRequest object passed to the `FileReference.download()` method is set to perform a `POST` operation.

See also

FileReference.browse()
FileReferenceList.browse()
FileReference.upload()
FileReference.save()
Working with file upload and download
Flash Player security
Example
The following example shows usage of the `download` event object. To run this example, change the `downloadURL.url` property to point to an actual domain and file, rather than the fictional http://www.[yourDomain].com/SomeFile.pdf. You might also need to compile the SWF file with Local playback security set to Access network only or to update Flash Player security settings to allow this file network access.

    package {
        import flash.display.Sprite;
        import flash.events.*;
        import flash.net.FileReference;
        import flash.net.URLRequest;
        import flash.net.FileFilter;

        public class FileReference_download extends Sprite {
            private var downloadURL:URLRequest;
            private var fileName:String = "SomeFile.pdf";
            private var file:FileReference;

            public function FileReference_download() {
                downloadURL = new URLRequest();
                downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
                file = new FileReference();
                configureListeners(file);
                file.download(downloadURL, fileName);
            }

            private function configureListeners(dispatcher:IEventDispatcher):void {
                dispatcher.addEventListener(Event.CANCEL, cancelHandler);
                dispatcher.addEventListener(Event.COMPLETE, completeHandler);
                dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
                dispatcher.addEventListener(Event.OPEN, openHandler);
                dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
                dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
                dispatcher.addEventListener(Event.SELECT, selectHandler);
            }

            private function cancelHandler(event:Event):void {
                trace("cancelHandler: " + event);
            }

            private function completeHandler(event:Event):void {
                trace("completeHandler: " + event);
            }

            private function ioErrorHandler(event:IOErrorEvent):void {
                trace("ioErrorHandler: " + event);
            }

            private function openHandler(event:Event):void {
                trace("openHandler: " + event);
            }

            private function progressHandler(event:ProgressEvent):void {
                var file:FileReference = FileReference(event.target);
                trace("progressHandler name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
            }

            private function securityErrorHandler(event:SecurityErrorEvent):void {
                trace("securityErrorHandler: " + event);
            }

            private function selectHandler(event:Event):void {
                var file:FileReference = FileReference(event.target);
                trace("selectHandler: name=" + file.name + " URL=" + downloadURL.url);
            }
        }
    }

load | () | method |

`flash10 function load():void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Starts the load of a local file selected by a user. Although Flash Player has no restriction on the size of files you can upload, download, load or save, the player officially supports sizes of up to 100 MB. You must call the `FileReference.browse()` or `FileReferenceList.browse()` method before you call this method.

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

The `FileReference.upload()`, `FileReference.download()`, `FileReference.load()` and `FileReference.save()` 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 transaction that is not yet completed on that object is canceled upon leaving the scope. Be sure that your FileReference object remains in scope for as long as the upload, download, load or save is expected to continue.

If the file finishes loading successfully, its contents are available with the `data` property.

- Loading operations are not allowed if the calling SWF file is in an untrusted local sandbox.
- The default behavior is to deny access between sandboxes. A website can enable access to a resource by adding a URL policy file.
- You can prevent a SWF file from using this method by setting the `allowNetworking` parameter of the the `object` and `embed` tags in the HTML page that contains the SWF content.

Events

| `open:`Event`` — Dispatched when an load operation starts.
| `progress:`ProgressEvent`` — Dispatched periodically during the file load operation.
| `complete:`Event`` — Dispatched when the file load operation completes successfully.
| `ioError:`IOErrorEvent`` — Invoked if the load fails because of an input/output error while Flash Player is reading or writing the file.

Throws

| `IllegalOperationError` — Thrown in the following situations: 1) Another FileReference or FileReferenceList browse session is in progress; only one file browsing session may be performed at a time. 2) A setting in the user's mms.cfg file prohibits this operation.
| `MemoryError` — This error can occur if Flash Player cannot allocate memory for the file. The file may be too large or available memory may be too low.

See also

FileReference.browse()
FileReferenceList.browse()
FileReference.data()
FileReferenceList.fileList
FileReference.save()

save | () | method |

`flash10 function save(data:*, defaultFileName:String = null):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Opens a dialog box that lets the user save a file to the local filesystem. Although Flash Player has no restriction on the size of files you can upload, download, load or save, the player officially supports sizes of up to 100 MB.

The `save()` 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 save operation (for example, by clicking Save), the save process begins. Listeners receive events to indicate the progress, success, or failure of the save operation. To ascertain the status of the dialog box and the save operation after calling `save()`, your ActionScript code must listen for events such as `cancel`, `open`, `progress`, and `complete`.

The `FileReference.upload()`, `FileReference.download()`, `FileReference.load()` and `FileReference.save()` 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 transaction that is not yet completed on that object is canceled upon leaving the scope. Be sure that your FileReference object remains in scope for as long as the upload, download, load or save is expected to continue.

When the file is saved successfully, the properties of the FileReference object are populated with the properties of the local file. The `complete` event is dispatched if the save is successful.

Only one `browse()` or `save()` session can be performed at a time (because only one dialog box can be invoked at a time).

Parameters

| `data:*` — The data to be saved. The data can be in one of several formats, and will be treated appropriately: If this parameter is `null`, an exception is thrown. If this parameter is a `String`, it is saved as a UTF-8 text file. If this parameter is `XML`, it is written to a file in XML format, with all formatting preserved. If this parameter is a `ByteArray`, it is written to a data file verbatim. If this parameter is none of the above, `save()` will call `toString()` on it, and if that fails, an exception is thrown.
| `defaultFileName:String` (default = `null`)`` — The default filename displayed in the dialog box for the file to be saved. This string must not contain the following characters: / \ : * ? " < > | % If you omit this parameter, the filename will be blank by default.

Events

| `open:`Event`` — Dispatched when a download operation starts.
| `progress:`ProgressEvent`` — Dispatched periodically during the file download operation.
| `complete:`Event`` — Dispatched when the file download operation successfully completes.
| `cancel:`Event`` — Dispatched when the user dismisses the dialog box.
| `select:`Event`` — Dispatched when the user selects a file for download from the dialog box.
| `ioError:`IOErrorEvent`` — Dispatched if an input/output error occurs while the file is being read or transmitted.

Throws

| `IllegalOperationError` — Thrown in the following situations: 1) Another browse session is in progress; only one file browsing session can be performed at a time. 2) The filename to download contains prohibited characters. 3) A setting in the user's mms.cfg file prohibits this operation.
| `ArgumentError` — If `data` is not of type ByteArray, and it does not have a `toString()` method, an exception is thrown. If `data` is not of type XML, and it does not have a `toXMLString()` method, an exception is thrown.
| `MemoryError` — This error can occur if Flash Player cannot allocate memory for the file. The file may be too large or available memory may be too low.

See also

FileReferenceList.browse()
FileReferenceList.load()
FileReferenceList.data
FileReferenceList.upload
FileReferenceList.download

upload | () | method |

`public function upload(request:URLRequest, uploadDataFieldName:String = "Filedata", testUpload:Boolean = false):void`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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 the `FileReference.browse()` or `FileReferenceList.browse()` method before you call 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 for 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 is not yet completed on that object is canceled upon leaving the scope. Be sure that your FileReference object remains in scope for as long as the upload or download is 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 by using the HTTP `POST` method. The server script that handles the upload should expect a `POST` request with the following elements:

- `Content-Type` of `multipart/form-data`
- `Content-Disposition` 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

For a sample `POST` request, see the description of the `uploadDataFieldName` parameter. You can send `POST` or `GET` parameters to the server with the `upload()` method; see the description of the `request` parameter.

If the `testUpload` parameter is `true`, and the file to be uploaded is bigger than approximately 10 KB, Flash Player on Windows first sends a test upload `POST` operation with zero content before uploading the actual file, to verify that the transmission is likely to succeed. Flash Player then sends a second `POST` operation that contains the actual file content. For files smaller than 10 KB, Flash Player performs a single upload `POST` with the actual file content to be uploaded. Flash Player on Macintosh does not perform test upload `POST` operations.

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 username and password for authentication, and only for downloads. For uploads using the plug-in or ActiveX control, or for uploads and downloads using the stand-alone or external player, the file transfer fails.

When you use this method , consider the security model:

- Loading operations are not allowed if the calling SWF file is in an untrusted local sandbox.
- The default behavior is to deny access between sandboxes. A website can enable access to a resource by adding a URL policy file.
- You can prevent a SWF file from using this method by setting the `allowNetworking` parameter of the the `object` and `embed` tags in the HTML page that contains the SWF content.

However, in Adobe AIR, content in the `application` security sandbox (content installed with the AIR application) are not restricted by these security limitations.

For more information related to security, see the following:

- The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs
- The "Understanding AIR Security" section of the "Getting started with Adobe AIR" chapter in the Developing AIR Applications book.
- The Flash Player Developer Center Topic: Security

Parameters

| `request:URLRequest` — The URLRequest object; the `url` property of the URLRequest object should contain the URL of the server script configured to handle upload through HTTP `POST` calls. On some browsers, URL strings are limited in length. Lengths greater than 256 characters may fail on some browsers or servers. If this parameter is `null`, an exception is thrown. The URL can be HTTP or, for secure uploads, HTTPS. To use HTTPS, use an HTTPS url in the `url` parameter. If you do not specify a port number in the `url` parameter, Flash Player uses port 80 for HTTP and port 443 for HTTPS, by default. To send `POST` or `GET` parameters to the server, set the `data` property of the URLRequest object to your parameters, and set the `method` property to either `URLRequestMethod.POST` or `URLRequestMethod.GET`.
| `uploadDataFieldName:String` (default = "`Filedata`")`` — The field name that precedes the file data in the upload `POST` operation. The `uploadDataFieldName` value must be non-null and a non-empty String. By default, the value of `uploadDataFieldName` is `"Filedata"`, as shown in the following 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--
| `testUpload:Boolean` (default = `false`)`` — A setting to request a test file upload. If `testUpload` is `true`, for files larger than 10 KB, Flash Player attempts a test file upload `POST` with a Content-Length of 0. The test upload checks whether the actual file upload will be successful and that server authentication, if required, will succeed. A test upload is only available for Windows players.

Events

| `open:`Event`` — Dispatched when an upload operation starts.
| `progress:`ProgressEvent`` — Dispatched periodically during the file upload operation.
| `complete:`Event`` — Dispatched when the file upload operation completes successfully.
| `uploadCompleteData:`Event`` — Dispatched when data has been received from the server after a successful file upload.
| `securityError:`SecurityErrorEvent`` — Dispatched when an upload fails because of a security violation.
| `httpStatus:`HTTPStatusEvent`` — Dispatched when an upload fails because of an HTTP error.
| `ioError:`IOErrorEvent`` — Invoked in any of the following situations: The upload fails because of an input/output error while Flash Player or Adobe AIR is reading, writing, or transmitting the file. The upload fails because an attempt to upload a file to a server that requires authentication (such as a user name and password). During upload, no means are provided for users to enter passwords. The upload fails because the `url` parameter contains an invalid protocol. `FileReference.upload()` must use HTTP or HTTPS.

Throws

| `SecurityError` — Local untrusted SWF files may not communicate with the Internet. To avoid this situation, reclassify this SWF file as local-with-networking or trusted. This exception is thrown with a message indicating the name of the local file and the URL that may not be accessed.
| `IllegalOperationError` — Thrown in the following situations: 1) Another FileReference or FileReferenceList browse session is in progress; only one file browsing session may be performed at a time. 2) The URL parameter is not a valid path or protocol. File upload must use HTTP, and file download must use FTP or HTTP. 3) The `uploadDataFieldName` parameter is set to `null`. 4) A setting in the user's mms.cfg file prohibits this operation.
| `ArgumentError` — Thrown in the following situations: 1) The `uploadDataFieldName` parameter is an empty string. 2) `url.data` is of type ByteArray. For use with the `FileReference.upload()` and `FileReference.download()` methods, `url.data` may only be of type URLVariables or String. 3) In the AIR runtime (in the application security sandbox), the method of the URLRequest is not GET or POST (use `uploadEncoded()` instead).
| `MemoryError` — This error can occur for the following reasons: 1) Flash Player cannot convert the `URLRequest.data` parameter from UTF8 to MBCS. This error is applicable if the URLRequest object passed to `FileReference.upload()` is set to perform a GET operation and if `System.useCodePage` is set to `true`. 2) Flash Player cannot allocate memory for the `POST` data. This error is applicable if the URLRequest object passed to `FileReference.upload()` is set to perform a `POST` operation.

See also

FileReference.browse()
FileReferenceList.browse()
FileReference.download()
FileReferenceList.fileList
FileReference.load()
Working with file upload and download
Flash Player security
Event Detail

cancel | Event

Event Object Type: `flash.events.Event`
Event.type property = `flash.events.Event.CANCEL`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched when a file upload or download is canceled through the file-browsing dialog box by the user. Flash Player does not dispatch this event if the user cancels an upload or download through other means (closing the browser or stopping the current application).

Defines the value of the `type` property of a `cancel` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | A reference to the object on which the operation is canceled.

Example
The following example shows usage of the `cancel` event object. To run this example, change the `downloadURL.url` property to point to an actual domain and file, rather than the fictional http://www.[yourDomain].com/SomeFile.pdf. You might also need to compile the SWF file with Local playback security set to Access network only or to update Flash Player security settings to allow this file network access.

    package {
        import flash.display.Sprite;
        import flash.events.*;
        import flash.net.FileReference;
        import flash.net.URLRequest;

        public class FileReference_event_cancel extends Sprite {
            private var downloadURL:URLRequest;
            private var fileName:String = "SomeFile.pdf";
            private var file:FileReference;

            public function FileReference_event_cancel() {
                downloadURL = new URLRequest();
                downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
                file = new FileReference();
                file.addEventListener(Event.CANCEL, cancelHandler);
                file.download(downloadURL, fileName);
            }
            private function cancelHandler(event:Event):void {
                trace("cancelHandler: " + event);
            }
        }
    }

complete | Event |

Event Object Type: `flash.events.Event`
Event.type property = `flash.events.Event.COMPLETE`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched when download is complete or when upload generates an HTTP status code of 200. For file download, this event is dispatched when Adobe AIR finishes downloading the entire file to disk. For file upload, this event is dispatched after Adobe AIR receives an HTTP status code of 200 from the server receiving the transmission.

Defines the value of the `type` property of a `complete` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The network object that has completed loading.

Example
The following example shows usage of the `complete` event object. To run this example, change the `downloadURL.url` property to point to an actual domain and file, rather than the fictional http://www.[yourDomain].com/SomeFile.pdf. You might also need to compile the SWF file with Local playback security set to Access network only or to update Flash Player security settings to allow this file network access.

    package {
        import flash.display.Sprite;
        import flash.events.*;
        import flash.net.FileReference;
        import flash.net.URLRequest;

        public class FileReference_event_complete extends Sprite {
            private var downloadURL:URLRequest;
            private var fileName:String = "SomeFile.pdf";
            private var file:FileReference;

            public function FileReference_event_complete() {
                downloadURL = new URLRequest();
                downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
                file = new FileReference();
                configureListeners(file);
                file.download(downloadURL, fileName);
            }

            private function configureListeners(dispatcher:IEventDispatcher):void {
                dispatcher.addEventListener(Event.CANCEL, cancelHandler);
                dispatcher.addEventListener(Event.COMPLETE, completeHandler);
                dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
                dispatcher.addEventListener(Event.OPEN, openHandler);
                dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
                dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
                dispatcher.addEventListener(Event.SELECT, selectHandler);
            }

            private function cancelHandler(event:Event):void {
                trace("cancelHandler: " + event);
            }

            private function completeHandler(event:Event):void {
                trace("completeHandler: " + event);
            }

            private function ioErrorHandler(event:IOErrorEvent):void {
                trace("ioErrorHandler: " + event);
            }

            private function openHandler(event:Event):void {
                trace("openHandler: " + event);
            }

            private function progressHandler(event:ProgressEvent):void {
                var file:FileReference = FileReference(event.target);
                trace("progressHandler name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
            }

            private function securityErrorHandler(event:SecurityErrorEvent):void {
                trace("securityErrorHandler: " + event);
            }

            private function selectHandler(event:Event):void {
                var file:FileReference = FileReference(event.target);
                trace("selectHandler: name=" + file.name + " URL=" + downloadURL.url);
            }
        }
    }

See also

FileReference.download()
FileReference.upload()

httpStatus | Event |

Event Object Type: `flash.events.HTTPStatusEvent`
HTTPStatusEvent.type property = `flash.events.HTTPStatusEvent.HTTP_STATUS`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched when an upload fails and an HTTP status code is available to describe the failure. The `httpStatus` event is dispatched, followed by an `ioError` event.

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

Defines the value of the `type` property of a `httpStatus` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`status` | The HTTP status code returned by the server.
`target` | The network object receiving an HTTP status code.

See also

FileReference.upload()

ioError | Event |

Event Object Type: `flash.events.IOErrorEvent`
IOErrorEvent.type property = `flash.events.IOErrorEvent.IO_ERROR`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched when the upload or download fails. A file transfer can fail for one of the following reasons:

- An input/output error occurs while the player is reading, writing, or transmitting the file.
- The tries to upload a file to a server that requires authentication (such as a user name and password). During upload, Adobe AIR does not provide a means for users to enter passwords. If tries to upload a file to a server that requires authentication, the upload fails.
- The tries to download a file from a server that requires authentication, within 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 in these players tries to download a file from a server that requires authentication, the download fails.
- The value passed to the `url` parameter in the `upload()` method contains an invalid protocol. Valid protocols are HTTP and HTTPS.

Defines the value of the `type` property of an `ioError` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The network object experiencing the input/output error.
`text` | Text to be displayed as an error message.

See also

FileReference.download()
FileReference.upload()

open | Event |

Event Object Type: `flash.events.Event`
Event.type property = `flash.events.Event.OPEN`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched when an upload or download operation starts.

Defines the value of the `type` property of an `open` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The network object that has opened a connection.

Example
The following example shows usage of the `download` event object. To run this example, change the `downloadURL.url` property to point to an actual domain and file, rather than the fictional http://www.[yourDomain].com/SomeFile.pdf. You might also need to compile the SWF file with Local playback security set to Access network only or to update Flash Player security settings to allow this file network access.

    package {
        import flash.display.Sprite;
        import flash.events.*;
        import flash.net.FileReference;
        import flash.net.URLRequest;
        import flash.net.FileFilter;

        public class FileReference_download extends Sprite {
            private var downloadURL:URLRequest;
            private var fileName:String = "SomeFile.pdf";
            private var file:FileReference;

            public function FileReference_download() {
                downloadURL = new URLRequest();
                downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
                file = new FileReference();
                configureListeners(file);
                file.download(downloadURL, fileName);
            }

            private function configureListeners(dispatcher:IEventDispatcher):void {
                dispatcher.addEventListener(Event.CANCEL, cancelHandler);
                dispatcher.addEventListener(Event.COMPLETE, completeHandler);
                dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
                dispatcher.addEventListener(Event.OPEN, openHandler);
                dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
                dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
                dispatcher.addEventListener(Event.SELECT, selectHandler);
            }

            private function cancelHandler(event:Event):void {
                trace("cancelHandler: " + event);
            }

            private function completeHandler(event:Event):void {
                trace("completeHandler: " + event);
            }

            private function ioErrorHandler(event:IOErrorEvent):void {
                trace("ioErrorHandler: " + event);
            }

            private function openHandler(event:Event):void {
                trace("openHandler: " + event);
            }

            private function progressHandler(event:ProgressEvent):void {
                var file:FileReference = FileReference(event.target);
                trace("progressHandler name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
            }

            private function securityErrorHandler(event:SecurityErrorEvent):void {
                trace("securityErrorHandler: " + event);
            }

            private function selectHandler(event:Event):void {
                var file:FileReference = FileReference(event.target);
                trace("selectHandler: name=" + file.name + " URL=" + downloadURL.url);
            }
        }
    }

See also

FileReference.download()
FileReference.upload()

progress | Event |

Event Object Type: `flash.events.ProgressEvent`
ProgressEvent.type property = `flash.events.ProgressEvent.PROGRESS`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched periodically during the file upload or download operation. The `progress` event is dispatched while Flash Player transmits bytes to a server, and it is periodically dispatched during the transmission, even if the transmission is ultimately not successful. To determine if and when the file transmission is actually successful and complete, listen for the `complete` event.

In some cases, `progress` events are not received. For example, when the file being transmitted is very small or the upload or download happens very quickly a `progress` event might not be dispatched.

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

Defines the value of the `type` property of a `progress` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`bytesLoaded` | The number of items or bytes loaded at the time the listener processes the event.
`bytesTotal` | The total number of items or bytes that ultimately will be loaded if the loading process succeeds.
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The network object reporting progress.

Example
The following example shows usage of the `progress` event. To run this example, change the `downloadURL.url` property to point to an actual domain and file, rather than the fictional http://www.[yourDomain].com/SomeFile.pdf. You might also need to compile the SWF file with Local playback security set to Access network only or to update Flash Player security settings to allow this file network access.

    package {
        import flash.display.Sprite;
        import flash.events.*;
        import flash.net.FileReference;
        import flash.net.URLRequest;

        public class FileReference_event_progress extends Sprite {
            private var downloadURL:URLRequest;
            private var fileName:String = "SomeFile.pdf";
            private var file:FileReference;

            public function FileReference_event_progress() {
                downloadURL = new URLRequest();
                downloadURL.url = "http://www.[yourDomain].com/SomeFile.pdf";
                file = new FileReference();
                file.addEventListener(ProgressEvent.PROGRESS, progressHandler);
                file.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
                file.addEventListener(Event.COMPLETE, completeHandler);
                file.download(downloadURL, fileName);
            }

            private function progressHandler(event:ProgressEvent):void {
                var file:FileReference = FileReference(event.target);
                trace("progressHandler: name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
            }

            private function ioErrorHandler(event:IOErrorEvent):void {
                trace("ioErrorHandler: " + event);
            }

            private function completeHandler(event:Event):void {
                trace("completeHandler: " + event);
            }
        }
    }

See also

FileReference.complete
flash.events.ProgressEvent
FileReference.download()
FileReference.upload()

securityError | Event |

Event Object Type: `flash.events.SecurityErrorEvent`
SecurityErrorEvent.type property = `flash.events.SecurityErrorEvent.SECURITY_ERROR`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Dispatched when a call to the `FileReference.upload()` or `FileReference.download()` method tries to upload a file to a server or get a file from a server that is outside the caller's security sandbox. The value of the text property that describes the specific error that occurred is normally `"securitySandboxError"`. 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 URL policy file.

In Adobe AIR, these security restrictions do not apply to content in the application security sandbox.

The `SecurityErrorEvent.SECURITY_ERROR` constant defines the value of the `type` property of a `securityError` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The network object reporting the security error.
`text` | Text to be displayed as an error message.

See also

FileReference.download()
FileReference.upload()
Flash Player security

select | Event |

Event Object Type: `flash.events.Event`
Event.type property = `flash.events.Event.SELECT`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

For content running outside of the application security sandbox , the `select` event acts slightly differently depending on what method invokes it. When the `select` event is dispatched after a `browse()` call, the AIR application can read all the FileReference object's properties, because the file selected by the user is on the local file system. When the `select` event occurs after a `download()` call, the AIR application can read only the `name` property, because the file hasn't yet been downloaded to the local file system at the moment the `select` event is dispatched. When the file is downloaded and the `complete` event dispatched, the AIR application can read all other properties of the FileReference object.

Defines the value of the `type` property of a `select` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The FileReference object on which an item has been selected.

Example
The following example shows usage of the `select` event object. To run this example, change the `uploadURL.url` property to point to an actual domain and file, rather than the fictional http://www.[yourDomain].com/SomeFile.pdf. You might also need to compile the SWF file with Local playback security set to Access network only or to update Flash Player security settings to allow this file network access. In order for this example to run from your desktop, your server also needs to have a crossdomain.xml file posted. If the `ioErrorHandler()` function is triggered, you probably need to update the provided `uploadURL` with a valid url that is configured to receive uploads.

    package {
        import flash.display.Sprite;
        import flash.events.*;
        import flash.net.FileReference;
        import flash.net.URLRequest;

        public class FileReference_event_select extends Sprite {
            private var uploadURL:URLRequest;
            private var file:FileReference;

            public function FileReference_event_select() {
                uploadURL = new URLRequest();
                uploadURL.url = "http://www.[yourDomain].com/yourUploadHandlerScript.cfm";
                file = new FileReference();
                file.addEventListener(Event.SELECT, selectHandler);
                file.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
                file.addEventListener(ProgressEvent.PROGRESS, progressHandler);
                file.addEventListener(Event.COMPLETE, completeHandler);
                file.browse();
            }

            private function selectHandler(event:Event):void {
                var file:FileReference = FileReference(event.target);
                trace("selectHandler: name=" + file.name + " URL=" + uploadURL.url);
                file.upload(uploadURL);
            }

            private function ioErrorHandler(event:IOErrorEvent):void {
                trace("ioErrorHandler: " + event);
            }

            private function progressHandler(event:ProgressEvent):void {
                var file:FileReference = FileReference(event.target);
                trace("progressHandler: name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
            }

            private function completeHandler(event:Event):void {
                trace("completeHandler: " + event);
            }
        }
    }

uploadCompleteData | Event |

Event Object Type: `flash.events.DataEvent`
DataEvent.type property = `flash.events.DataEvent.UPLOAD_COMPLETE_DATA`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9.0.28.0

Dispatched after data is received from the server after a successful upload. This event is not dispatched if data is not returned from the server.

Defines the value of the `type` property of an `uploadCompleteData` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`data` | The raw data returned from the server after a successful file upload.
`target` | The FileReference object receiving data after a successful upload.

Examples How to use examples
FileReferenceExample.as
The following example displays the data format and status information for a file loaded at runtime.

Note: To run this example, change the uploadURL.url property to point to an actual URL, rather than the fictional one in the example. The URL should point to a file named `yourUploadHandlerScript.cfm` in the root web directory of the URL specified. Based on your configuration, you might also need to compile the SWF file with Local Playback Security set to Access Network Only or to update Flash Player security settings to allow this file network access.

    package {
        import flash.display.Sprite;
        import flash.events.*;
        import flash.net.FileFilter;
        import flash.net.FileReference;
        import flash.net.URLRequest;

        public class FileReferenceExample extends Sprite {
            private var uploadURL:URLRequest;
            private var file:FileReference;

            public function FileReferenceExample() {
                uploadURL = new URLRequest();
                uploadURL.url = "http://www.[yourDomain].com/yourUploadHandlerScript.cfm";
                file = new FileReference();
                configureListeners(file);
                file.browse(getTypes());
            }

            private function configureListeners(dispatcher:IEventDispatcher):void {
                dispatcher.addEventListener(Event.CANCEL, cancelHandler);
                dispatcher.addEventListener(Event.COMPLETE, completeHandler);
                dispatcher.addEventListener(HTTPStatusEvent.HTTP_STATUS, httpStatusHandler);
                dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
                dispatcher.addEventListener(Event.OPEN, openHandler);
                dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
                dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
                dispatcher.addEventListener(Event.SELECT, selectHandler);
                dispatcher.addEventListener(DataEvent.UPLOAD_COMPLETE_DATA,uploadCompleteDataHandler);
            }

            private function getTypes():Array {
                var allTypes:Array = new Array(getImageTypeFilter(), getTextTypeFilter());
                return allTypes;
            }

            private function getImageTypeFilter():FileFilter {
                return new FileFilter("Images (*.jpg, *.jpeg, *.gif, *.png)", "*.jpg;*.jpeg;*.gif;*.png");
            }

            private function getTextTypeFilter():FileFilter {
                return new FileFilter("Text Files (*.txt, *.rtf)", "*.txt;*.rtf");
            }

            private function cancelHandler(event:Event):void {
                trace("cancelHandler: " + event);
            }

            private function completeHandler(event:Event):void {
                trace("completeHandler: " + event);
            }

            private function uploadCompleteDataHandler(event:Event):void {
                trace("uploadCompleteData: " + event);
            }

            private function httpStatusHandler(event:HTTPStatusEvent):void {
                trace("httpStatusHandler: " + event);
            }

            private function ioErrorHandler(event:IOErrorEvent):void {
                trace("ioErrorHandler: " + event);
            }

            private function openHandler(event:Event):void {
                trace("openHandler: " + event);
            }

            private function progressHandler(event:ProgressEvent):void {
                var file:FileReference = FileReference(event.target);
                trace("progressHandler name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
            }

            private function securityErrorHandler(event:SecurityErrorEvent):void {
                trace("securityErrorHandler: " + event);
            }

            private function selectHandler(event:Event):void {
                var file:FileReference = FileReference(event.target);
                trace("selectHandler: name=" + file.name + " URL=" + uploadURL.url);
                file.upload(uploadURL);
            }
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00