air.desktop

# URLFilePromise - AS3

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 allows resources accessible at a URL to be dragged out of an AIR application as a file promise.

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:

1. Construct and initialize one or more URLFilePromise objects.
2. Add the URLFilePromise objects to an array.
3. Add the array to a new Clipboard object using the ClipboardFormat, `FILE_PROMISE_LIST`.
4. 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):

1. Select the File > Publish Settings command.
2. In the Flash panel, click the Settings button for ActionScript 3.0. Select Library Path.
3. 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.
4. Click the OK button.
5. Add the following `import` statement to your ActionScript 3.0 code: `import air.desktop.*;`

More examples

Dropping file promises

Related API Elements

IFilePromise interface
Clipboard class
ClipboardFormats class
NativeDragManager class
URLStream class
URLRequest class

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | 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

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | URLFilePromise() 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
|  | close():void Allows the AIR runtime to close the data source at the appropriate time during the drag-and-drop operation. | URLFilePromise
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | open():IDataInput Allows the AIR runtime to open the data source at the appropriate time during the drag-and-drop operation. | URLFilePromise
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | reportError(e:ErrorEvent):void Allows the AIR runtime to report errors that occur during the drag-and-drop operation. | URLFilePromise
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher
|  | complete | Dispatched when the data for the file has been fully downloaded. | URLFilePromise
|  | deactivate | [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher
|  | httpResponseStatus | Dispatched for HTTP requests to report the response headers. | URLFilePromise
|  | httpStatus | Dispatched for HTTP requests to report the request status code. | URLFilePromise
|  | ioError | Dispatched when an IOError prevents the file download. | URLFilePromise
|  | open | Dispatched when the underlying URLStream connection is opened. | URLFilePromise
|  | progress | Dispatched when a block of data is available to be read from the underlying URLStream. | URLFilePromise
|  | securityError | Dispatched when a security error prevents the file download. | URLFilePromise

Property Detail

### 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`
Constructor Detail

### 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.

Method Detail

### 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.

Returns

| `IDataInput`

### 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`

Event Detail

### complete

Event

Event Object Type: `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.

The `Event.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

Event Object Type: `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 the `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.

### httpStatus

Event

Event Object Type: `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.

The `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.

### ioError

Event

Event Object Type: `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 the `type` property of an `ioError` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`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

Event Object Type: `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.

The `Event.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

Event Object Type: `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 the `type` property of a `progress` event object.

This event has the following properties:

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

### securityError

Event

Event Object Type: `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.

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

This event has the following properties:

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

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00