| Package | flash.desktop |
| Interface | public interface IFilePromise |
| Implementors | MediaPromise, URLFilePromise |
| Language Version: | ActionScript 3.0 |
| Runtime Versions: | AIR 2 |
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.
More examples
Related API Elements
| 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 | ||
|---|---|---|---|
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 | ||
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():StringThrows
ArgumentError — if the relative path uses .. shortcuts to traverse one or more parent directories
of the drop target.
|
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).
ReturnsIDataInput — 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.
|
Thu Dec 4 2014, 05:50 PM -08:00