/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is the Application Update Service * * The Initial Developer of the Original Code is Google Inc. * Portions created by the Initial Developer are Copyright (C) 2005 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Ben Goodger * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #include "nsISupports.idl" interface nsIDOMDocument; interface nsIDOMElement; interface nsIDOMWindow; interface nsIRequest; interface nsIRequestObserver; interface nsISimpleEnumerator; interface nsITimerCallback; interface nsIXMLHttpRequest; /** * An interface that describes an object representing a patch file that can * be downloaded and applied to a version of this application so that it * can be updated. */ [scriptable, uuid(56863a67-bd69-42de-9f40-583e625b457d)] interface nsIUpdatePatch : nsISupports { /** * The type of this patch: * "partial" A binary difference between two application versions * "complete" A complete patch containing all of the replacement files * to update to the new version */ attribute AString type; /** * The URL this patch was being downloaded from */ attribute AString URL; /** * The hash function to use when determining this file's integrity */ attribute AString hashFunction; /** * The value of the hash function named above that should be computed if * this file is not corrupt. */ attribute AString hashValue; /** * The size of this file, in bytes. */ attribute unsigned long size; /** * The state of this patch */ attribute AString state; /** * true if this patch is currently selected as the patch to be downloaded and * installed for this update transaction, false if another patch from this * update has been selected. */ attribute boolean selected; /** * Serializes this patch object into a DOM Element * @param updates * The document to serialize into * @returns The DOM Element created by the serialization process */ nsIDOMElement serialize(in nsIDOMDocument updates); }; /** * An interface that describes an object representing an available update to * the current application - this update may have several available patches * from which one must be selected to download and install, for example we * might select a binary difference patch first and attempt to apply that, * then if the application process fails fall back to downloading a complete * file-replace patch. This object also contains information about the update * that the front end and other application services can use to learn more * about what is going on. */ [scriptable, uuid(9d6a388b-2e0c-4d0e-9a60-5c9739a7ada5)] interface nsIUpdate : nsISupports { /** * The type of update: * "major" A major new version of the Application * "minor" A minor update to the Application (e.g. security update) */ attribute AString type; /** * The name of the update, or " " */ attribute AString name; /** * The Application version of this update. */ attribute AString version; /** * The Toolkit version of this update. */ attribute AString platformVersion; /** * The Addon version of this update. Used by the Extension System to track * compatibility of installed addons with this update. */ attribute AString extensionVersion; /** * The Build ID of this update. Used to determine a particular build, down * to the hour, minute and second of its creation. This allows the system * to differentiate between several nightly builds with the same |version| * for example. */ attribute AString buildID; /** * The URL to a page which offers details about the content of this * update. Ideally, this page is not the release notes but some other page * that summarizes the differences between this update and the previous, * which also links to the release notes. */ attribute AString detailsURL; /** * The URL to a HTML fragment that contains a license for this update. If * this is specified, the user is shown the license file after they choose * to install the update and they must agree to it before the download * commences. */ attribute AString licenseURL; /** * The URL to the Update Service that supplied this update. */ attribute AString serviceURL; /** * The channel used to retrieve this update from the Update Service. */ attribute AString channel; /** * Whether or not the update being downloaded is a complete replacement of * the user's existing installation or a patch representing the difference * between the new version and the previous version. */ attribute boolean isCompleteUpdate; /** * Whether or not the update is a security update or not. If this is true, * then we present more serious sounding user interface messages to the * user. */ attribute boolean isSecurityUpdate; /** * When the update was installed. */ attribute long long installDate; /** * A message associated with this update, if any. */ attribute AString statusText; /** * The currently selected patch for this update. */ readonly attribute nsIUpdatePatch selectedPatch; /** * The state of the selected patch: * "downloading" The update is being downloaded. * "pending" The update is ready to be applied. * "applying" The update is being applied. * "succeeded" The update was successfully applied. * "download-failed" The update failed to be downloaded. * "failed" The update failed to be applied. */ attribute AString state; /** * A numeric error code that conveys additional information about the state * of a failed update. If the update is not in the "failed" state, then this * value is zero. * * TODO: Define typical error codes (for now, see updater/errors.h) */ attribute long errorCode; /** * The number of patches supplied by this update. */ readonly attribute unsigned long patchCount; /** * Retrieves a patch. * @param index * The index of the patch to retrieve. * @returns The nsIUpdatePatch at the specified index. */ nsIUpdatePatch getPatchAt(in unsigned long index); /** * Serializes this update object into a DOM Element * @param updates * The document to serialize into * @returns The DOM Element created by the serialization process */ nsIDOMElement serialize(in nsIDOMDocument updates); }; /** * An interface describing an object that listens to the progress of an update * check operation. This object is notified as the check continues, finishes * and if it has an error. */ [scriptable, uuid(8cbceb6e-8e27-46f2-8808-444c6499f836)] interface nsIUpdateCheckListener : nsISupports { /** * Called every time there is a progress notification loading the Update * Service file. * @param request * The nsIXMLHttpRequest handling the update check. * @param position * The current byte downloaded * @param totalSize * The total number of bytes that have to be downloaded */ void onProgress(in nsIXMLHttpRequest request, in unsigned long position, in unsigned long totalSize); /** * The update check was completed. * @param request * The nsIXMLHttpRequest handling the update check. * @param updates * An array of nsIUpdate objects listing available updates. * @param updateCount * The size of the |updates| array. */ void onCheckComplete(in nsIXMLHttpRequest request, [array, size_is(updateCount)] in nsIUpdate updates, in unsigned long updateCount); /** * An error occurred while loading the remote update service file. * @param request * The nsIXMLHttpRequest handling the update check. * @param update * A nsIUpdate object that contains details about the * error in its |statusText| property. */ void onError(in nsIXMLHttpRequest request, in nsIUpdate update); }; /** * An interface describing an object that knows how to check for updates. */ [scriptable, uuid(877ace25-8bc5-452a-8586-9c1cf2871994)] interface nsIUpdateChecker : nsISupports { /** * Checks for available updates, notifying a listener of the results. * @param listener * An object implementing nsIUpdateCheckListener which is notified * of the results of an update check. * @param force * Forces the checker to check for updates, regardless of the * current value of the user's update settings. This is used by * any piece of UI that offers the user the imperative option to * check for updates now, regardless of their update settings. * force will not work if the system administrator has locked * the app.update.enabled preference. */ void checkForUpdates(in nsIUpdateCheckListener listener, in boolean force); /** * Constants for the |stopChecking| function that tell the Checker how long * to stop checking: * * CURRENT_CHECK: Stops the current (active) check only * CURRENT_SESSION: Stops all checking for the current session * ANY_CHECKS: Stops all checking, any session from now on * (disables update checking preferences) */ const unsigned short CURRENT_CHECK = 1; const unsigned short CURRENT_SESSION = 2; const unsigned short ANY_CHECKS = 3; /** * Ends any pending update check. * @param duration * A value representing the set of checks to stop doing. */ void stopChecking(in unsigned short duration); }; /** * An interface describing a global application service that handles performing * background update checks and provides utilities for selecting and * downloading update patches. */ [scriptable, uuid(9849c4bf-5197-4d22-baa8-e3b44a1703d2)] interface nsIApplicationUpdateService : nsISupports { /** * The Update Checker used for background update checking. */ readonly attribute nsIUpdateChecker backgroundChecker; /** * Selects the best update to install from a list of available updates. * @param updates * An array of updates that are available * @param updateCount * The length of the |updates| array */ nsIUpdate selectUpdate([array, size_is(updateCount)] in nsIUpdate updates, in unsigned long updateCount); /** * Adds a listener that receives progress and state information about the * update that is currently being downloaded, e.g. to update a user * interface. * @param listener * An object implementing nsIRequestObserver and optionally * nsIProgressEventSink that is to be notified of state and * progress information as the update is downloaded. */ void addDownloadListener(in nsIRequestObserver listener); /** * Removes a listener that is receiving progress and state information * about the update that is currently being downloaded. * @param listener * The listener object to remove. */ void removeDownloadListener(in nsIRequestObserver listener); /** * */ AString downloadUpdate(in nsIUpdate update, in boolean background); /** * Pauses the active update download process */ void pauseDownload(); /** * Whether or not there is an download happening at the moment. */ readonly attribute boolean isDownloading; /** * Whether or not the Update Service can download and install updates. * This is a function of whether or not the current user has access * privileges to the install directory. */ readonly attribute boolean canUpdate; }; /** * An interface describing a global application service that maintains a list * of updates previously performed as well as the current active update. */ [scriptable, uuid(fede66a9-9f96-4507-a22a-775ee885577e)] interface nsIUpdateManager : nsISupports { /** * Gets the update at the specified index * @param index * The index within the updates array * @returns The nsIUpdate object at the specified index */ nsIUpdate getUpdateAt(in long index); /** * Gets the total number of updates in the history list. */ readonly attribute long updateCount; /** * The active (current) update. The active update is not in the history list. */ attribute nsIUpdate activeUpdate; /** * Saves all updates to disk. */ void saveUpdates(); }; /** * An interface describing an object that can show various kinds of Update * notification UI to the user. */ [scriptable, uuid(599fd3c6-ec68-4499-ada5-2997739c97a6)] interface nsIUpdatePrompt : nsISupports { /** * Shows a user interface that checks for and then displays the available * updates. */ void checkForUpdates(); /** * Show a message advising that an update is available for download and * install. * @param update * The update to be downloaded and installed */ void showUpdateAvailable(in nsIUpdate update); /** * Show a message advising that an update has now been downloaded and that * a restart is necessary to complete the update. * @param update * The update that was downloaded * @param background * Less obtrusive UI, starting with a non-modal notification alert */ void showUpdateDownloaded(in nsIUpdate update, [optional] in boolean background); /** * Shows a message that an update was installed successfully. */ void showUpdateInstalled(); /** * Shows an error message UI telling the user about some kind of update * failure, e.g. failure to apply patch. * @param update * The nsIUpdate object which we could not install */ void showUpdateError(in nsIUpdate update); /** * Shows a list of all updates installed to date. * @param parent * A parent window to anchor this window to. Can be null. */ void showUpdateHistory(in nsIDOMWindow parent); }; /** * An interface describing a global application service that allows long * duration (e.g. 1-7 or more days, weeks or months) timers to be registered * and then fired. */ [scriptable, uuid(0765c92c-6145-4253-9db4-594d8023087e)] interface nsIUpdateTimerManager : nsISupports { /** * Register an interval with the timer manager. The timer manager * periodically checks to see if the interval has expired and if it has * calls the specified callback. This is persistent across application * restarts and can handle intervals of long durations. * @param id * An id that identifies the interval, used for persistence * @param callback * A nsITimerCallback object that is notified when the interval * expires * @param interval * The length of time, in seconds, of the interval */ void registerTimer(in AString id, in nsITimerCallback callback, in unsigned long interval); };