mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-10-31 22:25:30 +00:00
545 lines
18 KiB
Plaintext
545 lines
18 KiB
Plaintext
/* -*- 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 <ben@mozilla.org>
|
|
*
|
|
* 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 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(60523512-bb69-417c-9b2c-87a0664b0bbe)]
|
|
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 final URL this patch was being downloaded from
|
|
*/
|
|
attribute AString finalURL;
|
|
|
|
/**
|
|
* 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(2379e2e1-8eab-4084-8d8c-94ffeee56804)]
|
|
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 "<Application Name> <Update Version>"
|
|
*/
|
|
attribute AString name;
|
|
|
|
/**
|
|
* The string to display in the user interface for the version. If you want
|
|
* a real version number use appVersion.
|
|
*/
|
|
attribute AString displayVersion;
|
|
|
|
/**
|
|
* The Application version of this update.
|
|
*/
|
|
attribute AString appVersion;
|
|
|
|
/**
|
|
* The Toolkit version of this update.
|
|
*/
|
|
attribute AString platformVersion;
|
|
|
|
/**
|
|
* The Application version prior to the application being updated.
|
|
*/
|
|
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.
|
|
*/
|
|
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 page that is typically localized to display in the update
|
|
* prompt.
|
|
*/
|
|
attribute AString billboardURL;
|
|
|
|
/**
|
|
* 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 to show the update prompt which requires user confirmation when an
|
|
* update is found during a background update check. This overrides the
|
|
* default setting to download the update in the background.
|
|
*/
|
|
attribute boolean showPrompt;
|
|
|
|
/**
|
|
* Whether to show the "No Thanks" button in the update prompt. This allows
|
|
* the user to never receive a notification for that specific update version
|
|
* again.
|
|
*/
|
|
attribute boolean showNeverForVersion;
|
|
|
|
/**
|
|
* Whether to show the survey link in the update prompt. The url must also be
|
|
* present in the app.update.surveyURL preference.
|
|
*/
|
|
attribute boolean showSurvey;
|
|
|
|
/**
|
|
* 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 or failed certificate attribute check during an update
|
|
* check. If the update is not in the "failed" state or the certificate
|
|
* attribute check has not failed the value is zero.
|
|
*
|
|
* TODO: Define typical error codes (for now, see updater/errors.h and the
|
|
* CERT_ATTR_CHECK_FAILED_* values in nsUpdateService.js)
|
|
*/
|
|
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(b5811144-ed30-4343-aff9-c514034aa19a)]
|
|
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 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 canCheckForUpdates;
|
|
|
|
/**
|
|
* 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 canApplyUpdates;
|
|
};
|
|
|
|
/**
|
|
* 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 the application update checking user interface and checks if there
|
|
* is an update available.
|
|
*/
|
|
void checkForUpdates();
|
|
|
|
/**
|
|
* Shows the application update available user interface advising that an
|
|
* update is available for download and install. If the app.update.silent
|
|
* preference is true or the user interface is already displayed the call will
|
|
* be a no-op.
|
|
* @param update
|
|
* The nsIUpdate object to be downloaded and installed
|
|
*/
|
|
void showUpdateAvailable(in nsIUpdate update);
|
|
|
|
/**
|
|
* Shows the application update downloaded user interface advising that an
|
|
* update has now been downloaded and a restart is necessary to complete the
|
|
* update. If background is true (e.g. the download was not user initiated)
|
|
* and the app.update.silent preference is true the call will be a no-op.
|
|
* @param update
|
|
* The nsIUpdate object 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 the application update installed user interface advising that an
|
|
* update was installed successfully. If the app.update.silent preference is
|
|
* true, the app.update.showInstalledUI preference is false, or the user
|
|
* interface is already displayed the call will be a no-op.
|
|
*/
|
|
void showUpdateInstalled();
|
|
|
|
/**
|
|
* Shows the application update error user interface advising that an error
|
|
* occurred while checking for or applying an update. If the app.update.silent
|
|
* preference is true the call will be a no-op.
|
|
* @param update
|
|
* An nsIUpdate object representing the update that could not be
|
|
* installed. The nsIUpdate object will not be the actual update when
|
|
* the error occurred during an update check and will instead be an
|
|
* nsIUpdate object with the error information for the update check.
|
|
*/
|
|
void showUpdateError(in nsIUpdate update);
|
|
|
|
/**
|
|
* Shows a list of all updates installed to date.
|
|
* @param parent
|
|
* An nsIDOMWindow to set as the parent for this window. Can be null.
|
|
*/
|
|
void showUpdateHistory(in nsIDOMWindow parent);
|
|
};
|