| 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
importstatement to your ActionScript 3.0 code:import air.desktop.*;
More examples
Related API Elements
Clipboard class
ClipboardFormats class
NativeDragManager class
URLStream class
URLRequest class
Hide Inherited Public Properties
Show Inherited Public Properties| Property | Defined By | ||
|---|---|---|---|
 | constructor : Object
A reference to the class object or constructor function for a given object instance. | Object | |
| 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.Eventproperty 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.HTTPStatusEventproperty 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.HTTPStatusEventproperty 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.IOErrorEventproperty 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.Eventproperty 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.ProgressEventproperty 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.SecurityErrorEventproperty 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. |
Wed Nov 21 2018, 06:34 AM -08:00