flash.desktop

# IFilePromise - AS3

Package | flash.desktop
Interface | public interface IFilePromise
Implementors | MediaPromise, 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.

More examples

Dropping file promises
Implementing the IFilePromise interface

Related API Elements

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

Public Properties

| 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

Public Methods

| 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

Property Detail

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

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00