ApplicationUpdaterUI

Package	air.update
Class	public class ApplicationUpdaterUI
Inheritance	ApplicationUpdaterUI EventDispatcher Object

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

The ApplicationUpdaterUI class defines the basic functionality of the update framework for Adobe^® AIR^® applications, and it provides a default user interface. (The ApplicationUpdater class defines update functionality without implementing a default user interface.)

This class is included in the applicationupdater_ui.swc file, included in the Adobe AIR SDK. The applicationupdater_ui.swc file is in the frameworks/libs/air directory of the AIR SDK. The version in the frameworks/libs/air directory in the AIR 2 SDK is for Flex 4 development. If you use Flex 3, use the version in the frameworks/libs/air/flex3 subdirectory.

Adobe^® Flex™ Builder™ loads this class automatically when you create a project for Adobe AIR. You should include the SWC file when compiling the application using the Adobe^® Flex™ SDK.

Managing updates of applications can be complicated. The AIR update framework provides APIs to assist developers in providing good update capabilities in AIR applications. The functionality in the AIR update framework assists developers in the following:

Periodically checking for updates based on an interval or at the request of the user
Downloading AIR files (updates) from a web source
Alerting the user on the first run of the newly installed version
Confirming that the user wants to check for updates
Displaying information on the new update version to the user
Displaying download progress and error information to the user

The AIR update framework lets you store information about the update version of an AIR application in simple XML configuration files. For most applications, setting up these configuration files and including some basic code provides good update functionality to the end user.

The AIRUpdateUI class implements a default user interface that your application can use. It provides the user with basic information and options related to application updates.

The update process goes through a sequence of states:

State	Description
Uninitialized	The updater has not been initialized.
Initializing	The updater is initializing.
Ready	The updater has been initialized
Before checking	The updater has not yet checked for the update descriptor file.
Checking	The updater is checking for an update descriptor file.
Available	The update descriptor file is available.
Downloading	The updater is downloading the AIR file.
Downloaded	The updater has downloaded the AIR file.
Installing	The updater is installing the AIR file.
Pending install	The updater has initialized and there are pending updates.

When testing an application using the AIR Debug Launcher (ADL) application, attempting to update the application results in an IllegalOperationError exception.

The AIR update framework is only supported in the desktop profile. It is not supported for extended desktop applications (applications installed with a native installer), and it is not supported on the mobile profile (iPhone applications written with ActionScript 3.0). Check the Updater.isSupported property at runtime to see if the update framework is supported.

For details on using the AIR update framework, see the "Updating AIR Applications" chapter of Building Adobe AIR Applications.

Related API Elements

ApplicationUpdater
flash.desktop.Updater

Public Properties

Hide Inherited Public Properties

Show Inherited Public Properties

	Property		Defined By
		configurationFile : File The location of the configuration file that sets the values for delay and updateURL properties.	ApplicationUpdaterUI
		constructor : Object A reference to the class object or constructor function for a given object instance.	Object
		currentVersion : String [read-only] The current version of the application.	ApplicationUpdaterUI
		delay : Number The interval, in days, between periodic checks of new updates.	ApplicationUpdaterUI
		isCheckForUpdateVisible : Boolean Enables the visibility of the Check for Update, No Update, and Update Error dialog boxes.	ApplicationUpdaterUI
		isDownloadProgressVisible : Boolean Enables the visibility of the Download Update dialog box.	ApplicationUpdaterUI
		isDownloadUpdateVisible : Boolean Enables the visibility of the Download Update dialog box.	ApplicationUpdaterUI
		isFileUpdateVisible : Boolean Enables the visibility of the File Update, File No Update, and File Error dialog boxes.	ApplicationUpdaterUI
		isFirstRun : Boolean [read-only] Whether this is the first run after a successful update (true) or not (false).	ApplicationUpdaterUI
		isInstallUpdateVisible : Boolean Enables the visibility of the Install Update dialog box.	ApplicationUpdaterUI
		isNewerVersionFunction : Function A function that the updater should use to perform version comparisons.	ApplicationUpdaterUI
		isUnexpectedErrorVisible : Boolean Enables the visibility of the Unexpected Error dialog box.	ApplicationUpdaterUI
		isUpdateInProgress : Boolean [read-only] A Boolean property, which is true if an update is running, false otherwise.	ApplicationUpdaterUI
		localeChain : Array An array defining the locale chain used by the user interface.	ApplicationUpdaterUI
		previousApplicationStorageDirectory : File [read-only] The previous location of the application storage directory, if it changed after an update.	ApplicationUpdaterUI
		previousVersion : String [read-only] The previous version of the application.	ApplicationUpdaterUI
		updateDescriptor : XML [read-only] The content of the update descriptor file downloaded from the update URL.	ApplicationUpdaterUI
		updateURL : String The location of the update descriptor file.	ApplicationUpdaterUI
		wasPendingUpdate : Boolean [read-only] Whether there was a postponed update, even if it failed to install (true); false otherwise.	ApplicationUpdaterUI

Public Methods

Hide Inherited Public Methods

Show Inherited Public Methods

	Method		Defined By
		ApplicationUpdaterUI() The constructor function.	ApplicationUpdaterUI
		addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.	EventDispatcher
		addResources(lang:String, res:Object):void Dynamically adds a new resource bundle for the specified language.	ApplicationUpdaterUI
		cancelUpdate():void Cancels the update process.	ApplicationUpdaterUI
		checkNow():void Starts the update process.	ApplicationUpdaterUI
		dispatchEvent(event:Event):Boolean Dispatches an event into the event flow.	EventDispatcher
		hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event.	EventDispatcher
		hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined.	Object
		initialize():void Initializes the updater.	ApplicationUpdaterUI
		installFromAIRFile(file:File):void Starts the update process using a local AIR file.	ApplicationUpdaterUI
		isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.	Object
		propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable.	Object
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object.	EventDispatcher
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations.	Object
		toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions.	Object
		toString():String Returns the string representation of the specified object.	Object
		valueOf():Object Returns the primitive value of the specified object.	Object
		willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.	EventDispatcher

Events

Click for more information on events

Hide Inherited Events

Show Inherited Events

	Summary	Defined By
activate	[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.	EventDispatcher
beforeInstall	Dispatched just before installing the update, after the installUpdate() method was called.	ApplicationUpdaterUI
checkForUpdate	Dispatched before the update process begins, just before the updater tries to download the update descriptor file.	ApplicationUpdaterUI
deactivate	[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.	EventDispatcher
downloadComplete	Dispatched when the download of the update file is complete.	ApplicationUpdaterUI
downloadError	Dispatched if there is an error while connecting or downloading the update file.	ApplicationUpdaterUI
downloadStart	Dispatched after a call to the downloadUpdate() method and the connection to the server is established.	ApplicationUpdaterUI
error	Dispatched when an error occurred either during initialization or during the update process (if something unexpected happens).	ApplicationUpdaterUI
fileUpdateError	Dispatched when an error occurs validating the file passed as the airFile parameter in a call to the installFromAIRFile() method.	ApplicationUpdaterUI
fileUpdateStatus	Dispatched after the updater successfully validates the file in the call to the installFromAIRFile() method.	ApplicationUpdaterUI
initialized	Dispatched after the initialization is complete.	ApplicationUpdaterUI
progress	Dispatched as the update file is downloaded.	ApplicationUpdaterUI
updateError	Dispatched if an error occurs while trying to download or parse the update descriptor file.	ApplicationUpdaterUI
updateStatus	Dispatched after the updater successfully downloads and interprets the update descriptor file.	ApplicationUpdaterUI

Property Detail

configurationFile

property

configurationFile:File

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

The location of the configuration file that sets the values for delay and updateURL properties. It also has settings for determining whether the application displays various confirmation dialog boxes during the update process. If this property points to a non-existent file, calling the initialize() method results in an Error being thrown.

Here is a sample configuration file:

Copy

 <?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>
           <defaultUI>
              <dialog name="checkForUpdate" visible="true" />
               <dialog name="downloadUpdate" visible="false" />
               <dialog name="downloadProgress" visible="true" />
               <dialog name="installUpdate" visible="true" />    
           </defaultUI>
        </configuration>

Instead of loading a configuration file, you can use ActionScript code to set the following properties of the ApplicationUpdaterUI object: delay, isCheckForUpdateVisible, isDownloadProgressVisible, isDownloadUpdateVisible, isFileUpdateVisible, isInstallUpdateVisible, and updateURL properties.

Implementation
public function get configurationFile():File
public function set configurationFile(value:File):void

Related API Elements

delay
updateURL

currentVersion

property

currentVersion:String [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

The current version of the application. This property is set during a call to the initialize() method. It is set to the version from the application descriptor file.

Implementation
public function get currentVersion():String

delay

property

delay:Number

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

The interval, in days, between periodic checks of new updates.

A value of 0 (the default value) indicates that the timer is not active, so no periodic check is done. The delay can be set either via this property or via the configuration file. When the value is set using both methods, the value set using this property is used.

The default value is 0.

Implementation
public function get delay():Number
public function set delay(value:Number):void

Related API Elements

configurationFile

isCheckForUpdateVisible

property

isCheckForUpdateVisible:Boolean

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Enables the visibility of the Check for Update, No Update, and Update Error dialog boxes. When set to true, the updater displays these dialog boxes as part of the update process. This can also be set in the update configuration file. A value set using this property overrides the setting in the update configuration file.

Implementation
public function get isCheckForUpdateVisible():Boolean
public function set isCheckForUpdateVisible(value:Boolean):void

isDownloadProgressVisible

property

isDownloadProgressVisible:Boolean

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Enables the visibility of the Download Update dialog box. When set to true, the updater displays this dialog box as part of the update process. This can also be set in the update configuration file. A value set using this property overrides the setting in the update configuration file.

Implementation
public function get isDownloadProgressVisible():Boolean
public function set isDownloadProgressVisible(value:Boolean):void

isDownloadUpdateVisible

property

isDownloadUpdateVisible:Boolean

Runtime Versions:

AIR 1.5

Enables the visibility of the Download Update dialog box. When set to true, the updater displays these dialog boxes as part of the update process. This can also be set in the update configuration file. A value set using this property overrides the setting in the update configuration file.

Implementation
public function get isDownloadUpdateVisible():Boolean
public function set isDownloadUpdateVisible(value:Boolean):void

isFileUpdateVisible

property

isFileUpdateVisible:Boolean

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Enables the visibility of the File Update, File No Update, and File Error dialog boxes. When set to true, the updater displays these dialog boxes as part of the update process. This can also be set in the update configuration file. A value set using this property overrides the setting in the update configuration file.

Implementation
public function get isFileUpdateVisible():Boolean
public function set isFileUpdateVisible(value:Boolean):void

isFirstRun

property

isFirstRun:Boolean [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Whether this is the first run after a successful update (true) or not (false). The updater sets this value during the call to the initialize() method. The developer should check that isFirstRun is set to true if there is a need to migrate data from one version to another.

Implementation
public function get isFirstRun():Boolean

Related API Elements

wasPendingUpdate

isInstallUpdateVisible

property

isInstallUpdateVisible:Boolean

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Enables the visibility of the Install Update dialog box. When set to true, the updater displays this dialog box as part of the update process. This can also be set in the update configuration file. A value set using this property overrides the setting in the update configuration file.

Implementation
public function get isInstallUpdateVisible():Boolean
public function set isInstallUpdateVisible(value:Boolean):void

isNewerVersionFunction

property

isNewerVersionFunction:Function

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

A function that the updater should use to perform version comparisons. By default, the update framework does a version comparison to detect whether the version from the remote site is newer than the version of the installed application. However, sometimes the default comparison does not match the developer's versioning scheme. Set this property to provide a new function that does the comparison.

The default comparision function accepts versions like x.y.z, where x, y, and z can contain letters and digits. There are some special conditions that the default comparision function recognizes. If the test function finds "alpha", "beta", or "rc" in the version strings, the order is alpha < beta < rc.

Implementation
public function get isNewerVersionFunction():Function
public function set isNewerVersionFunction(value:Function):void

Example ( How to use this example )

The following code defines a custom function, customFn, for the appUpdate updater object. The example function is intentionally simple. Your custom function should return a Boolean value based on the rules of your versioning scheme.

Copy

appUpdate.isNewerVersionFunction = customFn; 

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

isUnexpectedErrorVisible

property

isUnexpectedErrorVisible:Boolean

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Enables the visibility of the Unexpected Error dialog box. When set to true, the Application Updater displays this dialog box as part of the update process. This can also be set in the update configuration file. A value set using this property overrides the setting in the update configuration file.

Implementation
public function get isUnexpectedErrorVisible():Boolean
public function set isUnexpectedErrorVisible(value:Boolean):void

isUpdateInProgress

property

isUpdateInProgress:Boolean [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

A Boolean property, which is true if an update is running, false otherwise.

Implementation
public function get isUpdateInProgress():Boolean

localeChain

property

localeChain:Array

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

An array defining the locale chain used by the user interface. Typically, only JavaScript (HTML) developers use this property.

Flex developers can use the ResourceManager to handle the locale chain.

By default, in an HTML-based application, the languages are sorted between those languages in the Capabilities.languages array and the ten languages supported by the user interface. If no match is found, the user interface uses the English language.

This JavaScript example uses the AIR HTML localization framework, included in the AIR SDK. It sorts the languages against the list of languages, and then it sets English as the default fallback language:

Copy

 appUpdater.addResources("ro_RO", {titleCheck: "Titlu", msgCheck: "Mesaj", btnCheck: "Buton"});
        appUpdater.addResources("hu", {titleCheck: "Cím", msgCheck: "Üzenet"}); 
        var languages = ["ro", "hu"];
        languages = languages.concat(air.Capabilities.languages);
        var sortedLanguages = air.Localizer.sortLanguagesByPreference(languages, air.Capabilities.language, "en-US");  
        sortedLanguages.push("en-US");
        appUpdater.localeChain = sortedLanguages;

Implementation
public function get localeChain():Array
public function set localeChain(value:Array):void

Related API Elements

addResources()

previousApplicationStorageDirectory

property

previousApplicationStorageDirectory:File [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

The previous location of the application storage directory, if it changed after an update. The application storage directory location changes after an upgrade with a certificate migration. If there is no certificate migration, the application storage directory does not change when the user updates the application. and this property is set to null. This property is set during a call to the initialize() method.

A developer can sign new version of AIR application with a new certificate if the developer uses the -migrate option when packaging the AIR file with ADT. If a new version of an AIR application uses a new signing certificate, the local storage directory of the application changes when the user installs the new version. Use this property to transfer data from the old application storage directory to the new application storage directory (File.applicationStorageDirectory). For more information, see "Signing an AIR file to change the application certificate" in the "Creating an AIR application using the command line tools" chapter of the Adobe AIR developer's guide.

Implementation
public function get previousApplicationStorageDirectory():File

previousVersion

property

previousVersion:String [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

The previous version of the application. This property is set during a call to the initialize() method. Returns the previous version of the application before the upgrade (set only if isfirstRun is true); otherwise it is set to null.

Implementation
public function get previousVersion():String

updateDescriptor

property

updateDescriptor:XML [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

The content of the update descriptor file downloaded from the update URL. This property is non-null only after the updater object dispatches an updateStatus event.

Implementation
public function get updateDescriptor():XML

updateURL

property

updateURL:String

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

The location of the update descriptor file. Any location valid for a URLRequest path is accepted. This is the only mandatory setting required by the updater. You can set the update URL either via this property or via the configuration file. When the value is set using both methods, the updater uses the value set using this property.

Implementation
public function get updateURL():String
public function set updateURL(value:String):void

Related API Elements

configurationFile

wasPendingUpdate

property

wasPendingUpdate:Boolean [read-only]

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Whether there was a postponed update, even if it failed to install (true); false otherwise. The updater sets this property during a call to the initialize() method. Use the wasPendingUpdate and isFirstRun properties to check if an update failed to install (in which case wasPendingUpdate is set to true and isFirstRun is set to false).

Implementation
public function get wasPendingUpdate():Boolean

Related API Elements

isFirstRun

Constructor Detail

()

Constructor

public function ApplicationUpdaterUI()

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

The constructor function.

Method Detail

addResources

()

method

public function addResources(lang:String, res:Object):void

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dynamically adds a new resource bundle for the specified language. JavaScript developers use this method to dynamically add a new language for the dialog boxes that the application updater UI displays. (Flex developers can directly add a new language to the "ApplicationUpdaterDialogs" resource bundle.)

Parameters

lang:String — The language code (such as "ro" for Romanian).

res:Object — The object contains the keys and values for the translation. The keys are the ones from the language property file. The following table lists the possible keys (property names).

Key	English value	Dialog Box	Description
`appWidth`	530	All	Width of the dialog box.
`titleWindow`	Updating:	All	Displayed in the native window title bar before the application name.
`titleCheck`	Check for updates	Check For Updates	Dialog box title.
`msgCheck`	Allow the application to check for updates?	Check For Updates	Dialog box message.
`btnCheck`	Check for Updates	Check For Updates	Check for Updates button label.
`btnCancel`	Cancel	All dialog boxes with a Cancel button	Cancel button label.
`titleCheckNoUpdates`	No updates available	CheckForUpdates - No updates available	Dialog box title.
`msgCheckNoUpdates`	There are no updates available for the application.	Check For Updates - No updates available	Dialog box message.
`btnClose`	Close	All dialog boxes with Close button	Close button label.
`titleCheckError`	Update error	Check For Updates - Connection Error	Dialog box title.
`msgCheckError`	There was an error checking for updates. Error# {0}	Check For Updates - Connection Error	Dialog box message. {0} will be replaced with the error ID.
`titleUpdate`	Update available	Update Available	Dialog box title.
`msgUpdate`	An updated version of the application is available for download.	Update Available	Dialog box message.
`lblApplication`	Application:	Update Available	Label displayed before the application name.
`lblInstalledVersion`	Installed Version:	Update Available	Label displayed before the installed version.
`lblAvailableVersion`	Update Version:	Update Available	Label displayed before the update version.
`btnDownload`	Download now	Update Available	Download Now button label.
`btnDownloadLater`	Download later	Update Available	Download Later button label.
`lnkReleaseNotes`	Release notes	All with release notes link	The "Release notes" link name.
`titleProgress`	Download progress...	Download Progress	Dialog box title.
`msgProgress`	Downloading update	Download Progress	Dialog box message.
`titleDownloadError`	Download failed	Download Error	Dialog box title.
`msgDownloadError`	There was an error downloading the update. Error# {0}	Download Error	Dialog box message. {0} will be replaced with the error ID.
`titleInstall`	Install update	Install Update	Dialog box title.
`msgInstall`	The update for the application is downloaded and ready to be installed.	Install Update	Dialog box message.
`btnInstall`	Install now	Install Update	"Install" button label
`btnInstallLater`	Postpone until restart	Install Update	"Postpone until restart" button label
`titleFileUpdate`	Update available	File - Update Available	Dialog box title.
`msgFileUpdate`	The file contains an updated version of the application. Install?	File - Update Available	Dialog box message.
`lblFile`	File:	File - Update Available	Label displayed before the file name
`titleFileNoUpdate`	No update available	File - No updates available	Dialog box title.
`msgFileNoUpdate`	The file doesn't contain a newer version of the application.	File - No updates available	Dialog box message.
`titleFileError`	File error	File - Error	Dialog box title.
`msgFileError`	An error occurred validating the update file. Error# {0}	File - Error	Dialog box message. {0} will be replaced with the error ID.
`titleUnexpectedError`	Unexpected error	Unexpected Error	Dialog box title.
`msgUnexpectedError`	An unexpected error occurred. Error# {0}	Unexpected Error	Dialog box message. {0} will be replaced with the error ID.

Related API Elements

localeChain

cancelUpdate

()

method

public function cancelUpdate():void

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Cancels the update process. Calling this method cancels any pending downloads, deleting any incomplete downloaded files, and restarts the periodic check timer.

The update process can be canceled at any time except when the state machine is in "uninitialized" or "initializing" state. It does nothing when it is called in one of the "uninitialized" or "initializing" states.

checkNow

()

method

public function checkNow():void

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Starts the update process. Calling this method does not stop the periodic timer; however, the method detects that an update process is running and will skip the current iteration.

This method only executes if the current state is "Ready".

This method can result in the updater object dispatching the following event:

Events

checkForUpdate:UpdateEvent — Dispatched just before the update process begins.

initialize

()

method

public function initialize():void

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Initializes the updater. Calling this method does the following:

It initializes the update framework, silently (and synchronously) installing any pending updates. You should call this method during application startup, since it may restart the application.
It checks if there is a postponed update and installs it.
If something went wrong with a prior update, it clears the update file and version information from the storage area.
If the periodic timer delay has expired, it starts the update process; otherwise it starts the periodic timer. However, when testing an application using the AIR Debug Launcher (ADL) application, attempting to update the application results in a IllegalOperationError exception.

Events

	`initialized:UpdateEvent` — The initialization is complete.

	`error:ErrorEvent` — There is an error during initialization.

installFromAIRFile

()

method

public function installFromAIRFile(file:File):void

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Starts the update process using a local AIR file.

Calling this method has no effect if an update process is running (if the state is not "Downloaded").

This function is useful for an application that has the customUpdateUI element set to true in the application descriptor file.

When testing an application using the AIR Debug Launcher (ADL) application, calling this method results in an IllegalOperationError exception.

Parameters

file:File — The local AIR file to install.

Events

	`fileUpdateStatus:StatusFileUpdateEvent` — Dispatched after the updater successfully validates the AIR file.

	`updateError:StatusFileUpdateErrorEvent` — Dispatched if an error occurs while trying parse the update descriptor file.

Event Detail

beforeInstall

Event

Event Object Type: air.update.events.UpdateEvent
property UpdateEvent.type = air.update.events.UpdateEvent.BEFORE_INSTALL

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dispatched just before installing the update, after the installUpdate() method was called. Sometimes, it is useful to prevent the installation of the update at this time, because the user could lose all current work when the runtime exits the application to install the update.

Calling this event's preventDefault() method postpones the installation until the next restart. If you call the preventDefault() method, no additional update process can be started during this application session (via a call to the installUpdate() method or because of the periodic check).

The UpdateEvent.BEFORE_INSTALL constant defines the value of the type property of the event object for a beforeInstall event.

This event has the following properties:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`target`	The updater object.

checkForUpdate

Event

Event Object Type: air.update.events.UpdateEvent
property UpdateEvent.type = air.update.events.UpdateEvent.CHECK_FOR_UPDATE

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dispatched before the update process begins, just before the updater tries to download the update descriptor file. The updater can dispatch this event as a result of directly calling the checkNow() method or because the periodic check timer expired.

The UpdateEvent.CHECK_FOR_UPDATE constant defines the value of the type property of the event object for a checkForUpdate event.

This event has the following properties:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`target`	The updater object.

downloadComplete

Event

Event Object Type: air.update.events.UpdateEvent
property UpdateEvent.type = air.update.events.UpdateEvent.DOWNLOAD_COMPLETE

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dispatched when the download of the update file is complete.

The UpdateEvent.DOWNLOAD_COMPLETE constant defines the value of the type property of the event object for a downloadComplete event.

This event has the following properties:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`target`	The updater object.

downloadError

Event

Event Object Type: air.update.events.DownloadErrorEvent
property DownloadErrorEvent.type = air.update.events.DownloadErrorEvent.DOWNLOAD_ERROR

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dispatched if there is an error while connecting or downloading the update file. It is also dispatched for invalid HTTP statuses (such as 404 - File not found).

When this event is dispatched the periodic timer is automatically restarted (if the delay is greater than 0).

The DownloadErrorEvent.DOWNLOAD_ERROR constant defines the value of the type property of the event object for a downloadError event.

The errorID property of a DownloadErrorEvent object is an integer defining error information (see the following table). An additional subErrorID property may contain more error information.

errorID Error code	Description
16800	Occurs during validating the downloaded update file. The `subErrorID` property may contain additional information.
16801	Invalid Adobe AIR file (missing application.xml).
16802	Invalid Adobe AIR file (missing MIME type).
16803	Invalid Adobe AIR file (format).
16804	Invalid Adobe AIR file (invalid flags).
16805	Invalid Adobe AIR file (unknown compression).
16806	Invalid Adobe AIR file (invalid filename).
16807	Invalid Adobe AIR file (corrupt).
16808	Configuration file does not exist.
16809	The `updateURL` property is not set.
16810	Reserved.
16811	Invalid configuration file (unknown configuration version).
16812	Invalid configuration file (URL missing).
16813	Invalid configuration file (delay format).
16814	Invalid configuration file (invalid defaultUI values).
16815	Invalid update descriptor (unknown descriptor version).
16816	Invalid update descriptor (missing update version).
16817	Invalid update descriptor (invalid description).
16818	IO error while saving data to disk. The `subErrorID` property may provide more information.
16819	Security error while downloading. The `subErrorID` property may provide more information.
16820	Invalid HTTP status code. The `subErrorID` property may contain the invalid status code.
16821	Reserved.
16822	I/O error while downloading. The `subErrorID` property may provide more information.
16823	End-of-file error while saving data to disk. The `subErrorID` property may provide more information.
16824	Invalid update descriptor. The `subErrorID` property may provide more information.
16825	The update file contains an application with a different application ID.
16826	The update file does not contain a newer version of the application.
16827	The version contained in the update file does not match the version from the update descriptor.
16828	Cannot update application, usually because the application is running in the AIR Debug Launcher (ADL).
16829	Missing update file at install time.

downloadStart

Event

Event Object Type: air.update.events.UpdateEvent
property UpdateEvent.type = air.update.events.UpdateEvent.DOWNLOAD_START

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dispatched after a call to the downloadUpdate() method and the connection to the server is established. When using ApplicationUpdater library, you may want the event handler for this event to display a progress bar to report the download progress to the user.

The UpdateEvent.DOWNLOAD_START constant defines the value of the type property of the event object for a downloadStart event.

This event has the following properties:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`target`	The updater object.

error

Event

Event Object Type: flash.events.ErrorEvent
property ErrorEvent.type = flash.events.ErrorEvent.ERROR

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dispatched when an error occurred either during initialization or during the update process (if something unexpected happens).

Defines the value of the type property of an error event object.

This event has the following properties:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`target`	The object experiencing a network operation failure.
`text`	Text to be displayed as an error message.

fileUpdateError

Event

Event Object Type: air.update.events.StatusFileUpdateErrorEvent
property StatusFileUpdateErrorEvent.type = air.update.events.StatusFileUpdateErrorEvent.FILE_UPDATE_ERROR

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dispatched when an error occurs validating the file passed as the airFile parameter in a call to the installFromAIRFile() method.

The StatusUpdateErrorEvent.UPDATE_ERROR constant defines the value of the type property of the event object for a statusUpdateError event.

fileUpdateStatus

Event

Event Object Type: air.update.events.StatusFileUpdateEvent
property StatusFileUpdateEvent.type = air.update.events.StatusFileUpdateEvent.FILE_UPDATE_STATUS

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dispatched after the updater successfully validates the file in the call to the installFromAIRFile() method.

The StatusUpdateEvent.UPDATE_STATUS constant defines the value of the type property of the event object for a updateStatus event.

This event has the following properties:

Property	Value
`available`	Indicates if if there is a different version available than one of the current application (`true`); `false` otherwise (same version).
`path`	The `nativePath` property of the update File object specified by the `airFile` parameter in a call to the `installFromAIRFile()` method.
`version`	Indicates the version of the new update.

initialized

Event

Event Object Type: air.update.events.UpdateEvent
property UpdateEvent.type = air.update.events.UpdateEvent.INITIALIZED

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dispatched after the initialization is complete.

This event has the following read-only properties:

isFirstRun (Boolean) true if this is the first run after a successful update; false otherwise.
previousVersion (String) The previous version of the application before the upgrade (set only if isfirstRun is true).
currentVersion (String) The version from the application descriptor file of the currently installed version.

The UpdateEvent.INITIALIZED constant defines the value of the type property of the event object for a initialized event.

This event has the following properties:

Property	Value
`bubbles`	`false`
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`target`	The updater object.

progress

Event

Event Object Type: flash.events.ProgressEvent
property ProgressEvent.type = flash.events.ProgressEvent.PROGRESS

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dispatched as the update file is downloaded.

Defines the value of the type property of a progress event object.

This event has the following properties:

Property	Value
`bubbles`	`false`
`bytesLoaded`	The number of items or bytes loaded at the time the listener processes the event.
`bytesTotal`	The total number of items or bytes that ultimately will be loaded if the loading process succeeds.
`cancelable`	`false`; there is no default behavior to cancel.
`currentTarget`	The object that is actively processing the Event object with an event listener.
`target`	The object reporting progress.

updateError

Event

Event Object Type: air.update.events.StatusUpdateErrorEvent
property StatusUpdateErrorEvent.type = air.update.events.StatusUpdateErrorEvent.UPDATE_ERROR

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dispatched if an error occurs while trying to download or parse the update descriptor file.

When the updater dispatches this event, the periodic timer is automatically restarted (if the delay setting is greater than 0). The application should consider hiding any error dialog boxes when the updater dispatches a new checkForUpdate event.

The StatusUpdateErrorEvent.UPDATE_ERROR constant defines the value of the type property of the event object for a statusUpdateError event.

updateStatus

Event

Event Object Type: air.update.events.StatusUpdateEvent
property StatusUpdateEvent.type = air.update.events.StatusUpdateEvent.UPDATE_STATUS

Language Version:

ActionScript 3.0

Runtime Versions:

AIR 1.5

Dispatched after the updater successfully downloads and interprets the update descriptor file.

The StatusUpdateEvent.UPDATE_STATUS constant defines the value of the type property of the event object for a updateStatus event.

This event has the following properties:

Property	Value
`available`	Set to `true` if the update descriptor file specifies a version that is different than that of the current application; `false` otherwise (the version is the same).
`version`	The string representing the new available version.
`details`	An array defining the `details` string for each of the supported languages. If there is no localized description, this is defined as an array in which the first element is an empty string (`""`) and the second element is the details string. When there are localized descriptions, each element in the array is an array itself with two elements. The first element is the locale code, and the second is the description. For example, the following array has sub-arrays for two languages (U.S. English and French): `["en-US", "Hello World"], ["fr", "Bonjour monde"]`. The languages are listed in the same order as in the update descriptor. The text for the details property is specified in the update descriptor file.
`versionLabel`	(AIR 2.5+) The version label from the application descriptor of the update. The version label should be displayed to users instead of version. If no version label is specified, this property is an empty string.

ApplicationUpdaterUI - AS3

Classes x

configurationFile

currentVersion

delay

isCheckForUpdateVisible

isDownloadProgressVisible

isDownloadUpdateVisible

isFileUpdateVisible

isFirstRun

isInstallUpdateVisible

isNewerVersionFunction

isUnexpectedErrorVisible

isUpdateInProgress

localeChain

previousApplicationStorageDirectory

previousVersion

updateDescriptor

updateURL

wasPendingUpdate