michael@0: /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIDOMDocument;
michael@0: interface nsIDOMElement;
michael@0: interface nsIDOMWindow;
michael@0: interface nsIRequest;
michael@0: interface nsIRequestObserver;
michael@0: interface nsISimpleEnumerator;
michael@0: interface nsIXMLHttpRequest;
michael@0: interface nsIFile;
michael@0: 
michael@0: /**
michael@0:  * An interface that describes an object representing a patch file that can
michael@0:  * be downloaded and applied to a version of this application so that it
michael@0:  * can be updated.
michael@0:  */
michael@0: [scriptable, uuid(dc8fb8a9-3a53-4031-9469-2a5197ea30e7)]
michael@0: interface nsIUpdatePatch : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * The type of this patch:
michael@0:    * "partial"      A binary difference between two application versions
michael@0:    * "complete"     A complete patch containing all of the replacement files
michael@0:    *                to update to the new version
michael@0:    */
michael@0:   attribute AString type;
michael@0: 
michael@0:   /**
michael@0:    * The URL this patch was being downloaded from
michael@0:    */
michael@0:   attribute AString URL;
michael@0: 
michael@0:   /**
michael@0:    * The final URL this patch was being downloaded from
michael@0:    */
michael@0:   attribute AString finalURL;
michael@0: 
michael@0:   /**
michael@0:    * The hash function to use when determining this file's integrity
michael@0:    */
michael@0:   attribute AString hashFunction;
michael@0: 
michael@0:   /**
michael@0:    * The value of the hash function named above that should be computed if
michael@0:    * this file is not corrupt.
michael@0:    */
michael@0:   attribute AString hashValue;
michael@0: 
michael@0:   /**
michael@0:    * The size of this file, in bytes.
michael@0:    */
michael@0:   attribute unsigned long size;
michael@0: 
michael@0:   /**
michael@0:    * The state of this patch
michael@0:    */
michael@0:   attribute AString state;
michael@0: 
michael@0:   /**
michael@0:    * true if this patch is currently selected as the patch to be downloaded and
michael@0:    * installed for this update transaction, false if another patch from this
michael@0:    * update has been selected.
michael@0:    */
michael@0:   attribute boolean selected;
michael@0: 
michael@0:   /**
michael@0:    * Serializes this patch object into a DOM Element
michael@0:    * @param   updates
michael@0:    *          The document to serialize into
michael@0:    * @returns The DOM Element created by the serialization process
michael@0:    */
michael@0:   nsIDOMElement serialize(in nsIDOMDocument updates);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * An interface that describes an object representing an available update to
michael@0:  * the current application - this update may have several available patches
michael@0:  * from which one must be selected to download and install, for example we
michael@0:  * might select a binary difference patch first and attempt to apply that,
michael@0:  * then if the application process fails fall back to downloading a complete
michael@0:  * file-replace patch. This object also contains information about the update
michael@0:  * that the front end and other application services can use to learn more
michael@0:  * about what is going on.
michael@0:  */
michael@0: [scriptable, uuid(6b0b7721-6746-443d-8cb0-c6199d7f28a6)]
michael@0: interface nsIUpdate : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * The type of update:
michael@0:    *   "major"  A major new version of the Application
michael@0:    *   "minor"  A minor update to the Application (e.g. security update)
michael@0:    */
michael@0:   attribute AString type;
michael@0: 
michael@0:   /**
michael@0:    * The name of the update, or "<Application Name> <Update Version>"
michael@0:    */
michael@0:   attribute AString name;
michael@0: 
michael@0:   /**
michael@0:    * The string to display in the user interface for the version. If you want
michael@0:    * a real version number use appVersion.
michael@0:    */
michael@0:   attribute AString displayVersion;
michael@0: 
michael@0:   /**
michael@0:    * The Application version of this update.
michael@0:    */
michael@0:   attribute AString appVersion;
michael@0: 
michael@0:   /**
michael@0:    * The Toolkit version of this update.
michael@0:    */
michael@0:   attribute AString platformVersion;
michael@0: 
michael@0:   /**
michael@0:    * The Application version prior to the application being updated.
michael@0:    */
michael@0:   attribute AString previousAppVersion;
michael@0: 
michael@0:   /**
michael@0:    * The Build ID of this update. Used to determine a particular build, down
michael@0:    * to the hour, minute and second of its creation. This allows the system
michael@0:    * to differentiate between several nightly builds with the same |version|
michael@0:    * for example.
michael@0:    */
michael@0:   attribute AString buildID;
michael@0: 
michael@0:   /**
michael@0:    * The URL to a page which offers details about the content of this
michael@0:    * update. Ideally, this page is not the release notes but some other page
michael@0:    * that summarizes the differences between this update and the previous,
michael@0:    * which also links to the release notes.
michael@0:    */
michael@0:   attribute AString detailsURL;
michael@0: 
michael@0:   /**
michael@0:    * The URL to a page that is typically localized to display in the update
michael@0:    * prompt.
michael@0:    */
michael@0:   attribute AString billboardURL;
michael@0: 
michael@0:   /**
michael@0:    * The URL to a HTML fragment that contains a license for this update. If
michael@0:    * this is specified, the user is shown the license file after they choose
michael@0:    * to install the update and they must agree to it before the download
michael@0:    * commences.
michael@0:    */
michael@0:   attribute AString licenseURL;
michael@0: 
michael@0:   /**
michael@0:    * The URL to the Update Service that supplied this update.
michael@0:    */
michael@0:   attribute AString serviceURL;
michael@0: 
michael@0:   /**
michael@0:    * The channel used to retrieve this update from the Update Service.
michael@0:    */
michael@0:   attribute AString channel;
michael@0: 
michael@0:   /**
michael@0:    * Whether to show the update prompt which requires user confirmation when an
michael@0:    * update is found during a background update check. This overrides the
michael@0:    * default setting to download the update in the background.
michael@0:    */
michael@0:   attribute boolean showPrompt;
michael@0: 
michael@0:   /**
michael@0:    * Whether to show the "No Thanks" button in the update prompt. This allows
michael@0:    * the user to never receive a notification for that specific update version
michael@0:    * again.
michael@0:    */
michael@0:   attribute boolean showNeverForVersion;
michael@0: 
michael@0:   /**
michael@0:    * Whether the update is no longer supported on this system.
michael@0:    */
michael@0:   attribute boolean unsupported;
michael@0:   
michael@0:   /**
michael@0:    * Allows overriding the default amount of time in seconds before prompting the
michael@0:    * user to apply an update. If not specified, the value of
michael@0:    * app.update.promptWaitTime will be used.
michael@0:    */
michael@0:   attribute long long promptWaitTime;
michael@0: 
michael@0:   /**
michael@0:    * Whether or not the update being downloaded is a complete replacement of
michael@0:    * the user's existing installation or a patch representing the difference
michael@0:    * between the new version and the previous version.
michael@0:    */
michael@0:   attribute boolean isCompleteUpdate;
michael@0: 
michael@0:   /**
michael@0:    * Whether or not the update is a security update or not. If this is true,
michael@0:    * then we present more serious sounding user interface messages to the
michael@0:    * user.
michael@0:    */
michael@0:   attribute boolean isSecurityUpdate;
michael@0: 
michael@0:   /**
michael@0:    * Whether or not the update being downloaded is an OS update. This is
michael@0:    * generally only possible in Gonk right now.
michael@0:    */
michael@0:   attribute boolean isOSUpdate;
michael@0: 
michael@0:   /**
michael@0:    * When the update was installed.
michael@0:    */
michael@0:   attribute long long installDate;
michael@0: 
michael@0:   /**
michael@0:    * A message associated with this update, if any.
michael@0:    */
michael@0:   attribute AString statusText;
michael@0: 
michael@0:   /**
michael@0:    * The currently selected patch for this update.
michael@0:    */
michael@0:   readonly attribute nsIUpdatePatch selectedPatch;
michael@0: 
michael@0:   /**
michael@0:    * The state of the selected patch:
michael@0:    *   "downloading"        The update is being downloaded.
michael@0:    *   "pending"            The update is ready to be applied.
michael@0:    *   "pending-service"    The update is ready to be applied with the service.
michael@0:    *   "applying"           The update is being applied.
michael@0:    *   "applied"            The update is ready to be switched to.
michael@0:    *   "applied-os"         The update is OS update and to be installed.
michael@0:    *   "applied-service"    The update is ready to be switched to with the service.
michael@0:    *   "succeeded"          The update was successfully applied.
michael@0:    *   "download-failed"    The update failed to be downloaded.
michael@0:    *   "failed"             The update failed to be applied.
michael@0:    */
michael@0:   attribute AString state;
michael@0: 
michael@0:   /**
michael@0:    * A numeric error code that conveys additional information about the state
michael@0:    * of a failed update or failed certificate attribute check during an update
michael@0:    * check. If the update is not in the "failed" state or the certificate
michael@0:    * attribute check has not failed the value is zero.
michael@0:    *
michael@0:    * TODO: Define typical error codes (for now, see updater/errors.h and the
michael@0:    *       CERT_ATTR_CHECK_FAILED_* values in nsUpdateService.js)
michael@0:    */
michael@0:   attribute long errorCode;
michael@0: 
michael@0:   /**
michael@0:    * The number of patches supplied by this update.
michael@0:    */
michael@0:   readonly attribute unsigned long patchCount;
michael@0: 
michael@0:   /**
michael@0:    * Retrieves a patch.
michael@0:    * @param   index
michael@0:    *          The index of the patch to retrieve.
michael@0:    * @returns The nsIUpdatePatch at the specified index.
michael@0:    */
michael@0:   nsIUpdatePatch getPatchAt(in unsigned long index);
michael@0: 
michael@0:   /**
michael@0:    * Serializes this update object into a DOM Element
michael@0:    * @param   updates
michael@0:    *          The document to serialize into
michael@0:    * @returns The DOM Element created by the serialization process
michael@0:    */
michael@0:   nsIDOMElement serialize(in nsIDOMDocument updates);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * An interface describing an object that listens to the progress of an update
michael@0:  * check operation. This object is notified as the check continues, finishes
michael@0:  * and if it has an error.
michael@0:  */
michael@0: [scriptable, uuid(4aa2b4bb-39ea-407b-98ff-89f19134d4c0)]
michael@0: interface nsIUpdateCheckListener : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * The update check was completed.
michael@0:    * @param   request
michael@0:    *          The nsIXMLHttpRequest handling the update check.
michael@0:    * @param   updates
michael@0:    *          An array of nsIUpdate objects listing available updates.
michael@0:    * @param   updateCount
michael@0:    *          The size of the |updates| array.
michael@0:    */
michael@0:   void onCheckComplete(in nsIXMLHttpRequest request,
michael@0:                        [array, size_is(updateCount)] in nsIUpdate updates,
michael@0:                        in unsigned long updateCount);
michael@0: 
michael@0:   /**
michael@0:    * An error occurred while loading the remote update service file.
michael@0:    * @param   request
michael@0:    *          The nsIXMLHttpRequest handling the update check.
michael@0:    * @param   update
michael@0:    *          A nsIUpdate object that contains details about the
michael@0:    *          error in its |statusText| property.
michael@0:    */
michael@0:   void onError(in nsIXMLHttpRequest request,
michael@0:                in nsIUpdate update);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * An interface describing an object that knows how to check for updates.
michael@0:  */
michael@0: [scriptable, uuid(877ace25-8bc5-452a-8586-9c1cf2871994)]
michael@0: interface nsIUpdateChecker : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Checks for available updates, notifying a listener of the results.
michael@0:    * @param   listener
michael@0:    *          An object implementing nsIUpdateCheckListener which is notified
michael@0:    *          of the results of an update check.
michael@0:    * @param   force
michael@0:    *          Forces the checker to check for updates, regardless of the
michael@0:    *          current value of the user's update settings. This is used by
michael@0:    *          any piece of UI that offers the user the imperative option to
michael@0:    *          check for updates now, regardless of their update settings.
michael@0:    *          force will not work if the system administrator has locked
michael@0:    *          the app.update.enabled preference.
michael@0:    */
michael@0:   void checkForUpdates(in nsIUpdateCheckListener listener, in boolean force);
michael@0: 
michael@0:   /**
michael@0:    * Constants for the |stopChecking| function that tell the Checker how long
michael@0:    * to stop checking:
michael@0:    *
michael@0:    * CURRENT_CHECK:     Stops the current (active) check only
michael@0:    * CURRENT_SESSION:   Stops all checking for the current session
michael@0:    * ANY_CHECKS:        Stops all checking, any session from now on
michael@0:    *                    (disables update checking preferences)
michael@0:    */
michael@0:   const unsigned short CURRENT_CHECK    = 1;
michael@0:   const unsigned short CURRENT_SESSION  = 2;
michael@0:   const unsigned short ANY_CHECKS       = 3;
michael@0: 
michael@0:   /**
michael@0:    * Ends any pending update check.
michael@0:    * @param   duration
michael@0:    *          A value representing the set of checks to stop doing.
michael@0:    */
michael@0:   void stopChecking(in unsigned short duration);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * An interface describing a global application service that handles performing
michael@0:  * background update checks and provides utilities for selecting and
michael@0:  * downloading update patches.
michael@0:  */
michael@0: [scriptable, uuid(9f9b51f5-340e-47ce-85ae-9eb077c6cd39)]
michael@0: interface nsIApplicationUpdateService : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Checks for available updates in the background using the listener provided
michael@0:    * by the application update service for background checks.
michael@0:    */
michael@0:   void checkForBackgroundUpdates();
michael@0: 
michael@0:   /**
michael@0:    * The Update Checker used for background update checking.
michael@0:    */
michael@0:   readonly attribute nsIUpdateChecker backgroundChecker;
michael@0: 
michael@0:   /**
michael@0:    * Selects the best update to install from a list of available updates.
michael@0:    * @param   updates
michael@0:    *          An array of updates that are available
michael@0:    * @param   updateCount
michael@0:    *          The length of the |updates| array
michael@0:    */
michael@0:   nsIUpdate selectUpdate([array, size_is(updateCount)] in nsIUpdate updates,
michael@0:                          in unsigned long updateCount);
michael@0: 
michael@0:   /**
michael@0:    * Adds a listener that receives progress and state information about the
michael@0:    * update that is currently being downloaded, e.g. to update a user
michael@0:    * interface.
michael@0:    * @param   listener
michael@0:    *          An object implementing nsIRequestObserver and optionally
michael@0:    *          nsIProgressEventSink that is to be notified of state and
michael@0:    *          progress information as the update is downloaded.
michael@0:    */
michael@0:   void addDownloadListener(in nsIRequestObserver listener);
michael@0: 
michael@0:   /**
michael@0:    * Removes a listener that is receiving progress and state information
michael@0:    * about the update that is currently being downloaded.
michael@0:    * @param   listener
michael@0:    *          The listener object to remove.
michael@0:    */
michael@0:   void removeDownloadListener(in nsIRequestObserver listener);
michael@0: 
michael@0:   /**
michael@0:    *
michael@0:    */
michael@0:   AString downloadUpdate(in nsIUpdate update, in boolean background);
michael@0: 
michael@0:   /**
michael@0:    * Apply the OS update which has been downloaded and staged as applied.
michael@0:    * @param   update 
michael@0:    *          The update has been downloaded and staged as applied.
michael@0:    * @throws  if the update object is not an OS update.
michael@0:    */
michael@0:   void applyOsUpdate(in nsIUpdate update);
michael@0: 
michael@0:   /**
michael@0:    * Get the Active Updates directory
michael@0:    * @returns An nsIFile for the active updates directory.
michael@0:    */
michael@0:   nsIFile getUpdatesDirectory();
michael@0: 
michael@0:   /**
michael@0:    * Pauses the active update download process
michael@0:    */
michael@0:   void pauseDownload();
michael@0: 
michael@0:   /**
michael@0:    * Whether or not there is an download happening at the moment.
michael@0:    */
michael@0:   readonly attribute boolean isDownloading;
michael@0: 
michael@0:   /**
michael@0:    * Whether or not the Update Service can check for updates. This is a function
michael@0:    * of whether or not application update is disabled by the application and the
michael@0:    * platform the application is running on.
michael@0:    */
michael@0:   readonly attribute boolean canCheckForUpdates;
michael@0: 
michael@0:   /**
michael@0:    * Whether or not the Update Service can download and install updates.
michael@0:    * On Windows, this is a function of whether or not the maintenance service
michael@0:    * is installed and enabled. On other systems, and as a fallback on Windows,
michael@0:    * this depends on whether the current user has write access to the install
michael@0:    * directory.
michael@0:    */
michael@0:   readonly attribute boolean canApplyUpdates;
michael@0: 
michael@0:   /**
michael@0:    * Whether or not a different instance is handling updates of this
michael@0:    * installation.  This currently only ever returns true on Windows
michael@0:    * when 2 instances of an application are open or when both the Metro
michael@0:    * and Desktop browsers are open.  Only one of the instances will actually
michael@0:    * handle updates for the installation.
michael@0:    */
michael@0:   readonly attribute boolean isOtherInstanceHandlingUpdates;
michael@0: 
michael@0:   /**
michael@0:    * Whether the Update Service is able to stage updates.
michael@0:    */
michael@0:   readonly attribute boolean canStageUpdates;
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * An interface describing a component which handles the job of processing
michael@0:  * an update after it's been downloaded.
michael@0:  */
michael@0: [scriptable, uuid(74439497-d796-4915-8cef-3dfe43027e4d)]
michael@0: interface nsIUpdateProcessor : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Processes the update which has been downloaded.
michael@0:    * This happens without restarting the application.
michael@0:    * On Windows, this can also be used for switching to an applied
michael@0:    * update request.
michael@0:    * @param update The update being applied, or null if this is a switch
michael@0:    *               to updated application request.  Must be non-null on GONK.
michael@0:    */
michael@0:   void processUpdate(in nsIUpdate update);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * An interface describing a global application service that maintains a list
michael@0:  * of updates previously performed as well as the current active update.
michael@0:  */
michael@0: [scriptable, uuid(c5df56de-919d-406b-aaf9-106dfa9b685b)]
michael@0: interface nsIUpdateManager : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Gets the update at the specified index
michael@0:    * @param   index
michael@0:    *          The index within the updates array
michael@0:    * @returns The nsIUpdate object at the specified index
michael@0:    */
michael@0:   nsIUpdate getUpdateAt(in long index);
michael@0: 
michael@0:   /**
michael@0:    * Gets the total number of updates in the history list.
michael@0:    */
michael@0:   readonly attribute long updateCount;
michael@0: 
michael@0:   /**
michael@0:    * The active (current) update. The active update is not in the history list.
michael@0:    */
michael@0:   attribute nsIUpdate activeUpdate;
michael@0: 
michael@0:   /**
michael@0:    * Saves all updates to disk.
michael@0:    */
michael@0:   void saveUpdates();
michael@0: 
michael@0:   /**
michael@0:    * Refresh the update status based on the information in update.status.
michael@0:    */
michael@0:   void refreshUpdateStatus(in nsIUpdate update);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * An interface describing an object that can show various kinds of Update
michael@0:  * notification UI to the user.
michael@0:  */
michael@0: [scriptable, uuid(599fd3c6-ec68-4499-ada5-2997739c97a6)]
michael@0: interface nsIUpdatePrompt : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Shows the application update checking user interface and checks if there
michael@0:    * is an update available.
michael@0:    */
michael@0:   void checkForUpdates();
michael@0: 
michael@0:   /**
michael@0:    * Shows the application update available user interface advising that an
michael@0:    * update is available for download and install. If the app.update.silent
michael@0:    * preference is true or the user interface is already displayed the call will
michael@0:    * be a no-op.
michael@0:    * @param   update
michael@0:    *          The nsIUpdate object to be downloaded and installed
michael@0:    */
michael@0:   void showUpdateAvailable(in nsIUpdate update);
michael@0: 
michael@0:   /**
michael@0:    * Shows the application update downloaded user interface advising that an
michael@0:    * update has now been downloaded and a restart is necessary to complete the
michael@0:    * update. If background is true (e.g. the download was not user initiated)
michael@0:    * and the app.update.silent preference is true the call will be a no-op.
michael@0:    * @param   update
michael@0:    *          The nsIUpdate object that was downloaded
michael@0:    * @param   background
michael@0:    *          Less obtrusive UI, starting with a non-modal notification alert
michael@0:    */
michael@0:   void showUpdateDownloaded(in nsIUpdate update,
michael@0:                             [optional] in boolean background);
michael@0: 
michael@0:   /**
michael@0:    * Shows the application update installed user interface advising that an
michael@0:    * update was installed successfully. If the app.update.silent preference is
michael@0:    * true, the app.update.showInstalledUI preference is false, or the user
michael@0:    * interface is already displayed the call will be a no-op.
michael@0:    */
michael@0:   void showUpdateInstalled();
michael@0: 
michael@0:   /**
michael@0:    * Shows the application update error user interface advising that an error
michael@0:    * occurred while checking for or applying an update. If the app.update.silent
michael@0:    * preference is true the call will be a no-op.
michael@0:    * @param   update
michael@0:    *          An nsIUpdate object representing the update that could not be
michael@0:    *          installed. The nsIUpdate object will not be the actual update when
michael@0:    *          the error occurred during an update check and will instead be an
michael@0:    *          nsIUpdate object with the error information for the update check.
michael@0:    */
michael@0:   void showUpdateError(in nsIUpdate update);
michael@0: 
michael@0:   /**
michael@0:    * Shows a list of all updates installed to date.
michael@0:    * @param   parent
michael@0:    *          An nsIDOMWindow to set as the parent for this window. Can be null.
michael@0:    */
michael@0:   void showUpdateHistory(in nsIDOMWindow parent);
michael@0: };