/toolkit/mozapps/update/nsIUpdateService.idl
http://github.com/zpao/v8monkey · IDL · 545 lines · 104 code · 61 blank · 380 comment · 0 complexity · f9c62617104e2eee31f9a3a81c09b2d9 MD5 · raw file
- /* -*- 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.
- * "pending-service" The update is ready to be applied with the service.
- * "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);
- };