| 套件 | flash.desktop |
| 介面 | public interface IFilePromise |
| 實作者 | MediaPromise, URLFilePromise |
| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 2 |
檔案承諾是一種拖放剪貼簿格式，可以讓使用者拖曳 AIR 應用程式外尚不存在的檔案。AIR 會使用 IFilePromise 介面定義的各種方法和屬性，存取當放置檔案承諾時要寫入的資料。
當檔案承諾被放置到適當目標上，AIR 會呼叫 IFilePromise open() 方法。實作這種方法必須將資料提供者，以一個會實作 IDataInput 介面的物件形式傳回。提供者物件可以是內建的類別之一，例如 ByteArray、FileStream、Socket 以及 URLStream，也可以是一個自訂類別。
如果資料提供者的資料是以同步方式存取，例如使用 ByteArray，則 AIR 會讀取由 IDataInput bytesAvailable 屬性指示的資料量，然後寫入目的地檔案中。
如果資料提供者的資料是以非同步方式存取的，例如利用 Socket，則 AIR 會使用提供者傳送的事件來規範讀取資料以及寫入檔案的程序。資料是在每一個 progress 事件中讀取，直到收到 complete 或 close 事件為止。執行階段會偵聽下列事件 (但是資料提供者不需要傳送每個事件)：
- Event.OPEN
- ProgressEvent.PROGRESS
- ProgressEvent.SOCKET_DATA
- Event.COMPLETE
- Event.CLOSE
- IOErrorEvent.IOERROR
- SecurityErrorEvent.SECURITY_ERROR
- HTTPStatusEvent.HTTP_STATUS
- HTTPStatusEvent.HTTP_RESPONSE_STATUS
當有可用的資料時，自訂資料提供者類別應該會傳送 progress 事件或 socketData 事件。同樣地，當所有要求的資料都已讀取後，會傳送 complete 或 close 事件。error 事件會通知執行階段，資料傳送已經失敗而且應該中止。適當時應該會傳送其他事件，以便協助處理錯誤以及進行應用程式邏輯的除錯。
IFilePromise 定義的方法，其唯一用途就是在拖放作業完成之後，讓 AIR 執行階段呼叫。開發人員通常不應該從自己的程式碼來呼叫這些方法。
注意：在 air.desktop 元件庫中提供的 URLFilePromise 類別，可實作 IFilePromise 介面並使用 URLStream 做為資料提供者。air.desktop 元件庫以獨立的 SWF 及 SWC 檔案包括在 AIR SDK 中。
相關 API 元素
| 屬性 | 定義自 | ||
|---|---|---|---|
| isAsync : Boolean [唯讀]
指出是否支援非同步資料傳送。 | IFilePromise | ||
| relativePath : String [唯讀]
這個檔案承諾即將建立之檔案的相對路徑和名稱。 | IFilePromise | ||
| 方法 | 定義自 | ||
|---|---|---|---|
讀取所有資料之後，由AIR 執行階段呼叫。 | IFilePromise | ||
傳回 data provider 物件。 | IFilePromise | ||
由 AIR 執行階段呼叫，將從 data provider 物件讀取資料時發生的錯誤，通知 IFilePromise 實作錯誤。 | IFilePromise | ||
isAsync | 屬性 |
isAsync:Boolean [唯讀] | 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 2 |
指出是否支援非同步資料傳送。
如果為 true，則 open() 方法傳回的 data provider 物件必須實作 IEventDispatcher 介面 (或擴充一個會實作此介面的類別)。資料傳送是由 progress 或 socketData 事件推動的。AIR 會等候這些資料 progress 事件，直到傳送 complete 或 close 事件為止。
如果 isAsync 傳回 false，則 AIR 執行階段會假設可以立即取得所有資料。在這個案例中，執行階段會讀取 data provider 物件的 bytesAvailable 屬性，藉以判斷可以取得的資料數量，然後同步讀取這個數量的資料。
實作
public function get isAsync():Boolean relativePath | 屬性 |
relativePath:String [唯讀] | 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 2 |
這個檔案承諾即將建立之檔案的相對路徑和名稱。
此屬性必須提供有效的路徑。否則放置檔案承諾時，就會發生引數錯誤。
路徑可以包含子目錄，這會根據放置位置進行解析。需要時會建立子目錄。包括子目錄時，請使用 File.separator 常數，為目前的作業系統插入正確的路徑分隔符號字元。不允許使用 .. 捷徑瀏覽上層目錄。如果嘗試這麼做，便會擲回引數錯誤。去除路徑中的無效檔案系統字元，才不會擲回錯誤。
注意：若要允許用戶端程式碼設定路徑，您可以實作一個 setter 函數並加上簽章：function set relativePath( value:String ):void。
實作
public function get relativePath():String擲回值
ArgumentError — 如果相對路徑使用 .. 捷徑跨過放置目標的一或多個上層目錄。
|
close | () | 方法 |
public function close():void| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 2 |
讀取所有資料之後，由AIR 執行階段呼叫。
呼叫 close() 之後，不會在 open() 傳回的物件參考上呼叫任何方法。data provider 物件可以放心刪除。
open | () | 方法 |
public function open():IDataInput| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 2 |
傳回 data provider 物件。
data provider 物件必須實作 IDataInput 介面，它會定義資料的讀取方法。如果 IFilePromise isAsync 屬性傳回 true，則 data provider 物件也必須實作 IEventDispatcher 介面。以下內建的類別可以做為資料提供者：
- ByteArray (同步)
- FileStream (同步或非同步)
- Socket (非同步)
- URLStream (非同步)
您也可以提供自訂類別的物件，用以實作必要的介面 (或者擴充其他可以實作介面的類別)。
傳回值IDataInput — IDataInput - 一種實作 IDataInput 介面的物件。如果以非同步的方式提供資料，則傳回的物件也必須實作 IEventDispatcher 介面。
|
reportError | () | 方法 |
public function reportError(e:ErrorEvent):void| 語言版本: | ActionScript 3.0 |
| 執行階段版本: | AIR 2 |
由 AIR 執行階段呼叫，將從 data provider 物件讀取資料時發生的錯誤，通知 IFilePromise 實作錯誤。
參數
e:ErrorEvent — 包含詳細錯誤資訊的錯誤事件。
|
Tue Jun 12 2018, 03:47 PM Z