diff options
Diffstat (limited to 'toolkit/mozapps/update/nsIUpdateService.idl')
| -rw-r--r-- | toolkit/mozapps/update/nsIUpdateService.idl | 773 |
1 files changed, 773 insertions, 0 deletions
diff --git a/toolkit/mozapps/update/nsIUpdateService.idl b/toolkit/mozapps/update/nsIUpdateService.idl new file mode 100644 index 0000000000..920b307c80 --- /dev/null +++ b/toolkit/mozapps/update/nsIUpdateService.idl @@ -0,0 +1,773 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +#include "nsISupports.idl" + +interface nsIRequest; +interface nsIRequestObserver; +interface nsISimpleEnumerator; +interface nsIFile; + +webidl Element; +webidl Document; + +/** + * 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(dc8fb8a9-3a53-4031-9469-2a5197ea30e7)] +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 + */ + readonly attribute AString type; + + /** + * The URL this patch was being downloaded from + */ + readonly attribute AString URL; + + /** + * The final URL this patch was being downloaded from + */ + attribute AString finalURL; + + /** + * The size of this file, in bytes. + */ + readonly attribute unsigned long size; + + /** + * The state of this patch + */ + 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 the value is + * zero. The possible values are located in common/updatererrors.h and values between + * 80 and 99 are in nsUpdateService.js. + */ + attribute long errorCode; + + /** + * 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 + */ + Element serialize(in Document 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(e094c045-f4ff-41fd-92da-cd2effd2c7c9)] +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) + */ + readonly attribute AString type; + + /** + * The name of the update, or "<Application Name> <Update Version>" + */ + readonly attribute AString name; + + /** + * The string to display in the user interface for the version. If you want + * a real version number use appVersion. + */ + readonly attribute AString displayVersion; + + /** + * The Application version of this update. + */ + readonly attribute AString appVersion; + + /** + * The Application version prior to the application being updated. + */ + readonly attribute AString previousAppVersion; + + /** + * 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. + */ + readonly 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. + */ + readonly attribute AString detailsURL; + + /** + * The URL to the Update Service that supplied this update. + */ + readonly attribute AString serviceURL; + + /** + * The channel used to retrieve this update from the Update Service. + */ + readonly attribute AString channel; + + /** + * Whether the update is no longer supported on this system. + */ + readonly attribute boolean unsupported; + + /** + * Allows overriding the default amount of time in seconds before prompting the + * user to apply an update. If not specified, the value of + * app.update.promptWaitTime will be used. + */ + attribute long long promptWaitTime; + + /** + * 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; + + /** + * 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. + * "pending-service" The update is ready to be applied with the service. + * "pending-elevate" The update is ready to be applied but requires elevation. + * "applying" The update is being applied. + * "applied" The update is ready to be switched to. + * "applied-os" The update is OS update and to be installed. + * "applied-service" The update is ready to be switched to with the service. + * "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 the value is + * zero. The possible values are located in common/updatererrors.h and values between + * 80 and 99 are in nsUpdateService.js. + */ + attribute long errorCode; + + /** + * Whether an elevation failure has been encountered for this update. + */ + attribute boolean elevationFailure; + + /** + * 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 + */ + Element serialize(in Document updates); +}; + +/** + * An interface describing the result of an update check. + */ +[scriptable, uuid(bff08110-e79f-4a9f-a56c-348170f9208a)] +interface nsIUpdateCheckResult : nsISupports +{ + /** + * True if update checks are allowed. otherwise false. + */ + readonly attribute boolean checksAllowed; + + /** + * True if the update check succeeded, otherwise false. Guaranteed to be false + * if checksAllowed is false. + */ + readonly attribute boolean succeeded; + + /** + * The XMLHttpRequest handling the update check. Depending on exactly how the + * check failed, it's possible for this to be null. + */ + readonly attribute jsval request; + + /** + * If `!checksAllowed`, this will always be an empty array. + * + * If `succeeded`, this will be an array of nsIUpdate objects listing + * available updates. The length will be 0 if there are no available updates. + * + * If `checksAllowed && !succeeded`, this will be an array containing exactly + * one nsIUpdate object. Most of the attributes will have no useful value + * since we did not successfully retrieve an update, but `errorCode` and + * `statusText` will be set to values that describe the error encountered when + * checking for updates. + */ + readonly attribute Array<nsIUpdate> updates; +}; + +/** + * An interface describing an update check that may still be in-progress or may + * be completed. + */ +[scriptable, uuid(2620aa24-27aa-463a-b6d2-0734695c1f7a)] +interface nsIUpdateCheck : nsISupports +{ + /** + * An id that represents a particular update check. Can be passed to + * nsIUpdateChecker::stopCheck. + * + * Ids are guaranteed to be truthy (non-zero) and non-repeating. This is + * just for caller convenience so that (a) it's not an error to cancel a check + * that already completed and (b) they can easily check `if (idVar)` to see if + * they stored an id. + */ + readonly attribute long id; + + /** + * A promise that resolves to the results of the update check, which will be + * of type nsIUpdateCheckResult. + */ + readonly attribute Promise result; +}; + +/** + * An interface describing an object that knows how to check for updates. It can + * perform multiple update checks simultaneously or consolidate multiple check + * requests into a single web request, depending on whether the parameters + * specified for update checking match. + */ +[scriptable, uuid(877ace25-8bc5-452a-8586-9c1cf2871994)] +interface nsIUpdateChecker : nsISupports +{ + /** + * Enumerated constants. See the `checkType` parameter of `checkForUpdates` + * for details. + */ + const long BACKGROUND_CHECK = 1; + const long FOREGROUND_CHECK = 2; + + /** + * Checks for available updates. + * @param checkType + * Must be either BACKGROUND_CHECK or FOREGROUND_CHECK. If + * FOREGROUND_CHECK is specified, the normal + * nsIApplicationUpdateService.canCheckForUpdates check will be + * overridden and the "force" parameter will be included in the + * update URL. + * + * Regarding the "force" parameter: + * Sometimes the update server throttles updates, arbitrarily + * refraining from returning the newest version to some clients. The + * force parameter overrides this behavior and tells it to + * unconditionally return the newest available version. + * + * It's worth noting that the update server technically supports + * forcing the decision in the other direction too, preventing + * the newest version from being returned, but this interface doesn't + * actually support setting the force parameter this way. If the + * force parameter is used, it always forces getting the newest + * version. + * @returns An nsIUpdateCheck object that describes the update check and + * provides a Promise that resolves to the update check results. + */ + nsIUpdateCheck checkForUpdates(in long checkType); + + /** + * Gets the update URL. + * @param checkType + * Must be either BACKGROUND_CHECK or FOREGROUND_CHECK. See the + * checkType parameter of nsIUpdateChecker.checkForUpdates for more + * details. + * @returns A Promise that resolves to the URL to be used to check for + * updates, as a string. This URL should resolve to an XML describing + * the updates that are available to the current Firefox + * installation. + */ + Promise getUpdateURL(in long checkType); + + /** + * Ends a pending update check. Has no effect if the id is invalid or the + * check corresponding to the id has already completed. + * + * Note that because `nsIUpdateChecker` potentially combines multiple update + * checks, it is not guaranteed that this will actually cause the update + * request to be aborted. It also doesn't guarantee that + * `nsIUpdateCheck.result` will resolve when this is called. This merely marks + * the check id as cancelled and only if there are no other check ids waiting + * on the request does it abort it. + * + * @param id + * The id of a check to stop (accessible via nsIUpdateCheck). + */ + void stopCheck(in long id); + + /** + * Ends all pending update checks. + */ + void stopAllChecks(); +}; + +/** + * An interface describing a global application service that handles performing + * background update checks and provides utilities for selecting and + * downloading update patches. + */ +[scriptable, uuid(1107d207-a263-403a-b268-05772ec10757)] +interface nsIApplicationUpdateService : nsISupports +{ + /** + * Checks for available updates in the background using the listener provided + * by the application update service for background checks. + * @returns true if the update check was started, false if not. Note that the + * check starting does not necessarily mean that the check will + * succeed or that an update will be downloaded. + */ + bool checkForBackgroundUpdates(); + + /** + * Selects the best update to install from a list of available updates. + * @param updates + * An array of updates that are available + */ + nsIUpdate selectUpdate(in Array<nsIUpdate> updates); + + /** + * Adds a listener that receives progress and state information about the + * update that is currently being downloaded, e.g. to update a user + * interface. Registered listeners will be called for all downloads and all + * updates during a browser session; they are not automatically removed + * following the first (successful or failed) download. + * @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); + + /** + * Starts downloading the update passed. Once the update is downloaded, it + * will automatically be prepared for installation. + * + * @param update + * The update to download. + * @returns A promise that resolves to `true` if an update download was + * started, otherwise `false. + */ + Promise downloadUpdate(in nsIUpdate update); + + /** + * This is the function called internally by the Application Update Service + * when an update check is complete. Though this can be used to potentially + * start an update download, `downloadUpdate` should used for that. + * This is mostly exposed in the interface in order to make it accessible for + * testing. + */ + Promise onCheckComplete(in nsIUpdateCheckResult result); + + /** + * Stop the active update download process. This is the equivalent of + * calling nsIRequest::Cancel on the download's nsIRequest. When downloading + * with nsIIncrementalDownload, this will leave the partial download in place. + * When downloading with BITS, any partial download progress will be removed. + * + * @returns A Promise that resolves once the download has been stopped. + */ + Promise stopDownload(); + + /** + * There are a few things that can disable the Firefox updater at runtime + * such as Enterprise Policies. If this attribute is set to true, update + * should not be performed and most update interfaces will return errors. + */ + readonly attribute boolean disabled; + + /** + * Whether or not the Update Service can usually check for updates. This is a + * function of whether or not application update is disabled by the + * application and the platform the application is running on. + */ + readonly attribute boolean canUsuallyCheckForUpdates; + + /** + * Whether or not the Update Service can check for updates right now. This is + * a function of whether or not application update is disabled by the + * application, the platform the application is running on, and transient + * factors such as whether other instances are running. + */ + readonly attribute boolean canCheckForUpdates; + + /** + * Whether or not the installation requires elevation. Currently only + * implemented on OSX, returns false on other platforms. + */ + readonly attribute boolean elevationRequired; + + /** + * Whether or not the Update Service can usually download and install updates. + * On Windows, this is a function of whether or not the maintenance service + * is installed and enabled. On other systems, and as a fallback on Windows, + * this depends on whether the current user has write access to the install + * directory. + */ + readonly attribute boolean canUsuallyApplyUpdates; + + /** + * Whether or not the Update Service can download and install updates right now. + * On Windows, this is a function of whether or not the maintenance service + * is installed and enabled. On other systems, and as a fallback on Windows, + * this depends on whether the current user has write access to the install + * directory. On all systems, this includes transient factors such as whether + * other instances are running. + */ + readonly attribute boolean canApplyUpdates; + + /** + * Whether or not a different instance is handling updates of this + * installation. This currently only ever returns true on Windows + * when 2 instances of an application are open. Only one of the instances + * will actually handle updates for the installation. + */ + readonly attribute boolean isOtherInstanceHandlingUpdates; + + /** + * Whether the Update Service is usually able to stage updates. + */ + readonly attribute boolean canUsuallyStageUpdates; + + /** + * Whether the Update Service is able to stage updates right now. On all + * systems, this includes transient factors such as whether other instances + * are running. + */ + readonly attribute boolean canStageUpdates; + + /** + * On Windows, whether the Update Service can usually use BITS. + */ + readonly attribute boolean canUsuallyUseBits; + + /** + * On Windows, whether the Update Service can use BITS right now. This + * includes transient factors such as whether other instances are running. + */ + readonly attribute boolean canUseBits; + + /** + * Indicates whether or not the enterprise policy that allows only manual + * updating is active. One of the features of this policy is not being + * notified of updates; you are intended to need to manually tell Firefox + * that you want to update each time that you want to do so. + * + * This policy has some implications for the way that update checks work. We + * don't want to do background update checks. Without being able to notify + * the user, there's not really anything to do if we find one. However, we + * will allow "automatic" update checks when loading the update interfaces + * in about:preferences, the About Dialog, etc. When those interfaces are + * open, we do have a way of telling the user about an update without + * bothering them with a doorhanger. + */ + readonly attribute boolean manualUpdateOnly; + + /** + * This can be set to true to prevent updates being processed beyond starting + * an update download. This should only be used when we are being run as a + * background task. + * This exists to prevent a particularly fast update download from beginning + * to stage while the background task is shutting down. + */ + attribute boolean onlyDownloadUpdatesThisSession; + + /** + * Enumerated constants describing the update states that the updater can be + * in. + * Note that update checking is not part of the states that this interface + * can recognize and report. This is for two reasons: 1) there are multiple + * kinds of update checks (ex: foreground and background) and it would make + * the current update state more complicated if we wanted to track both, and + * 2) there isn't really any reason to concern ourselves with current update + * checks because nsIUpdateChecker will seamlessly combine multiple identical + * update checks into a single request without the caller having to worry + * about its internal state. + */ + // An update download hasn't started yet, or we failed at some point in the + // update process and aborted. + const long STATE_IDLE = 1; + // An update is currently being downloaded. + // This state begins once nsIApplicationUpdateService.downloadUpdate resolves + // to `true`. + // Note that we may be downloading an update but not be in this state because + // we can download a second update while we have an update ready. But there + // isn't much reason for currentState to track the second update. We know that + // it will always be in the downloading state until it finishes downloading + // and becomes the ready update. See STATE_UPDATE_SWAP for more details. + const long STATE_DOWNLOADING = 2; + // An update is currently being staged. Note that we do not always stage + // updates. + const long STATE_STAGING = 4; + // An update is pending. If the browser restarts now, it will be installed. + // Note that although "pending" is one of the potential update statuses, this + // does not correspond to exactly that status. + const long STATE_PENDING = 5; + // We had an update pending. Then we downloaded another update. Now we are + // in the process of removing the old update and swapping the new update into + // its place. + // Note that when the state initially changes to `STATE_SWAP`, the new update + // will be in `nsIUpdateManager.downloadingUpdate` but it will be moved into + // `nsIUpdateManager.readyUpdate` before moving to the next state. + const long STATE_SWAP = 6; + + /** + * Gets a string describing the state (mostly intended to be make console + * logs easier to read). + */ + AString getStateName(in long state); + + /** + * The current state of the application updater. Returns one of the enumerated + * constants, above. + * + * The expected flow looks like this: + * STATE_IDLE -> STATE_DOWNLOADING -> STATE_STAGING -> STATE_PENDING + * If a failure is encountered at some time, we go back to STATE_IDLE. + * If staging is not enabled, STATE_STAGING will be skipped. + * + * We may download additional updates after we reach STATE_PENDING. If we do, + * the state will remain at STATE_PENDING while we download the new update. If + * we restart during that time, the pending update will be installed and the + * partially downloaded update will be discarded. If a download completes + * successfully, there will be a brief period where STATE_PENDING is no longer + * correct, because the Update Service is in the process of removing the old + * update and replacing it with the new update. So if we restart during that + * period, the update will not be correctly installed. Thus, we switch away + * from STATE_PENDING to STATE_SWAP during that time. Assuming that the swap + * is successful, the state will then switch back STATE_STAGING (assuming that + * staging is enabled), then to STATE_PENDING. So the full expected state flow + * looks more like this: + * STATE_IDLE -> STATE_DOWNLOADING -> STATE_STAGING -> STATE_PENDING -> + * STATE_SWAP -> STATE_STAGING -> STATE_PENDING -> + * STATE_SWAP -> STATE_STAGING -> STATE_PENDING -> ... + * (Omitting STATE_STAGING if staging is not enabled). + */ + readonly attribute long currentState; + + /** + * A Promise that resolves immediately after `currentState` changes. + */ + readonly attribute Promise stateTransition; +}; + +/** + * An interface describing a component which handles the job of processing + * an update after it's been downloaded. + */ +[scriptable, uuid(74439497-d796-4915-8cef-3dfe43027e4d)] +interface nsIUpdateProcessor : nsISupports +{ + /** + * Stages an update while the application is running. + */ + void processUpdate(); + + /** + * The installer writes an installation-specific registry key if the + * Maintenance Service can be used for this installation. This function checks + * for that key's existence (it does not read or verify the key's contents). + * + * This function should only be called on Windows. + * + * @returns true if the registry key exists, false if it does not. + * @throws NS_ERROR_NOT_AVAILABLE + * If registry access fails. + * @throws NS_ERROR_NOT_IMPLEMENTED + * If this is called on a non-Windows platform. + */ + bool getServiceRegKeyExists(); +}; + +/** + * Upon creation, which should happen early during startup, the sync manager + * creates/opens and locks a file. All other running instances of the same + * installation of the app also open the same lock, so we can use it to + * determine whether any other instance is running. If so, we'll temporarily + * hold off on performing update tasks until there are no other instances or + * until a timeout expires, whichever comes first. That way we can avoid + * updating behind the back of copies that are still running, so we don't force + * all running instances to restart (see bug 1366808, where an error was added + * informing the user of the need to restart any running instances that have + * been updated). + */ +[scriptable, uuid(cf4c4487-66d9-4e18-a2e9-39002245332f)] +interface nsIUpdateSyncManager : nsISupports +{ + /** + * Returns whether another instance of this application is running. + * @returns true if another instance has the lock open, false if not + */ + bool isOtherInstanceRunning(); + + /** + * Should only be used for testing. + * + * Closes and reopens the lock file, possibly under a different name if a + * parameter is given (or the path hash has changed, which should only happen + * if a test is forcing it). + */ + void resetLock([optional] in nsIFile anAppFile); +}; + +/** + * An interface describing a global application service that maintains a list + * of updates previously performed as well as the current active update. + */ +[scriptable, uuid(0f1098e9-a447-4af9-b030-6f8f35c85f89)] +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. + */ + long getUpdateCount(); + + /** + * The update that has been downloaded, or null if there isn't one. + */ + attribute nsIUpdate readyUpdate; + + /** + * The update that is currently downloading, or null if there isn't one. + * An update is no longer considered to be downloading once onStopRequest is + * called. This means that both onStopRequest handlers for download listeners + * and observers of the "update-downloaded" topic should expect the update + * that was just downloaded to be stored in readyUpdate, not + * downloadingUpdate. + */ + attribute nsIUpdate downloadingUpdate; + + /** + * Adds the specified update to the update history. The update history is + * limited to 10 items, so this may also remove the last item from the + * history. + */ + void addUpdateToHistory(in nsIUpdate update); + + /** + * Saves all updates to disk. + */ + void saveUpdates(); + + /** + * Refresh the update status based on the information in update.status. + * + * @returns A Promise that resolves after the update status is refreshed. + */ + Promise refreshUpdateStatus(); + + /** + * The user agreed to proceed with an elevated update and we are now + * permitted to show an elevation prompt. + */ + void elevationOptedIn(); + + /** + * These functions both clean up and remove an active update without applying + * it. The first function does this for the update that is currently being + * downloaded. The second function does this for the update that has already + * been downloaded. + */ + void cleanupDownloadingUpdate(); + void cleanupReadyUpdate(); + + /** + * Runs cleanup that ought to happen on a Firefox paveover install to + * prevent a stale update from being processed when Firefox is first + * launched. + * This is best-effort. It will not throw on cleanup failure. + * + * The returned promise does not resolve with any particular value. It simply + * conveys that the cleanup has completed. + */ + Promise doInstallCleanup(); + + /** + * Runs cleanup that ought to happen when Firefox is uninstalled to clean up + * old update data that is no longer needed. + * This is best-effort. It will not throw on cleanup failure. + * + * The returned promise does not resolve with any particular value. It simply + * conveys that the cleanup has completed. + */ + Promise doUninstallCleanup(); +}; |