Source code
Revision control
Copy as Markdown
Other Tools
/* -*- 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
#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.
*/
boolean 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;
/**
* Determines if the base directory is writable. If not, we assume that
* further permissions are required and that we are dealing with an elevated
* installation.
*/
readonly attribute boolean isAppBaseDirWritable;
/**
* 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.
*/
boolean getServiceRegKeyExists();
/**
* Attempts to restart the application manually on program exit with the same
* arguments it was started with, while accepting additional arguments.
*
* This function should only be called on Windows.
*
* @param argvExtra
* An array of strings to be passed to the application upon
* restart as additional arguments.
* @returns pidRet
* Returns the pid of a newly spawned child process. This value
* is only valid if the function returns successfully.
* @throws NS_ERROR_ABORT
* If the child process failed to spawn correctly.
* @throws NS_ERROR_NOT_IMPLEMENTED
* If this is called on a non-Windows platform.
* @throws NS_ERROR_NOT_AVAILABLE
* If the command line cannot be read.
*/
long attemptAutomaticApplicationRestartWithLaunchArgs(in Array<AString> argvExtra);
/**
* This function is meant to be used in conjunction with
* RegisterApplicationRestartWithLaunchArgs() if you want the child process
* that invokes this function to wait for the parent process
* to finish execution. When the application has the argument
* -restart-pid <pid> this function waits for the application with
* <pid> to exit.
*
* This function should only be called on Windows.
*
* @param pid
* Which process ID to wait for.
* @param timeoutMS
* How long to wait for the process to exit in milliseconds.
* @throws NS_OK
* On successful wait.
* @throws NS_ERROR_NOT_IMPLEMENTED
* If this is called on a non-Windows platform.
* @throws NS_ERROR_INVALID_ARG
* If -restart-pid has no pid parameter.
* @throws NS_ERROR_ILLEGAL_VALUE
* If pid cannot be converted into unsigned int.
* @throws NS_ERROR_FAILURE
* If timeout elapses without process exit.
*/
void waitForProcessExit(in unsigned long pid, in unsigned long timeoutMS);
};
/**
* 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
* 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
*/
boolean 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();
};