air.desktop.URLFilePromise - Adobe® Flex® 4 Language Reference (Flex 4)

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:

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.*;

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
		prototype : Object [static] A reference to the prototype object of a class or function object.	Object
		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

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