Software Update:updates.xml Format
Background
The updates.xml format is the format used by the AUS server to advertise updates that are available to clients.
Format
A typical updates.xml file looks like this:
<?xml version="1.0"?>
<updates>
<update type="minor" version="1.0.4" extensionVersion="1.0.4"
detailsURL="http://www.foo.com/1.0.4/whatsnew.html" isOSUpdate="true">
<patch type="partial" URL="http://www.foo.com/1.0.4-partial.mar"
hashFunction="" hashValue="" size=""/>
<patch type="complete" URL="http://www.foo.com/1.0.4-complete.mar"
hashFunction="" hashValue="" size=""/>
</update>
..
<update type="major" version="1.1.2" extensionVersion="1.1.2"
detailsURL="http://www.foo.com/1.1.2/whatsnew.html" isOSUpdate="true">
<patch type="complete" URL="http://www.foo.com/1.1.2-complete.mar"
hashFunction="" hashValue="" size=""/>
</update>
</updates>
Elements & Attributes
Every updates.xml contains a updates element as its root. This element has no attributes.
Beneath updates lives a sequence of update elements, each describing an update to an individual application version.
The attributes for update are as follows:
| type | major or minor. Major updates are for major application number revs, minor for security releases or incremental updates. (Note: client side support for major updates is new to the MOZILLA_1_8_BRANCH.) |
| version | A string in FVF format advertising the version of this application update. |
| extensionVersion | A string in FVF format advertising the version of the extension API that this application update supplies. If it is "less" than the current version of your app, the update will not be considered available. |
| detailsURL | A URL string to a web page with more information about the specified update. For minor releases, this URL appears as a link (with text like "View more information about this update") in the UI shown to the user when they are presented with the option to upgrade. New for MOZILLA_1_8_BRANCH: For major releases, this URL is loaded "in line" in the UI shown to the user when they are presented with the option to upgrade. See Software_Update:HowToTestMajorUpdateUI for how to test this. |
| licenseURL | New for MOZILLA_1_8_BRANCH: A URL string to a web page with additional license terms that need to be accepted before the update can be installed (optional, do NOT provide it if this is going to be empty). Note: this attribute is only heeded for major releases. For minor releases, this attribute is ignored by the client. For major releases, this URL is loaded "in line" in the UI shown to the user when they are presented with the option to upgrade. See Software_Update:HowToTestMajorUpdateUI for how to test this. |
true for security updates, to present a scarier warning to users, false if the update is not a security update. | |
| buildID | The BuildID of the build being offered |
| isOSUpdate | Needed to specify that the update is to be applied as a recovery update, with the phone rebooting into recovery mode and applying the update correctly. |
Important Note: The schemes for the URL strings specified by the licenseURL and detailsURL attributes must be http or https. For security concerns, the web pages pointed to by the licenseURL and detailsURL attributes will be unable to execute Javascript, prompt for auth, execute plugins, or have subframes. (Meta redirects and images are allowed.) Additionally, any links in the page should have target=_blank, so that they will be parented in a new browser window, and not in XUL browser with in the software update UI.
If specified, the licenseURL must successfully load "in line" before the user can agree to it. The user must agree to it in order to proceed with the upgrade. (If the licenseURL fails to load, the user will be unable to agree to it, and therefore unable to upgrade.) Note: if the licenseURL attribute does not change between major releases, the user will end up agreeing to the same license twice. See bug #348389 for details.
New for MOZILLA_1_8_BRANCH: If an updates.xml files contains information about both a minor and a major upgrade, the end user will only see the minor updates. For major updates, the user will see an additional "Never" button in order to decline automatic reminders updates (using the hidden app.update.never.<version> pref to persist this decision). The user can manually "Check for Upgrades..." to get a major update that was previously declined.
Within an update element there must be at least one and no more than two patch elements. The patch element describes a patch file that lives on a remote server that must be downloaded and applied to the application to update it to that version. They describe either binary differences between versions of the application (partial patches), or complete updates that replace and remove files as necessary. The attributes for patch are as follows:
| type | partial or complete, depending on the patch. |
| URL | A URL to the remote patch file. |
| hashFunction | The name of the hash function to execute to verify the integrity of the patch. |
| hashValue | The server-generated hash generated for the file. If the client generated value does not match this, the integrity check fails after download. |
| size | The size of the update, in bytes. |
Important Note: The schemes for the URL attribute must be http or https.
Additional Client Metadata
The client uses this same format to collect a history of installed updates. In the process, it caches the update file locally in two places:
bin/active-update.xml (the update in progress, persisted across sessions) bin/updates.xml (updates performed in the past)
These files may contain additional attributes representing update state stored by the client.
