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 元素

updater 的内部状态。此属性可设置为下列值：

• "UNINITIALIZED" — updater 尚未初始化。

• "INITIALIZING" — updater 正在初始化。

• "READY" — updater 已初始化。

• "BEFORE_CHECKING" — 尚未检查 updater 中是否有更新描述符文件。

• "CHECKING" — updater 正在检查是否有更新描述符文件。

• "AVAILABLE" — 更新描述符文件可用。

• "DOWNLOADING" — updater 正在下载 AIR 文件。

• "DOWNLOADED" — updater 已下载 AIR 文件。

• "INSTALLING" — updater 正在安装 AIR 文件。

• "PENDING_INSTALLING" — updater 已初始化，但存在未处理的更新。

应用程序的当前版本。在调用 initialize() 方法的过程中设置此属性。将其设置为应用程序描述符文件中的版本。

定期检查新更新的间隔天数。

值为 0（默认值）时表示计时器未处于活动状态，因此不进行任何定期检查。可以通过此属性或通过配置文件设置此值。使用这两种方法设置此值后，将使用以此属性设置的值。

默认值为 0。

这是否为成功更新之后的第一次运行，如果是，则为 (true)，否则为 (false)。updater 在调用 initialize() 方法的过程中设置此值。如果需要将数据从一个版本迁移到另一个版本，则开发人员应该核实 isFirstRun 已设置为 true。

相关 API 元素

updater 执行版本比较所应该使用的函数。默认情况下，更新框架进行版本比较，以检测远程站点的版本是否比所安装应用程序的版本新。但是，有时默认的比较并不符合开发人员的版本控制方案。设置此属性可提供进行比较的新函数。

默认的比较函数接受类似 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 打包 AIR 文件时使用 -migrate 选项，则该开发人员可以用新的证书为 AIR 应用程序的新版本签名。如果 AIR 应用程序的新版本使用新的签名证书，则用户安装新版本时，应用程序的本地存储目录将发生更改。使用此属性将数据从旧的应用程序存储目录转移到新的应用程序存储目录 (File.applicationStorageDirectory)。有关详细信息，请参阅《Adobe AIR 开发人员指南》中“使用命令行工具创建 AIR 应用程序”一章的“为 AIR 文件签名以更改应用程序证书”。

应用程序的原有版本。在调用 initialize() 方法的过程中设置此属性。返回应用程序升级之前的原有版本（仅当 isfirstRun 为 true 时设置）；否则将其设置为 null。

从更新 URL 下载的更新描述符文件的内容。只有在 updater 对象调度 updateStatus 事件之后，此属性才为非 null。

更新描述符文件的位置。可以接受对 URLRequest 路径有效的任何位置。这是 updater 所需的唯一一个必要设置。可以通过此属性或通过配置文件来设置更新 URL。使用这两种方法设置此值后，updater 将使用以此属性设置的值。

是否有被推迟的更新，即使安装失败，如果有，则为 (true)；否则为 false。updater 在调用 initialize() 方法的过程中设置此属性。使用 wasPendingUpdate 和 isFirstRun 属性检查更新是否未能安装（这种情况下 wasPendingUpdate 设置为 true，且 isFirstRun 设置为 false）。

相关 API 元素

构造函数。

取消更新过程。调用此方法将取消所有未处理的下载，删除所有不完整的下载文件，以及重新启动定期检查计时器。

除状态机处于“UNINITIALIZED”或“INITIALIZING”状态之外的任何时候都可以取消更新过程。在“UNINITIALIZED”或“INITIALIZING”状态下调用此方法时，它不会执行任何操作。

异步下载并解释更新描述符文件。调用此方法会将 updater 的状态前移至“CHECKING”。请仅在取消 checkForUpdate 事件后调用此方法。

只有 updater 为“BEFORE_CHECKING”状态时此方法才会执行。

启动更新过程。调用此方法不会使定期检查计时器停止；但是，此方法可以检测出更新过程正在运行中，并将跳过当前遍历。

只有当前状态为“READY”时此方法才会执行。

此方法可能导致 updater 对象调度以下事件：

异步下载更新文件。调用此方法会将状态机前移至“DOWNLOADING”。只有当 StatusUpdateEvent.UPDATE_STATUS 事件的 available 属性为 true 时取消该事件后才需要调用此方法。

只有当前状态为“AVAILABLE”时此方法才会执行。

初始化 updater。调用此方法可执行以下操作：

1. 它将初始化更新框架，以静默方式同步安装所有未处理的更新。由于此方法可能会重新启动应用程序，因此在应用程序启动过程中应该调用此方法。

2. 它检查是否有被推迟的更新，如果有将安装该更新。

3. 如果前一次更新有错误，则它将从存储区域中清除更新文件和版本信息。

4. 如果定期检查计时器延迟已到期，则它将启动更新过程；否则它将启动定期检查计时器。但是，在使用 AIR Debug Launcher (ADL) 应用程序测试某个应用程序时，尝试更新应用程序会导致 IllegalOperationError 异常。

使用本地 AIR 文件启动更新过程。

如果正在运行更新过程，则调用此方法不起作用（如果状态不是 "DOWNLOADED"）。

对于在应用程序描述符文件中将 customUpdateUI 元素设置为 true 的应用程序，此函数很有用。

在使用 AIR Debug Launcher (ADL) 应用程序测试某个应用程序时，调用此方法会导致 IllegalOperationError 异常。

参数

安装更新文件。调用此方法会将状态机前移至“INSTALLING”，且只有在取消 downLoadComplete 事件后才需要调用此方法。

请在 updater 为“DOWNLOADED”状态时调用此方法。在任何其他状态下调用此方法都不起作用。

在使用 AIR Debug Launcher (ADL) 应用程序测试某个应用程序时，调用此方法会导致 IllegalOperationError 异常。

调用 installUpdate() 方法之后，恰好在安装更新之前将调度此事件。某些情况下，运行时退出应用程序以安装更新时，用户可能会丢失所有当前工作，这种情况下最好阻止安装更新。

调用此事件的 preventDefault() 方法可将安装推迟到下一次重新启动。如果调用 preventDefault() 方法，则在此应用程序会话过程中不能再启动其他更新过程（通过调用 installUpdate() 方法或通过定期检查）。

ApplicationUpdater 库的默认行为是下载更新描述符文件。可以调用 preventDefault() 方法取消此行为。

此事件具有以下属性：

升级过程开始之前，恰好在 updater 尝试下载更新描述符文件之前将调度此事件。updater 调度此事件的原因可以是直接调用 checkNow() 方法或定期检查计时器到期。

此事件具有以下属性：

更新文件下载完毕时将调度此事件。

通常使用此事件显示一条消息，询问用户是否要继续安装更新。

ApplicationUpdater 库的默认行为是自动调用 installUpdate() 方法。

此事件具有以下属性：

如果在连接或下载更新文件时出错，将调度此事件。HTTP 状态无效（如“404 - 找不到文件”）时也会调度此事件。

调度此事件时，定期检查计时器将自动重新启动（如果延迟大于 0）。

DownloadErrorEvent 对象的 errorID 属性是一个整数，用于定义错误信息（请参阅下表）。此外，还具有另一个属性 subErrorID，该属性可能包含更多错误信息。

调用 downloadUpdate() 方法并建立到服务器的连接之后将调度此事件。使用 ApplicationUpdater 库时，可能希望此事件的事件处理函数显示进度栏，从而向用户报告下载进度。

此事件具有以下属性：

初始化过程中或更新过程中出错时（如果发生某种意外情况），将调度此事件。

此事件具有以下属性：

验证调用 installFromAIRFile() 方法过程中作为 airFile 参数传递的文件时，若出错，将调度此事件。

updater 成功验证调用 installFromAIRFile() 方法过程中的文件之后将调度此事件。

此事件具有以下属性：

初始化完成之后，将调度此事件。

此事件具有以下属性：

在下载更新文件时进行调度。

此事件具有以下属性：

如果尝试下载或分析更新描述符文件时出错，将调度此事件。

updater 调度此事件时，定期检查计时器将自动重新启动（如果延迟设置大于 0）。updater 调度新的 checkForUpdate 事件时，应用程序应该考虑隐藏所有错误对话框。

updater 成功下载并解释更新描述符文件之后，将调度此事件。

如果将 StatusUpdateEvent 对象的 available 属性设置为 true，则默认行为是开始下载更新。只有在使用 ApplicationUpdater 类时可以阻止默认行为，而使用 ApplicationUpdatorUI 类时不能。

此事件具有以下属性：