实现 IFilePromise 接口

Adobe AIR 2 和更高版本

在文件释放中使用同步数据提供程序
在文件释放中使用异步数据提供程序

若要为不能使用 URLFilePromise 对象访问的资源提供文件释放，可以在自定义类中实现 IFilePromise 接口。一旦放置文件释放后，IFilePromise 接口就会定义由 AIR 运行时访问要写入到文件中的数据所用的方法和属性。

IFilePromise 实现将为该文件释放提供数据的另一个对象传递到 AIR 运行时。此对象必须实现 AIR 运行时用于读取数据的 IDataInput 接口。例如，可实现 IFilePromise 的 URLFilePromise 类使用 URLStream 对象作为数据提供程序。

AIR 可以同步读取数据，也可以异步读取数据。IFilePromise 实现通过返回 isAsync 属性中的相应值来报告支持哪种访问模式。如果提供异步数据访问，则数据提供程序对象必须实现 IEventDispatcher 接口并调度必要的事件，例如 open 、 progress 和 complete 。

可使用自定义类或以下内置类之一作为文件释放的数据提供程序：

ByteArray（同步）
FileStream（同步或异步）
Socket（异步）
URLStream（异步）

要实现 IFilePromise 接口，必须为下列函数和属性提供代码：

open():IDataInput — 从读取的已释放文件的数据返回数据提供程序对象。该对象必须实现 IDataInput 接口。如果异步提供数据，对象还必须实现 IEventDispatcher 接口并调度必要的事件（请参阅在文件释放中使用异步数据提供程序）。
get relativePath():String — 提供已创建文件的路径，包括文件名。此路径被解析为相对于由拖放操作中用户选择的放置位置。要确保此路径使用适用于主机操作系统的适当分隔符，请在指定包含目录的路径时使用 File.separator 常量。您可以添加 setter 函数或使用构造函数参数来允许在运行时设置路径。
get isAsync():Boolean — 通知 AIR 运行时数据提供程序对象是异步提供数据还是同步提供数据。
close():void — 当完全读取数据时由运行时调用（否则将出现阻止进一步读取的错误）。可使用此函数清除资源。
reportError( e:ErrorEvent ):void — 在读取数据出错时由运行时调用。

在涉及文件释放的拖放操作期间，所有 IFilePromise 方法都由运行时调用。通常，应用程序逻辑不应直接调用上述任何方法。

在文件释放中使用同步数据提供程序

实现 IFilePromise 接口最简单的方法是使用同步数据提供程序对象，例如 ByteArray 或同步 FileStream。在下面的示例中，创建一个 ByteArray 对象，用数据填充它，并在调用 open() 方法时返回。

package 
{ 
    import flash.desktop.IFilePromise; 
    import flash.events.ErrorEvent; 
    import flash.utils.ByteArray; 
    import flash.utils.IDataInput; 
     
    public class SynchronousFilePromise implements IFilePromise 
    { 
        private const fileSize:int = 5000; //size of file data 
        private var filePath:String = "SynchronousFile.txt"; 
         
        public function get relativePath():String 
        { 
            return filePath; 
        } 
         
        public function get isAsync():Boolean 
        { 
            return false; 
        } 
         
        public function open():IDataInput 
        { 
            var fileContents:ByteArray = new ByteArray(); 
             
            //Create some arbitrary data for the file 
            for( var i:int = 0; i < fileSize; i++ ) 
            { 
                fileContents.writeUTFBytes( 'S' ); 
            } 
             
            //Important: the ByteArray is read from the current position             
            fileContents.position = 0; 
            return fileContents; 
        } 
         
        public function close():void 
        { 
            //Nothing needs to be closed in this case. 
        } 
         
        public function reportError(e:ErrorEvent):void 
        { 
            trace("Something went wrong: " + e.errorID + " - " + e.type + ", " + e.text ); 
        } 
    } 
}

实际上，同步文件释放的效用很受限。如果数据量很小，您可以在临时目录中轻松创建一个文件，将普通文件列表数组添加到拖放剪贴板。另一方面，如果数据量很大或生成数据的计算成本很高，则长的同步进程是必需的。长的同步进程会在明显较长的时间内阻止 UI 更新，使应用程序看起来像无响应一样。若要避免此问题，您可以创建一个由计时器驱动的异步数据提供程序。

在文件释放中使用异步数据提供程序

使用异步数据提供程序对象时，IFilePromise isAsync 属性必须为 true ，并且由 open() 方法返回的对象必须实现 IEventDispatcher 接口。运行时侦听多个替代事件，以便可以使用不同的内置对象作为数据提供程序。例如， progress 事件由 FileStream 和 URLStream 对象调度，而 socketData 事件由 Socket 对象调度。运行时从所有这些对象侦听适当的事件。

下列事件推动从数据提供程序对象读取数据的进程：

Event.OPEN — 通知运行时数据源已准备好。
ProgressEvent.PROGRESS — 通知运行时数据可用。运行时将从数据提供程序对象读取可用的数据量。
ProgressEvent.SOCKET_DATA — 通知运行时数据可用。 socketData 事件由基于 Socket 的对象调度。对于其他对象类型，您应调度 progress 事件。（运行时同时侦听这两个事件以检测何时可以读取数据。）
Event.COMPLETE — 通知运行时已读取所有数据。
Event.CLOSE — 通知运行时已读取所有数据。（运行时同时侦听 close 和 complete 来实现此目的。）
IOErrorEvent.IOERROR — 通知运行时读取数据时出错。运行时终止文件创建并调用 IFilePromise close() 方法。
SecurityErrorEvent.SECURITY_ERROR — 通知运行时出现安全性错误。运行时终止文件创建并调用 IFilePromise close() 方法。
HTTPStatusEvent.HTTP_STATUS — 运行时同时使用它和 httpResponseStatus ，以确保可用数据表示所需内容，而不会显示错误消息（例如 404 页面）。基于 HTTP 协议的对象应调度此事件。
HTTPStatusEvent.HTTP_RESPONSE_STATUS — 运行时同时使用它和 httpStatus ，以确保可用数据表示所需内容。基于 HTTP 协议的对象应调度此事件。

数据提供程序应按照以下顺序调度这些事件：

open 事件
progress 或 socketData 事件
complete 或 close 事件

注：内建对象（FileStream、Socket 和 URLStream）自动调度相应的事件。

以下示例使用自定义异步数据提供程序创建一个文件释放。数据提供程序类扩展了 ByteArray（以实现 IDataInput 支持）并实现 IEventDispatcher 接口。在每个 timer 事件发生时，对象会生成大量数据，并调度 progress 事件以通知运行时这些数据可用。当生成的数据足够多时，对象调度 complete 事件。

package 
{ 
import flash.events.Event; 
import flash.events.EventDispatcher; 
import flash.events.IEventDispatcher; 
import flash.events.ProgressEvent; 
import flash.events.TimerEvent; 
import flash.utils.ByteArray; 
import flash.utils.Timer; 
 
[Event(name="open", type="flash.events.Event.OPEN")] 
[Event(name="complete",  type="flash.events.Event.COMPLETE")] 
[Event(name="progress", type="flash.events.ProgressEvent")] 
[Event(name="ioError", type="flash.events.IOErrorEvent")] 
[Event(name="securityError", type="flash.events.SecurityErrorEvent")] 
public class AsyncDataProvider extends ByteArray implements IEventDispatcher 
{ 
    private var dispatcher:EventDispatcher = new EventDispatcher(); 
    public var fileSize:int = 0; //The number of characters in the file 
    private const chunkSize:int = 1000; //Amount of data written per event 
    private var dispatchDataTimer:Timer = new Timer( 100 ); 
    private var opened:Boolean = false; 
     
    public function AsyncDataProvider() 
    { 
        super(); 
        dispatchDataTimer.addEventListener( TimerEvent.TIMER, generateData ); 
    } 
 
    public function begin():void{ 
        dispatchDataTimer.start(); 
    } 
     
    public function end():void 
    { 
        dispatchDataTimer.stop(); 
    } 
    private function generateData( event:Event ):void 
    { 
        if( !opened ) 
        { 
            var open:Event = new Event( Event.OPEN ); 
            dispatchEvent( open );     
            opened = true; 
        } 
        else if( position + chunkSize < fileSize ) 
        { 
            for( var i:int = 0; i <= chunkSize; i++ ) 
            { 
                writeUTFBytes( 'A' ); 
            } 
            //Set position back to the start of the new data 
            this.position -= chunkSize; 
            var progress:ProgressEvent = 
                new ProgressEvent( ProgressEvent.PROGRESS, false, false, bytesAvailable, bytesAvailable + chunkSize); 
            dispatchEvent( progress ) 
        } 
        else 
        { 
            var complete:Event = new Event( Event.COMPLETE ); 
            dispatchEvent( complete );         
        } 
    } 
     //IEventDispatcher implementation 
    public function addEventListener(type:String, listener:Function, useCapture:Boolean=false, priority:int=0, useWeakReference:Boolean=false):void 
    { 
        dispatcher.addEventListener( type, listener, useCapture, priority, useWeakReference ); 
    } 
     
    public function removeEventListener(type:String, listener:Function, useCapture:Boolean=false):void 
    { 
        dispatcher.removeEventListener( type, listener, useCapture ); 
    } 
     
    public function dispatchEvent(event:Event):Boolean 
    { 
        return dispatcher.dispatchEvent( event ); 
    } 
     
    public function hasEventListener(type:String):Boolean 
    { 
        return dispatcher.hasEventListener( type ); 
    } 
     
    public function willTrigger(type:String):Boolean 
    { 
        return dispatcher.willTrigger( type ); 
    } 
} 
}

注：由于示例中的 AsyncDataProvider 类扩展了 ByteArray，所以它无法同时扩展 EventDispatcher。为实现 IEventDispatcher 接口，该类使用内部 EventDispatcher 对象并将 IEventDispatcher 方法调用转发给该内部对象。您也可以扩展 EventDispatcher 并实现 IDataInput（或同时实现两个接口）。

异步 IFilePromise 实现与同步实现几乎是相同的。主要区别是 isAsync 返回 true ，而 open() 方法返回异步数据对象：

package 
{ 
    import flash.desktop.IFilePromise; 
    import flash.events.ErrorEvent; 
    import flash.events.EventDispatcher; 
    import flash.utils.IDataInput; 
     
    public class AsynchronousFilePromise extends EventDispatcher implements IFilePromise 
    { 
        private var fileGenerator:AsyncDataProvider; 
        private const fileSize:int = 5000; //size of file data 
        private var filePath:String = "AsynchronousFile.txt"; 
                 
        public function get relativePath():String 
        { 
            return filePath; 
        } 
         
        public function get isAsync():Boolean 
        { 
            return true; 
        } 
         
        public function open():IDataInput 
        { 
            fileGenerator = new AsyncDataProvider(); 
            fileGenerator.fileSize = fileSize; 
            fileGenerator.begin(); 
            return fileGenerator; 
        } 
         
        public function close():void 
        { 
            fileGenerator.end(); 
        } 
         
        public function reportError(e:ErrorEvent):void 
        { 
            trace("Something went wrong: " + e.errorID + " - " + e.type + ", " + e.text ); 
        } 
    } 
}