Adobe® Flex® 4 Language Reference
Show Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
air.desktop 
URLFilePromise 
Packageair.desktop
Classpublic class URLFilePromise
InheritanceURLFilePromise Inheritance EventDispatcher Inheritance 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.*;

See also



Public Properties
 PropertyDefined By
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  AIR-only isAsync : Boolean
[read-only] Indicates whether the resource data is available asynchronously.
URLFilePromise
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  AIR-only relativePath : String
The path and file name of the created file, relative to the drop destination.
URLFilePromise
  AIR-only request : URLRequest
The URLRequest identifying the resource to be copied as the result of the drag-and-drop operation.
URLFilePromise
Public Methods
 MethodDefined By
  
Creates a URLFilePromise object.
URLFilePromise
 Inherited
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
 Inherited
Dispatches an event into the event flow.
EventDispatcher
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
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
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
  
Allows the AIR runtime to report errors that occur during the drag-and-drop operation.
URLFilePromise
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[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
 Inherited[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
Property Detail
AIR-only 

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
AIR-only 

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
AIR-only 

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
AIR-only 

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

AIR-only 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.

AIR-only 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

AIR-only 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
AIR-only 

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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe network object that has completed loading.
AIR-only 

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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
responseURLThe URL from which the response was returned.
responseHeadersThe response headers that the response returned, as an array of URLRequestHeader objects.
statusThe HTTP status code returned by the server.
targetThe network object receiving an HTTP status code.
AIR-only 

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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
statusThe HTTP status code returned by the server.
targetThe network object receiving an HTTP status code.
AIR-only 

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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
errorIDA reference number associated with the specific error (AIR only).
targetThe network object experiencing the input/output error.
textText to be displayed as an error message.
AIR-only 

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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe network object that has opened a connection.
AIR-only 

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:

PropertyValue
bubblesfalse
bytesLoadedThe number of items or bytes loaded at the time the listener processes the event.
bytesTotalThe total number of items or bytes that ultimately will be loaded if the loading process succeeds.
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe object reporting progress.
AIR-only 

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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe network object reporting the security error.
textText to be displayed as an error message.