flash.desktop.IFilePromise - Adobe® Flex® 4 Language Reference (Flex 4)

Package	flash.desktop
Interface	public interface IFilePromise
Implementors	URLFilePromise

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

The IFilePromise interface defines the interface used by the AIR runtime to read data for a file promise.

A file promise is a drag-and-drop clipboard format that allows a user to drag a file that does not yet exist out of an AIR application. AIR uses the methods and properties defined by the IFilePromise interface to access the data to be written when the file promise is dropped.

When a file promise is dropped on a suitable target, AIR calls the IFilePromise open() method. The implementation of this method must return the data provider as an object that implements the IDataInput interface. The provider object can be one of the built-in classes, such as ByteArray, FileStream, Socket, and URLStream, or it can be a custom class.

If the data from the data provider is accessed synchronously, such as with a ByteArray, AIR reads the amount of data indicated by the IDataInput bytesAvailable property and writes it to the destination file.

If the data from the data provider is accessed asynchronously, such as with a Socket, AIR uses events dispatched by the provider to regulate the process of reading the data and writing it to the file. Data is read at each progress event until a complete or a close event is received. The runtime listens for the following events (but a data provider does not need to dispatch every event):

Event.OPEN
ProgressEvent.PROGRESS
ProgressEvent.SOCKET_DATA
Event.COMPLETE
Event.CLOSE
IOErrorEvent.IOERROR
SecurityErrorEvent.SECURITY_ERROR
HTTPStatusEvent.HTTP_STATUS
HTTPStatusEvent.HTTP_RESPONSE_STATUS

Custom data provider classes should dispatch either a progress event or a socketData event when data is available. Likewise, either a complete or a close event should be dispatched when all the requested data has been read. The error events inform the runtime that the data transfer has failed and should be aborted. The other events should be dispatched as appropriate to aid in error handling and in debugging application logic.

The methods defined by IFilePromise are only intended to be called by the AIR runtime after a drag and drop operation has completed. Developers should not typically call these methods from their own code.

Note: The URLFilePromise class, available in the air.desktop library implements the IFilePromise interface and uses the URLStream as a data provider. The air.desktop library is included as separate SWF and SWC files in the AIR SDK.

	Property	Defined By
		isAsync : Boolean [read-only] Indicates whether asynchronous data transfer is supported.	IFilePromise
		relativePath : String [read-only] The relative path and file name of the file that will be created by this file promise.	IFilePromise

	Method	Defined By
		close():void Called by the AIR runtime when it has finished reading all data.	IFilePromise
		open():IDataInput Returns the data provider object.	IFilePromise
		reportError(e:ErrorEvent):void Called by the AIR runtime to inform the IFilePromise implementation of errors that occur when reading data from the data provider object.	IFilePromise

isAsync

property

isAsync:Boolean [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

Indicates whether asynchronous data transfer is supported.

If true, then the data provider object returned by the open() method must implement the IEventDispatcher interface (or extend a class implementing this interface). The data transfer is driven by progress or socketData events. AIR waits for these data progress events until a complete or a close event is dispatched.

If isAsync returns false, then the AIR runtime assumes that all data is available immediately. In this case, the runtime reads the bytesAvailable property of the data provider object to determine the amount of data available and synchronously reads that amount of data.

Implementation
public function get isAsync():Boolean

relativePath

property

relativePath:String [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

The relative path and file name of the file that will be created by this file promise.

This property must provide a valid path or an argument error is thrown when the file promise is dropped.

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. If attempted, an argument error is thrown. Invalid file system characters are stripped from the path without throwing an error.

Note: To allow client code to set the path, you can implement a setter function with the signature: function set relativePath( value:String ):void.

Implementation
public function get relativePath():String

Throws

ArgumentError — if the relative path uses .. shortcuts to traverse one or more parent directories of the drop target.

Method Detail

close

()

method

public function close():void

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

Called by the AIR runtime when it has finished reading all data.

No methods will be called on the object reference returned by open() after close() has been called. The data provider object can be safely destroyed.

open

()

method

public function open():IDataInput

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

Returns the data provider object.

The data provider object must implement the IDataInput interface, which defines methods for reading data. If the IFilePromise isAsync property returns true, then the data provider object must also implement the IEventDispatcher interface. The following built-in classes can be used as a data provider:

ByteArray (synchronous)
FileStream (synchronous or asynchronous)
Socket (asynchronous)
URLStream (asynchronous)

You can also provide an object of a custom class that implements the required interfaces (or extends another class that implements them).

Returns

IDataInput — IDataInput An object implementing the IDataInput interface. If the data is provided asynchronously, the returned object must also implement the IEventDispatcher interface.

reportError

()

method

public function reportError(e:ErrorEvent):void

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 2

Called by the AIR runtime to inform the IFilePromise implementation of errors that occur when reading data from the data provider object.

Parameters

e:ErrorEvent — The error event containing detailed error information.