ApplicationUpdater  - AS3

設定 delay 和 updateURL 屬性值的組態設定檔所在位置。如果這個屬性指向不存在的檔案，呼叫 initialize() 方法將導致擲出錯誤。

以下是組態設定檔的樣本：

 <?xml version="1.0" encoding="utf-8"?> 
         <configuration xmlns="http://ns.adobe.com/air/framework/update/configuration/1.0" >
           <url>app:/server/update.xml</url>
           <delay>1</delay>
        </configuration>

除了載入組態設定檔，您也可以使用 ActionScript 程式碼，設定 delay 和 updateURL 屬性。

相關 API 元素

更新程式的內部狀態。這個屬性可以設定成下列的值：

• "UNINITIALIZED" - 更新程式尚未初始化。

• "INITIALIZING" - 更新程式正在初始化。

• "READY" - 更新程式已完成初始化。

• "BEFORE_CHECKING" - 更新程式尚未檢查更新描述器檔案。

• "CHECKING" - 更新程式正在檢查更新描述器檔案。

• "AVAILABLE" - 已有可用的更新描述器檔案。

• "DOWNLOADING" - 更新程式正在下載 AIR 檔。

• "DOWNLOADED" - 更新程式已經下載 AIR 檔。

• "INSTALLING" - 更新程式正在安裝 AIR 檔。

• "PENDING_INSTALLING" - 更新程式已完成初始化，且目前尚有擱置的更新。

應用程式的目前版本。這個屬性是在 initialize() 方法呼叫期間所設定。其值設定為應用程式描述器檔案提供的版本。

定期檢查新的更新之天數間隔。

值為 0 (預設值) 代表計時器非作用中，因而不會執行定期檢查。您可以透過這個屬性或是組態設定檔來設定其值。如果同時透過這兩種方式設定其值，將使用以此屬性設定的值。

預設值為 0。

是否為成功更新後第一次執行 (true = 是，false = 否)。更新程式會在 initialize() 方法呼叫期間設定此值。若因版本變更而需要移轉資料，開發人員即應檢查 isFirstRun 是否已設定為 true。

相關 API 元素

更新程式用來執行版本比較的函數。根據預設，更新架構會進行版本比較，以偵測來自遠端網站的版本是否比已安裝應用程式的版本新。但是，預設的比較方式有時並不符合開發人員的版本設定配置。設定這個屬性可提供另一函數以進行比較。

預設的比較函數接受 x.y.z 之類的版本，其中 x、y 和 z 可包含字母及數字。預設的比較函數也能辨識某些特殊狀況。如果測試函數在版本字串中發現 "alpha"、"beta" 或 "rc"，其順序即為 alpha < beta < rc。

appUpdate.isNewerVersionFunction = customFn; 

function customFn (currentVersion:String, updateVersion:String):Boolean 
{
    return updateVersion > currentVersion;
}

應用程式儲存目錄先前的位置 (若該位置於更新後有所變更)。經由憑證移轉方式進行升級後，應用程式儲存目錄的位置就會變更。如果未經憑證移轉，使用者更新應用程式將不會造成應用程式儲存目錄變更，此時這個屬性即設定為 null。這個屬性是在 initialize() 方法呼叫期間所設定。

如果開發人員使用 ADT 搭配 -migrate 選項封裝 AIR 檔，即可使用新的憑證來簽署新版本的 AIR 應用程式。新版本的 AIR 應用程式若是使用新的簽署憑證，應用程式的本機儲存目錄將隨著使用者安裝新版本而變更。利用這個屬性可將舊的應用程式儲存目錄中的資料傳輸到新的應用程式儲存目錄 (File.applicationStorageDirectory)。如需詳細資訊，請參閱「Adobe AIR 開發人員指南」中，「使用命令列工具建立 AIR 應用程式」一章的「簽署 AIR 檔以變更應用程式憑證」。

應用程式的上一個版本。這個屬性是在 initialize() 方法呼叫期間所設定。傳回應用程式升級前的「上一個版本」(只有在 isfirstRun 為 true 時才會設定)；否則將設定為 null。

從更新 URL 下載之更新描述器檔案的內容。當更新程式物件傳送 updateStatus 事件後，這個屬性才為非 null。

更新描述器檔案的位置。接受任何有效的 URLRequest 路徑位置。更新程式必要的強制性設定惟獨此項。您可以透過這個屬性或是組態設定檔來設定更新 URL。如果同時透過這兩種方式設定其值，更新程式會使用以此屬性設定的值。

是否有延緩 (包括安裝失敗) 的更新 (true = 是，false = 否)。更新程式會在 initialize() 方法呼叫期間設定這個屬性。使用 wasPendingUpdate 和 isFirstRun 屬性可檢查是否有任何更新安裝失敗 (若 wasPendingUpdate 設定為 true 且 isFirstRun 設定為 false 即表示有此情況)。

相關 API 元素

建構函數。

取消更新程序。呼叫此方法將會取消任何等候中的下載、刪除任何下載不完全的檔案，並重新啟動定期檢查計時器。

只要更新程式不是處於 "UNINITIALIZED" 或 "INITIALIZING" 狀態，隨時皆可取消更新程序。若為 "UNINITIALIZED" 或 "INITIALIZING" 狀態，呼叫後不會執行任何動作。

非同步下載和解譯更新描述器檔案。呼叫此方法會使更新程式進入 "CHECKING" 狀態。應僅在 checkForUpdate 事件已取消的情況下才呼叫此方法。

此方法只會在更新程式處於 "BEFORE_CHECKING" 狀態時執行。

啟動更新程序。呼叫此方法並不會停止定期計時器，但此方法會偵測是否有更新程序正在執行，並將略過目前的程序循環。

此方法只會在目前狀態為 "READY" 時執行。

此方法可能導致更新程式物件傳送下列事件：

非同步下載更新檔案。呼叫此方法會使更新程式進入 "DOWNLOADING" 狀態。當 StatusUpdateEvent.UPDATE_STATUS 事件已取消且該事件的 available 屬性設定為 true 時，才需要呼叫此方法。

此方法只會在目前狀態為 "AVAILABLE" 時執行。

初始化更新程式。呼叫此方法將會執行下列動作：

1. 初始化更新架構，以無訊息方式同步安裝任何擱置的更新。在應用程式啟動時即應呼叫此方法，因為這可能會重新啟動應用程式。

2. 檢查是否有延緩的更新並加以安裝。

3. 如果先前的更新曾發生錯誤，即清除儲存區內的更新檔案和版本資訊。

4. 如果定期計時器延遲已到期，即啟動更新程序；否則將啟動定期計時器。然而，若是使用 AIR Debug Launcher (ADL) 應用程式來測試應用程式，試圖更新應用程式就會產生 IllegalOperationError 例外。

使用本機 AIR 檔啟動更新程序。

若有更新程序正在執行 (處於 "DOWNLOADED" 以外的狀態)，呼叫此方法將毫無作用。

這項功能對於已將應用程式描述器檔案中的 customUpdateUI 元素設定為 true 的應用程式來說很有用。

使用 AIR Debug Launcher (ADL) 應用程式測試應用程式時，呼叫此方法會產生 IllegalOperationError 例外。

參數

安裝更新檔案。呼叫此方法會使更新程式進入 "INSTALLING" 狀態，且唯有在 downLoadComplete 事件已取消的情況下才需要呼叫此方法。

待更新程式處於 "DOWNLOADED" 狀態時，再呼叫此方法。若為任何其他狀態，呼叫後不會執行任何動作。

使用 AIR Debug Launcher (ADL) 應用程式測試應用程式時，呼叫此方法會產生 IllegalOperationError 例外。

在呼叫 installUpdate() 方法後，將要安裝更新之前傳送。有時候，此時暫且不要安裝更新會比較妥當，因為執行階段若結束應用程式準備安裝更新，可能導致使用者遺失所有目前的工作成果。

呼叫此事件的 preventDefault() 方法便能延緩到下次重新啟動才安裝。如果您呼叫了 preventDefault() 方法，則此應用程式工作階段期間將無法再啟動其他更新程序 (藉由呼叫 installUpdate() 方法或因定期檢查而引發)。

ApplicationUpdater 元件庫預設的行為是下載更新描述器檔案。您可以呼叫 preventDefault() 方法取消這項行為。

這個事件具有下列屬性：

在更新程式嘗試下載更新描述器檔案 (更新程序將要開始) 之前傳送。直接呼叫 checkNow() 方法或定期檢查計時器已到期時，更新程式便會傳送此事件。

這個事件具有下列屬性：

當更新檔案下載完成時傳送。

此事件通常是用來顯示訊息，以詢問使用者是否要繼續安裝更新。

ApplicationUpdater 元件庫預設的行為是自動呼叫 installUpdate() 方法。

這個事件具有下列屬性：

若在連線或下載更新檔案時發生錯誤，便會傳送。若為無效的 HTTP 狀態 (例如「404 - 找不到檔案」)，也將傳送此事件。

一旦傳送此事件，即自動重新啟動定期計時器 (如果延遲值大於 0)。

DownloadErrorEvent 物件的 errorID 屬性為整數，用以定義錯誤資訊 (請參閱下表)。另外可能還有 subErrorID 屬性包含了更多的錯誤資訊。

在呼叫 downloadUpdate() 方法及建立伺服器連線之後傳送。使用 ApplicationUpdater 元件庫時，您可以透過此事件的事件處理常式，顯示進度列向使用者報告下載進度。

這個事件具有下列屬性：

若在初始化或更新程序期間發生錯誤 (發生未預期的事件)，便會傳送。

這個事件具有下列屬性：

若在驗證 installFromAIRFile() 方法呼叫中的 airFile 參數所傳遞的檔案時發生錯誤，便會傳送。

在更新程式成功驗證 installFromAIRFile() 方法呼叫中的檔案之後傳送。

這個事件具有下列屬性：

在初始化完成後傳送。

這個事件具有下列屬性：

下載更新檔案時傳送。

這個事件具有下列屬性：

若在嘗試下載或剖析更新描述器檔案時發生錯誤，便會傳送。

更新程式一旦傳送此事件，即自動重新啟動定期計時器 (如果延遲設定大於 0)。應用程式最好在更新程式傳送新的 checkForUpdate 事件時，隱藏任何錯誤對話方塊。

在更新程式成功下載並解譯更新描述器檔案之後傳送。

預設的行為是在 StatusUpdateEvent 物件的 available 屬性設定為 true 時，開始下載更新。唯有使用 ApplicationUpdater 類別的情況下才能制止預設的行為，若是使用 ApplicationUpdatorUI 類別則不可行。

這個事件具有下列屬性：