Packageflash.desktop
Interfacepublic interface IFilePromise
ImplementorsMediaPromise

Language version: ActionScript 3.0
Runtime version: 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):

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.

See also

flash.desktop.Clipboard
flash.desktop.ClipboardFormats
flash.desktop.NativeDragManager


Public Properties
 PropertyDefined 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
Public Methods
 MethodDefined by
  
Called by the AIR runtime when it has finished reading all data.
IFilePromise
  
Returns the data provider object.
IFilePromise
  
Called by the AIR runtime to inform the IFilePromise implementation of errors that occur when reading data from the data provider object.
IFilePromise
Property detail
isAsyncproperty
isAsync:Boolean  [read-only]

Language version: ActionScript 3.0
Runtime version: 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
relativePathproperty 
relativePath:String  [read-only]

Language version: ActionScript 3.0
Runtime version: 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 version: 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 version: 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:

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 version: 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.