Package | flash.net |
Class | public class FileReference |
Inheritance | FileReference EventDispatcher Object |
Subclasses | File |
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, Flash Player 9 |
Note: In Adobe AIR, the File class, which extends the FileReference class, provides more capabilities and has less security restrictions than the FileReference class.
FileReference instances are created in the following 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 Flash Player or 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.
Note that because of new functionality added to the Flash Player, when publishing to Flash Player 10, you can have
only one of the following operations active at one time: FileReference.browse()
,
FileReference.upload()
, FileReference.download()
, FileReference.load()
,
FileReference.save()
. Otherwise, Flash Player throws a runtime error (code 2174). Use FileReference.cancel()
to stop an operation in progress. This restriction applies only to Flash Player 10. Previous versions of Flash Player
are unaffected by this restriction on simultaneous multiple operations.
While calls to the FileReference.browse()
, FileReferenceList.browse()
,
or FileReference.download()
methods are executing, SWF file playback pauses in stand-alone and external versions
of Flash Player and in AIR for Linux and Mac OS X 10.1 and earlier
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=----------Ij5ae0ae0KM7GI3KM7 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="Filedata"; 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=----------Ij5ae0ae0KM7GI3KM7 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="Filedata"; filename="MyFile.jpg" Content-Type: application/octet-stream FileDataHere ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7 Content-Disposition: form-data; name="Upload" Submit Query ------------Ij5GI3GI3ei4GI3ei4KM7GI3KM7KM7--
Learn more
Related API Elements
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, which is only used in Mac OS versions
prior to Mac OS X. | FileReference | ||
data : ByteArray [read-only]
The ByteArray object representing the data from the loaded file after a successful call to the load() method. | FileReference | ||
extension : String [read-only]
The filename extension. | 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 | ||
permissionStatus : String [static] [read-only]
Determine whether the application has been granted the permission to access filesystem. | FileReference | ||
size : Number [read-only]
The size of the file on the local disk in bytes. | FileReference | ||
type : String [read-only]
The file type. | FileReference |
Method | Defined By | ||
---|---|---|---|
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 | ||
Displays a file-browsing dialog box that lets the
user select a file to upload. | FileReference | ||
Cancels any ongoing upload or download operation on this FileReference object. | FileReference | ||
Dispatches an event into the event flow. | EventDispatcher | ||
Opens a dialog box that lets the user download a file from a remote server. | FileReference | ||
Checks whether the EventDispatcher object has any listeners registered for a specific type
of event. | EventDispatcher | ||
Indicates whether an object has a specified property defined. | Object | ||
Indicates whether an instance of the Object class is in the prototype chain of the object specified
as the parameter. | Object | ||
Starts the load of a local file selected by a user. | FileReference | ||
Indicates whether the specified property exists and is enumerable. | Object | ||
Removes a listener from the EventDispatcher object. | EventDispatcher | ||
Requests permission to access filesystem. | FileReference | ||
Opens a dialog box that lets the user save a file to the local filesystem. | FileReference | ||
Sets the availability of a dynamic property for loop operations. | Object | ||
Returns the string representation of this object, formatted according to locale-specific conventions. | Object | ||
Returns the string representation of the specified object. | Object | ||
upload(request:URLRequest, uploadDataFieldName:String = "Filedata", testUpload:Boolean = false):void
Starts the upload of the file to a remote server. | FileReference | ||
Initiate uploading a file to a URL without any encoding. | FileReference | ||
Returns the primitive value of the specified object. | Object | ||
Checks whether an event listener is registered with this EventDispatcher object or any of
its ancestors for the specified event type. | EventDispatcher |
Event | Summary | Defined By | ||
---|---|---|---|---|
[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher | |||
Dispatched when a file upload or download is canceled through the file-browsing dialog box by the user. | FileReference | |||
Dispatched when download is complete or when upload generates an HTTP status code of 200. | FileReference | |||
[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher | |||
Dispatched if a call to the upload() or uploadUnencoded() method attempts to access data over HTTP and Adobe AIR is able to detect and return the status code for the request. | FileReference | |||
Dispatched when an upload fails and an HTTP status code is available to describe the failure. | FileReference | |||
Dispatched when the upload or download fails. | FileReference | |||
Dispatched when an upload or download operation starts. | FileReference | |||
Dispatched when the application requests permission to access filesystem. | FileReference | |||
Dispatched periodically during the file upload or download operation. | FileReference | |||
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 | |||
Dispatched when the user selects a file for upload or download from the file-browsing dialog box. | FileReference | |||
Dispatched after data is received from the server after a successful upload. | FileReference |
creationDate | property |
creationDate:Date
[read-only] Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, Flash Player 9 |
The creation date of the file on the local disk. If the object is
was not populated, a call to get the value of this property returns null
.
Note: If an operating system does not have creationDate
as its property,
in such cases, CreationDate
is equal to lastModifiedDate
.
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.
|
Related API Elements
creator | property |
creator:String
[read-only] Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, Flash Player 9 |
The Macintosh creator type of the file, which is only used in Mac OS versions
prior to Mac OS X. In Windows or Linux, 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 .
|
Learn more
Related API Elements
data | property |
data:ByteArray
[read-only] Language Version: | ActionScript 3.0 |
Runtime Versions: | Flash Player 10, AIR 1.5 |
The ByteArray object representing the data from the loaded file after a successful call to the load()
method.
Implementation
public function get data():ByteArray
Throws
IllegalOperationError — If the 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 .
|
Learn more
Related API Elements
extension | property |
extension:String
[read-only] Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0 |
The filename extension.
A file's extension is the part of the name following (and not including) the final dot (".").
If there is no dot in the filename, the extension is null
.
Note: You should use the extension
property to determine a file's type; do not use the
creator
or type
properties. You should consider the creator
and type
properties to be considered deprecated. They apply to older versions of Mac OS.
Implementation
public function get extension():String
Throws
IllegalOperationError — If the reference is not initialized.
|
modificationDate | property |
modificationDate:Date
[read-only] Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, Flash Player 9, 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.
|
Related API Elements
name | property |
name:String
[read-only] Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, 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.
|
Related API Elements
permissionStatus | property |
size | property |
size:Number
[read-only] Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, Flash Player 9 |
The size of the file on the local disk in bytes.
Note: In the initial version of ActionScript 3.0, the size
property was
defined as a uint object, which supported files with sizes up to about 4 GB. It is now implemented as a Number
object to support larger files.
Implementation
public function get size():Number
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.
| |
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.
|
Related API Elements
type | property |
type:String
[read-only] Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, Flash Player 9 |
The file type.
In Windows or Linux, this property is the file extension. On the Macintosh, this property is
the four-character file type, which is only used in Mac OS versions prior to Mac OS X. If the FileReference object
was not populated, a call to get the value of this property returns null
.
For Windows, Linux, and Mac OS X, the file extension — the portion of the name
property that
follows the last occurrence of the dot (.) character — identifies the file type.
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 .
|
Related API Elements
FileReference | () | Constructor |
public function FileReference()
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, Flash Player 9 |
Creates a new FileReference object. When populated, a FileReference object represents a file on the user's local disk.
Related API Elements
browse | () | method |
public function browse(typeFilter:Array = null):Boolean
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, 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.
Note: The File class, available in Adobe AIR, includes methods for
accessing more specific system file selection dialog boxes. These methods are
File.browseForDirectory()
, File.browseForOpen()
,
File.browseForOpenMultiple()
, and File.browseForSave()
.
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.
In Flash Player 10 and Flash Player 9 Update 5, you can only call this method successfully in response to a user event (for example, in an event handler for a mouse click or keypress event). Otherwise, calling this method results in Flash Player throwing an Error exception.
Note that because of new functionality added to the Flash Player, when publishing to Flash Player 10, you can have
only one of the following operations active at one time: FileReference.browse()
,
FileReference.upload()
, FileReference.download()
, FileReference.load()
,
FileReference.save()
. Otherwise, Flash Player throws a runtime error (code 2174). Use FileReference.cancel()
to stop an operation in progress. This restriction applies only to Flash Player 10. Previous versions of Flash Player
are unaffected by this restriction on simultaneous multiple operations.
In Adobe AIR, the file-browsing dialog is not always displayed in front of windows that are
"owned" by another window (windows that have a non-null owner
property).
To avoid window ordering issues, hide owned windows before calling this method.
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.
|
Boolean — Returns true if the parameters are valid and the file-browsing dialog box
opens.
|
Events
select: — Dispatched when the user successfully selects an item from the Browse file chooser.
| |
cancel: — 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.
| |
Error — If the method is not called in response to a user action, such as a mouse
event or keypress event.
|
Learn more
Related API Elements
cancel event
FileReference.download()
FileReferenceList.browse()
File.browseForDirectory()
File.browseForOpen()
File.browseForOpenMultiple()
File.browseForSave()
cancel | () | method |
public function cancel():void
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, 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 |
Runtime Versions: | AIR 1.0, 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 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.
You cannot connect to commonly reserved ports. For a complete list of blocked ports, see "Restricting Networking APIs" in the ActionScript 3.0 Developer's Guide.
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 Flash Player 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 theobject
andembed
tags in the HTML page that contains the SWF content. - In Flash Player 10 and Flash Player 9 Update 5, you can only call this method successfully in response to a user event (for example, in an event handler for a mouse click or keypress event). Otherwise, calling this method results in Flash Player throwing an Error exception.
However, in Adobe AIR,
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 Flash Player Developer Center Topic: Security.
When you download a file using this method, it is flagged as downloaded on operating systems that flag downloaded files:
- Windows XP service pack 2 and later, and on Windows Vista
- Mac OS 10.5 and later
Some operating systems, such as Linux, do not flag downloaded files.
Note that because of new functionality added to the Flash Player, when publishing to Flash Player 10, you can have
only one of the following operations active at one time: FileReference.browse()
,
FileReference.upload()
, FileReference.download()
, FileReference.load()
,
FileReference.save()
. Otherwise, Flash Player throws a runtime error (code 2174). Use FileReference.cancel()
to stop an operation in progress. This restriction applies only to Flash Player 10. Previous versions of Flash Player
are unaffected by this restriction on simultaneous multiple operations.
In Adobe AIR, the download dialog is not always displayed in front of windows that are
"owned" by another window (windows that have a non-null owner
property).
To avoid window ordering issues, hide owned windows before calling this method.
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. The requestHeaders property
of the URLRequest object is ignored; custom HTTP request headers are not supported in uploads or downloads.
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: — Dispatched when a download operation starts.
| |
progress: — Dispatched periodically during the file download operation.
| |
complete: — Dispatched when the file download operation successfully completes.
| |
cancel: — Dispatched when the user dismisses the dialog box.
| |
select: — Dispatched when the user selects a file for download from the dialog box.
| |
securityError: — Dispatched when a download fails because of a
security error.
| |
ioError: — Dispatched for any of the following reasons:
|
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 content 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.
| |
SecurityError — You cannot connect to commonly reserved ports.
For a complete list of blocked ports, see "Restricting Networking APIs" in the
ActionScript 3.0 Developer's Guide.
| |
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.
| |
Error — If the method is not called in response to a user action, such as a mouse
event or keypress event.
|
Learn more
Related API Elements
FileReference.browse()
FileReferenceList.browse()
FileReference.upload()
FileReference.save()
Example ( How to use this example )
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 |
public function load():void
Language Version: | ActionScript 3.0 |
Runtime Versions: | Flash Player 10, AIR 1.5 |
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, it officially supports sizes of up to 100 MB. For content running in Flash Player,
you must call the FileReference.browse()
or FileReferenceList.browse()
method before
you call the load()
method. However, content running in AIR in the application sandbox can call
the load()
method of a File object without first calling the browse()
method.
(The AIR File class extends the FileReference class.)
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 load the files
one by one, iterate through the FileReferenceList.fileList
array of FileReference objects.
Adobe AIR also includes the FileStream class which provides more options for reading files.
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 stored as a byte array
in the data
property of the FileReference object.
The following security considerations apply:
- 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 cross-domain policy file.
- You can prevent a file from using this method by setting the
allowNetworking
parameter of the theobject
andembed
tags in the HTML page that contains the SWF content.
However, these considerations do not apply to AIR content in the application sandbox.
Note that when publishing to Flash Player 10 or AIR 1.5, you can have only one of the following operations active at one time:
FileReference.browse()
, FileReference.upload()
, FileReference.download()
, FileReference.load()
,
FileReference.save()
. Otherwise, the application throws a runtime error (code 2174). Use FileReference.cancel()
to stop an operation in progress. This restriction applies only to Flash Player 10 and AIR 1.5. Previous versions of Flash Player
or AIR are unaffected by this restriction on simultaneous multiple operations.
In Adobe AIR, the file-browsing dialog is not always displayed in front of windows that are
"owned" by another window (windows that have a non-null owner
property).
To avoid window ordering issues, hide owned windows before calling this method.
Events
open: — Dispatched when an load operation starts.
| |
progress: — Dispatched periodically during the file load operation.
| |
complete: — Dispatched when the file load operation completes successfully.
| |
ioError: — Invoked if the load fails because of an input/output error while the application
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 the application cannot allocate memory for the file.
The file may be too large or available memory may be too low.
|
Learn more
Related API Elements
FileReferenceList.browse()
FileReference.data
FileReferenceList.fileList
FileReference.save()
FileStream
Example ( How to use this example )
var buttonShape:Shape = new Shape(); buttonShape.graphics.beginFill(0x336699); buttonShape.graphics.drawCircle(50, 50, 25); var button = new SimpleButton(buttonShape, buttonShape, buttonShape, buttonShape); addChild(button); var fileRef:FileReference= new FileReference(); button.addEventListener(MouseEvent.CLICK, onButtonClick); function onButtonClick(e:MouseEvent):void { fileRef.browse([new FileFilter("Images", "*.jpg;*.gif;*.png")]); fileRef.addEventListener(Event.SELECT, onFileSelected); } function onFileSelected(e:Event):void { fileRef.addEventListener(Event.COMPLETE, onFileLoaded); fileRef.load(); } function onFileLoaded(e:Event):void { var loader:Loader = new Loader(); loader.loadBytes(e.target.data); addChild(loader); }
requestPermission | () | method |
public function requestPermission():void
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 24.0 |
Requests permission to access filesystem.
Events
PermissionStatus: — dispatched when the requested permission is granted/denied by the user.
|
save | () | method |
public function save(data:*, defaultFileName:String = null):void
Language Version: | ActionScript 3.0 |
Runtime Versions: | Flash Player 10, AIR 1.5 |
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 code must listen for events
such as cancel
, open
,
progress
, and complete
.
Adobe AIR also includes the FileStream class which provides more options for saving files locally.
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).
In Flash Player, you can only call this method successfully in response to a user event (for example, in an event handler for a mouse click or keypress event). Otherwise, calling this method results in Flash Player throwing an Error exception. This limitation does not apply to AIR content in the application sandbox.
In Adobe AIR, the save dialog is not always displayed in front of windows that are
"owned" by another window (windows that have a non-null owner
property).
To avoid window ordering issues, hide owned windows before calling this method.
Parameters
data:* — The data to be saved. The data can be in one of several formats, and will be treated
appropriately:
| |
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 a File object calls this method, the filename will be that of the file the File object references. (The AIR File class extends the FileReference class.) |
Events
open: — Dispatched when a download operation starts.
| |
progress: — Dispatched periodically during the file download operation.
| |
complete: — Dispatched when the file download operation successfully completes.
| |
cancel: — Dispatched when the user dismisses the dialog box.
| |
select: — Dispatched when the user selects a file for download from the dialog box.
| |
ioError: — 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.
| |
Error — If the method is not called in response to a user action, such as a mouse
event or keypress event.
| |
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.
|
Learn more
Related API Elements
FileReference.load()
FileReference.data
FileReference.upload()
FileReference.download()
FileStream
Example ( How to use this example )
MyTextField
)
and another text field that is not editable (MyButtonField
)to serve as a "button"
to respond to a mouse click. A user can edit the first text field and click the button
to save the text field contents to a local file. The mouse click event handler clickhandler
uses the FileReference.save()
method (for a FileReference object named MyFileReference
)
to open a dialog on the user's current operating system so the user can save the contents to a local file with the
name the user provides.
var MyTextField:TextField = new TextField(); var MyButtonField:TextField = new TextField(); var MyFile:FileReference = new FileReference(); MyTextField.border = true; MyTextField.type = TextFieldType.INPUT; MyButtonField.background = true; MyButtonField.backgroundColor = 0x339933; MyButtonField.x = 150; MyButtonField.height = 20; MyButtonField.text = "Click here to save"; addChild(MyTextField); addChild(MyButtonField); MyButtonField.addEventListener(MouseEvent.CLICK, clickhandler); function clickhandler(e:MouseEvent): void { MyFile.save(MyTextField.text); }
upload | () | method |
public function upload(request:URLRequest, uploadDataFieldName:String = "Filedata", testUpload:Boolean = false):void
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, Flash Player 9 |
Starts the upload of the file 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.
For the Adobe AIR File class, which extends the FileReference class, you can use the upload()
method to upload any file. For the FileReference class (used in Flash Player), the user must first
select a file.
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
ofmultipart/form-data
Content-Disposition
with aname
attribute set to"Filedata"
by default and afilename
attribute set to the name of the original file- The binary contents of the file
You cannot connect to commonly reserved ports. For a complete list of blocked ports, see "Restricting Networking APIs" in the ActionScript 3.0 Developer's Guide.
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 Flash Player 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 theobject
andembed
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 Flash Player Developer Center Topic: Security.
Note that because of new functionality added to the Flash Player, when publishing to Flash Player 10, you can have
only one of the following operations active at one time: FileReference.browse()
,
FileReference.upload()
, FileReference.download()
, FileReference.load()
,
FileReference.save()
. Otherwise, Flash Player throws a runtime error (code 2174). Use FileReference.cancel()
to stop an operation in progress. This restriction applies only to Flash Player 10. Previous versions of Flash Player
are unaffected by this restriction on simultaneous multiple operations.
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 requestHeaders property
of the URLRequest object is ignored; custom HTTP request headers are not supported in uploads or downloads.
The URL can be HTTP or, for secure uploads, HTTPS.
To use HTTPS, use an HTTPS url in the To send | |
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: — Dispatched when an upload operation starts.
| |
progress: — Dispatched periodically during the file upload operation.
| |
complete: — Dispatched when the file upload operation completes successfully.
| |
uploadCompleteData: — Dispatched when data has been received from the server after a successful file upload.
| |
securityError: — Dispatched when an upload fails because of a
security violation.
| |
httpStatus: — Dispatched when an upload fails because of an HTTP error.
| |
httpResponseStatus: — The upload operation completes successfully and the server
returns a response URL and response headers.
| |
ioError: — Invoked in any of the following situations:
|
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.
| |
SecurityError — You cannot connect to commonly reserved ports.
For a complete list of blocked ports, see "Restricting Networking APIs" in the
ActionScript 3.0 Developer's Guide.
| |
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.
|
Learn more
Related API Elements
uploadUnencoded | () | method |
public function uploadUnencoded(request:URLRequest):void
Runtime Versions: | AIR 1.0 |
Initiate uploading a file to a URL without any encoding. Whereas the upload()
method encodes
the file in a form-data envelope, the uploadUnencoded()
method passes the file contents as-is
in the HTTP request body. Use the uploadUnencoded() method if the data you wish to send is already encoded
in a format that the receiving server can understand.You typically use the uploadeUnencoded()
method with the HTTP/WebDAV PUT
method.
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 To send |
Events
open: — Dispatched when an upload operation starts.
| |
progress: — Dispatched periodically during the file upload operation.
| |
complete: — Dispatched when the file upload operation completes successfully.
| |
uploadCompleteData: — Dispatched when data has been received from the server after a
successful file upload.
| |
securityError: — Dispatched when an upload fails because of a
security violation.
| |
httpStatus: — Dispatched when an upload fails because of an HTTP error.
| |
httpResponseStatus: — The upload operation completes successfully and the server
returns a response URL and response headers.
| |
ioError: — Invoked in any of the following situations:
|
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.
|
Related API Elements
cancel | Event |
flash.events.Event
property Event.type =
flash.events.Event.CANCEL
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, 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).
TheEvent.CANCEL
constant 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 ( How to use this example )
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 |
flash.events.Event
property Event.type =
flash.events.Event.COMPLETE
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, 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 Flash Player or Adobe AIR finishes downloading the entire file to disk. For file upload, this event is dispatched after the Flash Player or Adobe AIR receives an HTTP status code of 200 from the server receiving the transmission.
TheEvent.COMPLETE
constant 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 ( How to use this example )
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); } } }
Related API Elements
httpResponseStatus | Event |
flash.events.HTTPStatusEvent
property HTTPStatusEvent.type =
flash.events.HTTPStatusEvent.HTTP_RESPONSE_STATUS
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, AIR 1.0 |
Dispatched if a call to the upload()
or uploadUnencoded()
method attempts to access data over HTTP and Adobe AIR is able to detect and return
the status code for the request.
httpStatus
event, the httpResponseStatus
event is
delivered before any response data. Also, the httpResponseStatus
event includes
values for the responseHeaders
and responseURL
properties (which are
undefined for an httpStatus
event. Note that the httpResponseStatus
event
(if any) will be sent before (and in addition to) any complete
or error
event.
The HTTPStatusEvent.HTTP_RESPONSE_STATUS
constant defines the value of the
type
property of a httpResponseStatus
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. |
responseURL | The URL from which the response was returned. |
responseHeaders | The response headers that the response returned, as an array of URLRequestHeader objects. |
status | The HTTP status code returned by the server. |
redirected | Whether the reponse is the result of a redierct. |
target | The network object receiving an HTTP status code. |
Related API Elements
httpStatus | Event |
flash.events.HTTPStatusEvent
property HTTPStatusEvent.type =
flash.events.HTTPStatusEvent.HTTP_STATUS
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, 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.
For content running in Flash Player 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.
HTTPStatusEvent.HTTP_STATUS
constant 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. |
Related API Elements
ioError | Event |
flash.events.IOErrorEvent
property IOErrorEvent.type =
flash.events.IOErrorEvent.IO_ERROR
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, 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 SWF file tries to upload a file to a server that requires authentication (such as a user name and password). During upload, Flash Player or Adobe AIR does not provide a means for users to enter passwords. If a SWF file tries to upload a file to a server that requires authentication, the upload fails.
- The SWF file tries to download a file from a server that requires authentication, 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 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, browser plug-in players, and the Adobe AIR runtime.
- The value passed to the
url
parameter in theupload()
method contains an invalid protocol. Valid protocols are HTTP and HTTPS.
Important: Only applications running in a browser — that is, using the browser plug-in or ActiveX control — and content running in Adobe AIR can provide a dialog box to prompt the user to enter a user name and password for authentication, and then only for downloads. For uploads using the plug-in or ActiveX control version of Flash Player, or for upload or download using either the stand-alone or the external player, the file transfer fails.
Defines the value of thetype
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. |
errorID | A reference number associated with the specific error (AIR only). |
target | The network object experiencing the input/output error. |
text | Text to be displayed as an error message. |
Related API Elements
open | Event |
flash.events.Event
property Event.type =
flash.events.Event.OPEN
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, Flash Player 9 |
Dispatched when an upload or download operation starts.
TheEvent.OPEN
constant 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 ( How to use this example )
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); } } }
Related API Elements
permissionStatus | Event |
flash.events.PermissionEvent
property PermissionEvent.type =
flash.events.PermissionEvent.PERMISSION_STATUS
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 24.0 |
Dispatched when the application requests permission to access filesystem.
Check the value of status
property to determine whether
the permission was granted or denied
Related API Elements
progress | Event |
flash.events.ProgressEvent
property ProgressEvent.type =
flash.events.ProgressEvent.PROGRESS
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, 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.
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 object reporting progress. |
Example ( How to use this example )
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); } } }
Related API Elements
securityError | Event |
flash.events.SecurityErrorEvent
property SecurityErrorEvent.type =
flash.events.SecurityErrorEvent.SECURITY_ERROR
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, 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.
In Adobe AIR, these security restrictions do not apply to content in the application security sandbox.
TheSecurityErrorEvent.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. |
Related API Elements
select | Event |
flash.events.Event
property Event.type =
flash.events.Event.SELECT
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, 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 in Flash Player or outside of the
application security sandbox in the Adobe AIR runtime,
the select
event acts slightly differently depending on what
method invokes it. When the select
event is dispatched after a browse()
call,
Flash Player or 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,
Flash Player or 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, Flash Player or
the AIR application can read all other properties of the FileReference object.
Event.SELECT
constant 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 object on which an item has been selected. |
Example ( How to use this example )
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 |
flash.events.DataEvent
property DataEvent.type =
flash.events.DataEvent.UPLOAD_COMPLETE_DATA
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 1.0, 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 thetype
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. |
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:DataEvent):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); } } }
Wed Nov 21 2018, 06:34 AM -08:00