class FileReference
package openfl.net
extends EventDispatcher
extended by File
Available on all platforms
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). 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
newoperator 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--Events:
cancel | 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). |
|---|---|
complete | 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. |
httpResponseStatus | Dispatched if a call to the |
httpStatus | Dispatched when an upload fails and an HTTP
status code is available to describe the
failure. The |
ioError | 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 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. |
open | Dispatched when an upload or download operation starts. |
progress | Dispatched periodically during the file upload
or download operation. The File upload progress cannot be determined on
Macintosh platforms earlier than OS X 10.3. The
|
securityError | Dispatched when a call to the
In Adobe AIR, these security restrictions do not apply to content in the application security sandbox. |
select | 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
|
uploadCompleteData | 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. |
See also:
Constructor
new()
Creates a new FileReference object. When populated, a FileReference object represents a file on the user's local disk.
Variables
read onlycreationDate:Date
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.
Throws:
IOError | If the file information cannot be accessed, an exception is thrown with a message indicating a file I/O error. |
|---|---|
IllegalOperationError | If the |
read onlycreator:String
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.
Throws:
IllegalOperationError | On Macintosh, if the
|
|---|
read onlydata:ByteArray
The ByteArray object representing the data from the loaded file after
a successful call to the load() method.
Throws:
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 |
|---|---|
IllegalOperationError | If the |
read onlyextension:String
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.
Throws:
IllegalOperationError | If the reference is not initialized |
|---|
read onlymodificationDate:Date
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.
Throws:
IOError | If the file information cannot be accessed, an exception is thrown with a message indicating a file I/O error. |
|---|---|
IllegalOperationError | If the |
read onlyname:String
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.
Throws:
IllegalOperationError | If the |
|---|
read onlysize:Float
The size of the file on the local disk in bytes. If size is 0, an
exception is thrown.
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 was later implemented as a Number object to
support larger files. In OpenFL, it is Float to match Number.
Throws:
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. |
|---|---|
IllegalOperationError | If the |
read onlytype:String
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.
Throws:
IllegalOperationError | If the |
|---|
Methods
browse(?typeFilter:Array<FileFilter>):Bool
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.
Returns:
Returns true if the parameters are valid and the
file-browsing dialog box opens.
Throws:
ArgumentError | If the |
|---|---|
Error | If the method is not called in response to a user action, such as a mouse event or keypress event. |
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. |
Events:
cancel | Dispatched when the user cancels the file upload Browse window. |
|---|---|
select | Dispatched when the user successfully selects an item from the Browse file chooser. |
cancel():Void
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(request:URLRequest, ?defaultFileName:String):Void
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 OpenFL 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
allowNetworkingparameter of the theobjectandembedtags 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 | The URLRequest object. The |
|---|---|
defaultFileName | The default filename displayed in the dialog
box for the file to be downloaded. This string
must not contain the following characters: |
Throws:
ArgumentError | If |
|---|---|
Error | If the method is not called in response to a user action, such as a mouse event or keypress event. |
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 |
MemoryError | This error can occur for the following
reasons: 1) Flash Player cannot convert
the |
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 OpenFL Developer's Guide. |
Events:
cancel | Dispatched when the user dismisses the dialog box. |
|---|---|
complete | Dispatched when the file download operation successfully completes. |
ioError | Dispatched for any of the following reasons: An input/output error occurs while the file is being read or transmitted. SWF content running in the stand-alone or external versions of Flash Player tries to download a file from a server that requires authentication. 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. |
open | Dispatched when a download operation starts. |
progress | Dispatched periodically during the file download operation. |
securityError | Dispatched when a download fails because of a security error. |
select | Dispatched when the user selects a file for download from the dialog box. |
See also:
load():Void
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
allowNetworkingparameter of the theobjectandembedtags 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.
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. |
Events:
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. |
open | Dispatched when an load operation starts. |
progress | Dispatched periodically during the file load operation. |
See also:
save(data:Dynamic, ?defaultFileName:String):Void
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:
If the value is |
|---|---|
defaultFileName | The default filename displayed in the dialog
box for the file to be saved. This string must
not contain the following characters: |
Throws:
ArgumentError | If |
|---|---|
Error | If the method is not called in response to a user action, such as a mouse event or keypress event. |
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. |
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. |
Events:
cancel | Dispatched when the user dismisses the dialog box. |
|---|---|
complete | Dispatched when the file download operation successfully completes. |
ioError | Dispatched if an input/output error occurs while the file is being read or transmitted. |
open | Dispatched when a download operation starts. |
progress | Dispatched periodically during the file download operation. |
select | Dispatched when the user selects a file for download from the dialog box. |
See also:
upload(request:URLRequest, uploadDataFieldName:String = "Filedata", testUpload:Bool = false):Void
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-Typeofmultipart/form-dataContent-Dispositionwith anameattribute set to"Filedata"by default and afilenameattribute 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 OpenFL 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
allowNetworkingparameter of the theobjectandembedtags 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 | The URLRequest object; the To send |
|---|---|
uploadDataFieldName | The field name that precedes the file data
in the upload |
testUpload | A setting to request a test file upload. If
|
Throws:
ArgumentError | Thrown in the following situations: 1)
The |
|---|---|
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 |
MemoryError | This error can occur for the following
reasons: 1) Flash Player cannot convert
the |
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 OpenFL Developer's Guide. |
Events:
complete | Dispatched when the file upload operation completes successfully. |
|---|---|
httpResponseStatus | The upload operation completes successfully and the server returns a response URL and response headers. |
httpStatus | Dispatched when an upload fails because of an HTTP error. |
ioError | 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 mean is
provided for users to enter passwords.
* The upload fails because the |
open | Dispatched when an upload operation starts. |
progress | Dispatched periodically during the file upload operation. |
securityError | Dispatched when an upload fails because of a security violation. |
uploadCompleteData | Dispatched when data has been received from the server after a successful file upload. |
See also: