Package | air.desktop |
Class | public class URLFilePromise |
Inheritance | URLFilePromise EventDispatcher Object |
Implements | IFilePromise |
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
The URLFilePromise class implements the IFilePromise interface using URLStream and URLRequest objects as the data source. The implementation provides drag and drop support for files that can be retrieved using HTTP or the other protocols supported by the URLStream class.
To create a URL file promise:
- Construct and initialize one or more URLFilePromise objects.
- Add the URLFilePromise objects to an array.
- Add the array to a new Clipboard object using the ClipboardFormat,
FILE_PROMISE_LIST
. - In response to a user gesture, call the NativeDragManager
startDrag()
method, passing in the Clipboard object containing the array of file promises.
When the user completes the drag operation, the runtime downloads the data for each file promise. The data is
accessed at the URL specified by the request
property of the URLFilePromise object and saved to the file
specified in the relativePath
property. The file is saved relative to the drop location. Thus, if the
relative path is foo/bar.txt
, and the file promise is dropped into a directory called home
, then the location of the
created file is: home/foo/bar.txt
. When an error occurs, the file is not created.
To support data sources that are not accessible through the URLStream class, implement the IFilePromise interface.
Note: The AIR runtime calls the IFilePromise methods, open()
, close()
, and reportError()
automatically. These methods should never be called by your application logic. Likewise, the open
, progress
,
complete
, and close
events dispatched by this URLFilePromise object are provided primarily for debugging
purposes. Your application does not need to respond to these events.
This class is included in the aircore.swc file. Adobe® Flash™ Builder loads this class automatically when you create a project for Adobe® AIR™. The Adobe® Flex™ SDK also includes this aircore.swc file, which you should include when compiling the application if you are using the Flex SDK.
To use air.desktop package in Adobe® Flash® Professional (CS4 or higher):
- Select the File > Publish Settings command.
- In the Flash panel, click the Settings button for ActionScript 3.0. Select Library Path.
- Click the Browse to SWC File button. Browse to Adobe Flash CSn/AIKn.n/frameworks/libs/air/aircore.swc file in the Adobe Flash Professional installation folder.
- Click the OK button.
- Add the following
import
statement to your ActionScript 3.0 code:import air.desktop.*;
More examples
Related API Elements
Clipboard class
ClipboardFormats class
NativeDragManager class
URLStream class
URLRequest class
Property | Defined By | ||
---|---|---|---|
constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | ||
isAsync : Boolean [read-only]
Indicates whether the resource data is available asynchronously. | URLFilePromise | ||
relativePath : String
The path and file name of the created file, relative to the drop destination. | URLFilePromise | ||
request : URLRequest
The URLRequest identifying the resource to be copied as the result of the drag-and-drop operation. | URLFilePromise |
Method | Defined By | ||
---|---|---|---|
Creates a URLFilePromise object. | URLFilePromise | ||
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 | ||
Allows the AIR runtime to close the data source at the appropriate time during the drag-and-drop operation. | URLFilePromise | ||
Dispatches an event into the event flow. | EventDispatcher | ||
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 | ||
Allows the AIR runtime to open the data source at the appropriate time during the drag-and-drop operation. | URLFilePromise | ||
Indicates whether the specified property exists and is enumerable. | Object | ||
Removes a listener from the EventDispatcher object. | EventDispatcher | ||
Allows the AIR runtime to report errors that occur during the drag-and-drop operation. | URLFilePromise | ||
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 | ||
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 the data for the file has been fully downloaded. | URLFilePromise | |||
[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher | |||
Dispatched for HTTP requests to report the response headers. | URLFilePromise | |||
Dispatched for HTTP requests to report the request status code. | URLFilePromise | |||
Dispatched when an IOError prevents the file download. | URLFilePromise | |||
Dispatched when the underlying URLStream connection is opened. | URLFilePromise | |||
Dispatched when a block of data is available to be read from the underlying URLStream. | URLFilePromise | |||
Dispatched when a security error prevents the file download. | URLFilePromise |
isAsync | property |
isAsync:Boolean
[read-only] Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
Indicates whether the resource data is available asynchronously.
The isAsync property of a URLFilePrmise object is always true
since URL streams are inherently asynchronous.
Implementation
public function get isAsync():Boolean
relativePath | property |
relativePath:String
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
The path and file name of the created file, relative to the drop destination.
The path can include subdirectories, which are resolved based on the drop location. The subdirectories are created,
if needed. When including subdirectories, use the File.separator
constant to insert the
proper path separator character for the current operating system. Using the .. shortcut to navigate to a parent directory
is not allowed.
The file name does not need to be the same as the file name of the remote resource.
Implementation
public function get relativePath():String
public function set relativePath(value:String):void
request | property |
request:URLRequest
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
The URLRequest identifying the resource to be copied as the result of the drag-and-drop operation.
Implementation
public function get request():URLRequest
public function set request(value:URLRequest):void
URLFilePromise | () | Constructor |
public function URLFilePromise()
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
Creates a URLFilePromise object.
You must set the request
and relativePath
properties before
using this URLFilePromise object.
close | () | method |
public function close():void
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
Allows the AIR runtime to close the data source at the appropriate time during the drag-and-drop operation.
Do not call this function in your application logic.
open | () | method |
public function open():IDataInput
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
Allows the AIR runtime to open the data source at the appropriate time during the drag-and-drop operation.
Do not call this function in your application logic.
ReturnsIDataInput |
reportError | () | method |
public function reportError(e:ErrorEvent):void
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
Allows the AIR runtime to report errors that occur during the drag-and-drop operation.
The URLFilePromise object redispatches any error events reported. Do not call this function in your application logic.
Parameters
e:ErrorEvent |
complete | Event |
flash.events.Event
property Event.type =
flash.events.Event.COMPLETE
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
Dispatched when the data for the file has been fully downloaded.
Note: The AIR runtime uses this event to manage the asynchronous data retrieval process. Typically, there is no need for your application to take any action in response to this event.
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. |
httpResponseStatus | Event |
flash.events.HTTPStatusEvent
property HTTPStatusEvent.type =
flash.events.HTTPStatusEvent.HTTP_RESPONSE_STATUS
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
Dispatched for HTTP requests to report the response headers.
Unlike thehttpStatus
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. |
httpStatus | Event |
flash.events.HTTPStatusEvent
property HTTPStatusEvent.type =
flash.events.HTTPStatusEvent.HTTP_STATUS
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
Dispatched for HTTP requests to report the request status code.
TheHTTPStatusEvent.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. |
ioError | Event |
flash.events.IOErrorEvent
property IOErrorEvent.type =
flash.events.IOErrorEvent.IO_ERROR
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
Dispatched when an IOError prevents the file download.
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. |
open | Event |
flash.events.Event
property Event.type =
flash.events.Event.OPEN
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
Dispatched when the underlying URLStream connection is opened.
Note: The AIR runtime uses this event to manage the asynchronous data retrieval process. Typically, there is no need for your application to take any action in response to this event.
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. |
progress | Event |
flash.events.ProgressEvent
property ProgressEvent.type =
flash.events.ProgressEvent.PROGRESS
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
Dispatched when a block of data is available to be read from the underlying URLStream.
Note: The AIR runtime uses this event to manage the asynchronous data retrieval process. Typically, there is no need for your application to take any action in response to this event.
Defines the value of thetype
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. |
securityError | Event |
flash.events.SecurityErrorEvent
property SecurityErrorEvent.type =
flash.events.SecurityErrorEvent.SECURITY_ERROR
Language Version: | ActionScript 3.0 |
Runtime Versions: | AIR 2.0 |
Dispatched when a security error prevents the file download.
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. |
Thu Dec 6 2018, 01:12 PM -08:00