WebAPI/SystemUpdateAPI

From MozillaWiki
Jump to: navigation, search

Design Architecture

SystemupdateArch.png

Contributors

Shih-Chiang Chien, James Cheng

Status

Features

  • Provide a standard WebAPI interface for interaction between applocation and update providers.
  • Provide a plugin mechanism for partner to inject their update provider module into gecko.
  • Dynamically switch between different update providers.

Proposed API

Basic WebIDL Interface

 dictionary SystemUpdateProviderInfo {
   DOMString name = "";
   DOMString uuid = "";
 };
 dictionary SystemUpdatePackageInfo {
   DOMString type = "";
   DOMString version = "";
   DOMString description = "";
   DOMTimeStamp buildDate = 0;
   unsigned long long size = 0;
 };
 [JSImplementation="@mozilla.org/system-update-provider;1",
  CheckPermissions="system-update",
  Pref="dom.system_update.enabled"]
 interface SystemUpdateProvider : EventTarget {
   readonly attribute DOMString name;
   readonly attribute DOMString uuid;
  
   attribute EventHandler onupdateavailable;
   attribute EventHandler onprogress;
   attribute EventHandler onupdateready;
   attribute EventHandler onerror;
  
   void checkForUpdate();
   void startDownload();
   void stopDownload();
   void applyUpdate();
   boolean setParameter(DOMString name, DOMString value);
   DOMString getParameter(DOMString name);
 };

name of type DOMString, readonly
The name for this update provider.
uuid of type DOMString, readonly
The unique id for this update provider.
onupdateavailable of type EventHandler,
Notified when there is an available update package for download.
onprogress of type EventHandler,
Notified when download progress changes.
onupdateready of type EventHandler,
Notified when finishing download and ready for applying the download package.
onerror of type EventHandler,
Notified if any error occurs.
checkForUpdate,
Check if there is any available update package for download.
startDownload,
Start the downloading process.
stopDownload,
Stop the downloading process.
applyUpdate,
Apply the downloaded update package.
getParameter / setParameter,
Get / Set the parameter of current update provider.

 [NavigatorProperty="updateManager",
  JSImplementation="@mozilla.org/system-update-manager;1",
  CheckPermissions="system-update",
  Pref="dom.system_update.enabled"]
 interface SystemUpdateManager {
   Promise<sequence<SystemUpdateProviderInfo>> getProviders();
  
   Promise<SystemUpdateProvider> setActiveProvider(DOMString uuid);
  
   Promise<SystemUpdateProvider> getActiveProvider();
 };

getProviders,
Get available providers in this device.
setActiveProvider,
Set the designate provider to active.
getActiveProvider,
Get the designate provider information.

Examples

navigator.udpateManager.getProviders().then(function(providerInfos) {
 var providerInfo = providerInfos[0];
 return navigator.updateManager.setActiveProvider(providerInfo.uuid);
}).then(function(provider) {
 // notify available update
 checkButton.onclick = function(event) {
   provider.checkForUpdate();
 };
 provider.onupdateavailable = function(evt) {
   showUpdateAvailable(event.detail.packageInfo);
   downloadButton.onclick = function(event) {
     provider.startDownload();
   };
 };
 // display download progress
 provider.onprogress = function(event) {
   showDownloadProgress(event);
 };
 // prompt when update package is ready to apply
 provider.onupdateready = function(event) {
     showUpdateReady();
     applyButton.onclick = function() {
       provider.applyUpdate();
     };
   };
 });

Scheduled update

var myDate  = new Date("May 15, 2012 16:20:00");
var req = navigator.mozAlarms.add(myDate, "ignoreTimezone", provider.info);
 req.onsuccess = function(event) {
  var info = event.alarm.data;
  navigator.updateManager.setActiveProvider(info.uuid)
  .then(function(provider) {
    provider.checkForUpdate();
  });
};