1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/mozapps/update/nsIUpdateService.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,574 @@
1.4 +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIDOMDocument;
1.12 +interface nsIDOMElement;
1.13 +interface nsIDOMWindow;
1.14 +interface nsIRequest;
1.15 +interface nsIRequestObserver;
1.16 +interface nsISimpleEnumerator;
1.17 +interface nsIXMLHttpRequest;
1.18 +interface nsIFile;
1.19 +
1.20 +/**
1.21 + * An interface that describes an object representing a patch file that can
1.22 + * be downloaded and applied to a version of this application so that it
1.23 + * can be updated.
1.24 + */
1.25 +[scriptable, uuid(dc8fb8a9-3a53-4031-9469-2a5197ea30e7)]
1.26 +interface nsIUpdatePatch : nsISupports
1.27 +{
1.28 + /**
1.29 + * The type of this patch:
1.30 + * "partial" A binary difference between two application versions
1.31 + * "complete" A complete patch containing all of the replacement files
1.32 + * to update to the new version
1.33 + */
1.34 + attribute AString type;
1.35 +
1.36 + /**
1.37 + * The URL this patch was being downloaded from
1.38 + */
1.39 + attribute AString URL;
1.40 +
1.41 + /**
1.42 + * The final URL this patch was being downloaded from
1.43 + */
1.44 + attribute AString finalURL;
1.45 +
1.46 + /**
1.47 + * The hash function to use when determining this file's integrity
1.48 + */
1.49 + attribute AString hashFunction;
1.50 +
1.51 + /**
1.52 + * The value of the hash function named above that should be computed if
1.53 + * this file is not corrupt.
1.54 + */
1.55 + attribute AString hashValue;
1.56 +
1.57 + /**
1.58 + * The size of this file, in bytes.
1.59 + */
1.60 + attribute unsigned long size;
1.61 +
1.62 + /**
1.63 + * The state of this patch
1.64 + */
1.65 + attribute AString state;
1.66 +
1.67 + /**
1.68 + * true if this patch is currently selected as the patch to be downloaded and
1.69 + * installed for this update transaction, false if another patch from this
1.70 + * update has been selected.
1.71 + */
1.72 + attribute boolean selected;
1.73 +
1.74 + /**
1.75 + * Serializes this patch object into a DOM Element
1.76 + * @param updates
1.77 + * The document to serialize into
1.78 + * @returns The DOM Element created by the serialization process
1.79 + */
1.80 + nsIDOMElement serialize(in nsIDOMDocument updates);
1.81 +};
1.82 +
1.83 +/**
1.84 + * An interface that describes an object representing an available update to
1.85 + * the current application - this update may have several available patches
1.86 + * from which one must be selected to download and install, for example we
1.87 + * might select a binary difference patch first and attempt to apply that,
1.88 + * then if the application process fails fall back to downloading a complete
1.89 + * file-replace patch. This object also contains information about the update
1.90 + * that the front end and other application services can use to learn more
1.91 + * about what is going on.
1.92 + */
1.93 +[scriptable, uuid(6b0b7721-6746-443d-8cb0-c6199d7f28a6)]
1.94 +interface nsIUpdate : nsISupports
1.95 +{
1.96 + /**
1.97 + * The type of update:
1.98 + * "major" A major new version of the Application
1.99 + * "minor" A minor update to the Application (e.g. security update)
1.100 + */
1.101 + attribute AString type;
1.102 +
1.103 + /**
1.104 + * The name of the update, or "<Application Name> <Update Version>"
1.105 + */
1.106 + attribute AString name;
1.107 +
1.108 + /**
1.109 + * The string to display in the user interface for the version. If you want
1.110 + * a real version number use appVersion.
1.111 + */
1.112 + attribute AString displayVersion;
1.113 +
1.114 + /**
1.115 + * The Application version of this update.
1.116 + */
1.117 + attribute AString appVersion;
1.118 +
1.119 + /**
1.120 + * The Toolkit version of this update.
1.121 + */
1.122 + attribute AString platformVersion;
1.123 +
1.124 + /**
1.125 + * The Application version prior to the application being updated.
1.126 + */
1.127 + attribute AString previousAppVersion;
1.128 +
1.129 + /**
1.130 + * The Build ID of this update. Used to determine a particular build, down
1.131 + * to the hour, minute and second of its creation. This allows the system
1.132 + * to differentiate between several nightly builds with the same |version|
1.133 + * for example.
1.134 + */
1.135 + attribute AString buildID;
1.136 +
1.137 + /**
1.138 + * The URL to a page which offers details about the content of this
1.139 + * update. Ideally, this page is not the release notes but some other page
1.140 + * that summarizes the differences between this update and the previous,
1.141 + * which also links to the release notes.
1.142 + */
1.143 + attribute AString detailsURL;
1.144 +
1.145 + /**
1.146 + * The URL to a page that is typically localized to display in the update
1.147 + * prompt.
1.148 + */
1.149 + attribute AString billboardURL;
1.150 +
1.151 + /**
1.152 + * The URL to a HTML fragment that contains a license for this update. If
1.153 + * this is specified, the user is shown the license file after they choose
1.154 + * to install the update and they must agree to it before the download
1.155 + * commences.
1.156 + */
1.157 + attribute AString licenseURL;
1.158 +
1.159 + /**
1.160 + * The URL to the Update Service that supplied this update.
1.161 + */
1.162 + attribute AString serviceURL;
1.163 +
1.164 + /**
1.165 + * The channel used to retrieve this update from the Update Service.
1.166 + */
1.167 + attribute AString channel;
1.168 +
1.169 + /**
1.170 + * Whether to show the update prompt which requires user confirmation when an
1.171 + * update is found during a background update check. This overrides the
1.172 + * default setting to download the update in the background.
1.173 + */
1.174 + attribute boolean showPrompt;
1.175 +
1.176 + /**
1.177 + * Whether to show the "No Thanks" button in the update prompt. This allows
1.178 + * the user to never receive a notification for that specific update version
1.179 + * again.
1.180 + */
1.181 + attribute boolean showNeverForVersion;
1.182 +
1.183 + /**
1.184 + * Whether the update is no longer supported on this system.
1.185 + */
1.186 + attribute boolean unsupported;
1.187 +
1.188 + /**
1.189 + * Allows overriding the default amount of time in seconds before prompting the
1.190 + * user to apply an update. If not specified, the value of
1.191 + * app.update.promptWaitTime will be used.
1.192 + */
1.193 + attribute long long promptWaitTime;
1.194 +
1.195 + /**
1.196 + * Whether or not the update being downloaded is a complete replacement of
1.197 + * the user's existing installation or a patch representing the difference
1.198 + * between the new version and the previous version.
1.199 + */
1.200 + attribute boolean isCompleteUpdate;
1.201 +
1.202 + /**
1.203 + * Whether or not the update is a security update or not. If this is true,
1.204 + * then we present more serious sounding user interface messages to the
1.205 + * user.
1.206 + */
1.207 + attribute boolean isSecurityUpdate;
1.208 +
1.209 + /**
1.210 + * Whether or not the update being downloaded is an OS update. This is
1.211 + * generally only possible in Gonk right now.
1.212 + */
1.213 + attribute boolean isOSUpdate;
1.214 +
1.215 + /**
1.216 + * When the update was installed.
1.217 + */
1.218 + attribute long long installDate;
1.219 +
1.220 + /**
1.221 + * A message associated with this update, if any.
1.222 + */
1.223 + attribute AString statusText;
1.224 +
1.225 + /**
1.226 + * The currently selected patch for this update.
1.227 + */
1.228 + readonly attribute nsIUpdatePatch selectedPatch;
1.229 +
1.230 + /**
1.231 + * The state of the selected patch:
1.232 + * "downloading" The update is being downloaded.
1.233 + * "pending" The update is ready to be applied.
1.234 + * "pending-service" The update is ready to be applied with the service.
1.235 + * "applying" The update is being applied.
1.236 + * "applied" The update is ready to be switched to.
1.237 + * "applied-os" The update is OS update and to be installed.
1.238 + * "applied-service" The update is ready to be switched to with the service.
1.239 + * "succeeded" The update was successfully applied.
1.240 + * "download-failed" The update failed to be downloaded.
1.241 + * "failed" The update failed to be applied.
1.242 + */
1.243 + attribute AString state;
1.244 +
1.245 + /**
1.246 + * A numeric error code that conveys additional information about the state
1.247 + * of a failed update or failed certificate attribute check during an update
1.248 + * check. If the update is not in the "failed" state or the certificate
1.249 + * attribute check has not failed the value is zero.
1.250 + *
1.251 + * TODO: Define typical error codes (for now, see updater/errors.h and the
1.252 + * CERT_ATTR_CHECK_FAILED_* values in nsUpdateService.js)
1.253 + */
1.254 + attribute long errorCode;
1.255 +
1.256 + /**
1.257 + * The number of patches supplied by this update.
1.258 + */
1.259 + readonly attribute unsigned long patchCount;
1.260 +
1.261 + /**
1.262 + * Retrieves a patch.
1.263 + * @param index
1.264 + * The index of the patch to retrieve.
1.265 + * @returns The nsIUpdatePatch at the specified index.
1.266 + */
1.267 + nsIUpdatePatch getPatchAt(in unsigned long index);
1.268 +
1.269 + /**
1.270 + * Serializes this update object into a DOM Element
1.271 + * @param updates
1.272 + * The document to serialize into
1.273 + * @returns The DOM Element created by the serialization process
1.274 + */
1.275 + nsIDOMElement serialize(in nsIDOMDocument updates);
1.276 +};
1.277 +
1.278 +/**
1.279 + * An interface describing an object that listens to the progress of an update
1.280 + * check operation. This object is notified as the check continues, finishes
1.281 + * and if it has an error.
1.282 + */
1.283 +[scriptable, uuid(4aa2b4bb-39ea-407b-98ff-89f19134d4c0)]
1.284 +interface nsIUpdateCheckListener : nsISupports
1.285 +{
1.286 + /**
1.287 + * The update check was completed.
1.288 + * @param request
1.289 + * The nsIXMLHttpRequest handling the update check.
1.290 + * @param updates
1.291 + * An array of nsIUpdate objects listing available updates.
1.292 + * @param updateCount
1.293 + * The size of the |updates| array.
1.294 + */
1.295 + void onCheckComplete(in nsIXMLHttpRequest request,
1.296 + [array, size_is(updateCount)] in nsIUpdate updates,
1.297 + in unsigned long updateCount);
1.298 +
1.299 + /**
1.300 + * An error occurred while loading the remote update service file.
1.301 + * @param request
1.302 + * The nsIXMLHttpRequest handling the update check.
1.303 + * @param update
1.304 + * A nsIUpdate object that contains details about the
1.305 + * error in its |statusText| property.
1.306 + */
1.307 + void onError(in nsIXMLHttpRequest request,
1.308 + in nsIUpdate update);
1.309 +};
1.310 +
1.311 +/**
1.312 + * An interface describing an object that knows how to check for updates.
1.313 + */
1.314 +[scriptable, uuid(877ace25-8bc5-452a-8586-9c1cf2871994)]
1.315 +interface nsIUpdateChecker : nsISupports
1.316 +{
1.317 + /**
1.318 + * Checks for available updates, notifying a listener of the results.
1.319 + * @param listener
1.320 + * An object implementing nsIUpdateCheckListener which is notified
1.321 + * of the results of an update check.
1.322 + * @param force
1.323 + * Forces the checker to check for updates, regardless of the
1.324 + * current value of the user's update settings. This is used by
1.325 + * any piece of UI that offers the user the imperative option to
1.326 + * check for updates now, regardless of their update settings.
1.327 + * force will not work if the system administrator has locked
1.328 + * the app.update.enabled preference.
1.329 + */
1.330 + void checkForUpdates(in nsIUpdateCheckListener listener, in boolean force);
1.331 +
1.332 + /**
1.333 + * Constants for the |stopChecking| function that tell the Checker how long
1.334 + * to stop checking:
1.335 + *
1.336 + * CURRENT_CHECK: Stops the current (active) check only
1.337 + * CURRENT_SESSION: Stops all checking for the current session
1.338 + * ANY_CHECKS: Stops all checking, any session from now on
1.339 + * (disables update checking preferences)
1.340 + */
1.341 + const unsigned short CURRENT_CHECK = 1;
1.342 + const unsigned short CURRENT_SESSION = 2;
1.343 + const unsigned short ANY_CHECKS = 3;
1.344 +
1.345 + /**
1.346 + * Ends any pending update check.
1.347 + * @param duration
1.348 + * A value representing the set of checks to stop doing.
1.349 + */
1.350 + void stopChecking(in unsigned short duration);
1.351 +};
1.352 +
1.353 +/**
1.354 + * An interface describing a global application service that handles performing
1.355 + * background update checks and provides utilities for selecting and
1.356 + * downloading update patches.
1.357 + */
1.358 +[scriptable, uuid(9f9b51f5-340e-47ce-85ae-9eb077c6cd39)]
1.359 +interface nsIApplicationUpdateService : nsISupports
1.360 +{
1.361 + /**
1.362 + * Checks for available updates in the background using the listener provided
1.363 + * by the application update service for background checks.
1.364 + */
1.365 + void checkForBackgroundUpdates();
1.366 +
1.367 + /**
1.368 + * The Update Checker used for background update checking.
1.369 + */
1.370 + readonly attribute nsIUpdateChecker backgroundChecker;
1.371 +
1.372 + /**
1.373 + * Selects the best update to install from a list of available updates.
1.374 + * @param updates
1.375 + * An array of updates that are available
1.376 + * @param updateCount
1.377 + * The length of the |updates| array
1.378 + */
1.379 + nsIUpdate selectUpdate([array, size_is(updateCount)] in nsIUpdate updates,
1.380 + in unsigned long updateCount);
1.381 +
1.382 + /**
1.383 + * Adds a listener that receives progress and state information about the
1.384 + * update that is currently being downloaded, e.g. to update a user
1.385 + * interface.
1.386 + * @param listener
1.387 + * An object implementing nsIRequestObserver and optionally
1.388 + * nsIProgressEventSink that is to be notified of state and
1.389 + * progress information as the update is downloaded.
1.390 + */
1.391 + void addDownloadListener(in nsIRequestObserver listener);
1.392 +
1.393 + /**
1.394 + * Removes a listener that is receiving progress and state information
1.395 + * about the update that is currently being downloaded.
1.396 + * @param listener
1.397 + * The listener object to remove.
1.398 + */
1.399 + void removeDownloadListener(in nsIRequestObserver listener);
1.400 +
1.401 + /**
1.402 + *
1.403 + */
1.404 + AString downloadUpdate(in nsIUpdate update, in boolean background);
1.405 +
1.406 + /**
1.407 + * Apply the OS update which has been downloaded and staged as applied.
1.408 + * @param update
1.409 + * The update has been downloaded and staged as applied.
1.410 + * @throws if the update object is not an OS update.
1.411 + */
1.412 + void applyOsUpdate(in nsIUpdate update);
1.413 +
1.414 + /**
1.415 + * Get the Active Updates directory
1.416 + * @returns An nsIFile for the active updates directory.
1.417 + */
1.418 + nsIFile getUpdatesDirectory();
1.419 +
1.420 + /**
1.421 + * Pauses the active update download process
1.422 + */
1.423 + void pauseDownload();
1.424 +
1.425 + /**
1.426 + * Whether or not there is an download happening at the moment.
1.427 + */
1.428 + readonly attribute boolean isDownloading;
1.429 +
1.430 + /**
1.431 + * Whether or not the Update Service can check for updates. This is a function
1.432 + * of whether or not application update is disabled by the application and the
1.433 + * platform the application is running on.
1.434 + */
1.435 + readonly attribute boolean canCheckForUpdates;
1.436 +
1.437 + /**
1.438 + * Whether or not the Update Service can download and install updates.
1.439 + * On Windows, this is a function of whether or not the maintenance service
1.440 + * is installed and enabled. On other systems, and as a fallback on Windows,
1.441 + * this depends on whether the current user has write access to the install
1.442 + * directory.
1.443 + */
1.444 + readonly attribute boolean canApplyUpdates;
1.445 +
1.446 + /**
1.447 + * Whether or not a different instance is handling updates of this
1.448 + * installation. This currently only ever returns true on Windows
1.449 + * when 2 instances of an application are open or when both the Metro
1.450 + * and Desktop browsers are open. Only one of the instances will actually
1.451 + * handle updates for the installation.
1.452 + */
1.453 + readonly attribute boolean isOtherInstanceHandlingUpdates;
1.454 +
1.455 + /**
1.456 + * Whether the Update Service is able to stage updates.
1.457 + */
1.458 + readonly attribute boolean canStageUpdates;
1.459 +};
1.460 +
1.461 +/**
1.462 + * An interface describing a component which handles the job of processing
1.463 + * an update after it's been downloaded.
1.464 + */
1.465 +[scriptable, uuid(74439497-d796-4915-8cef-3dfe43027e4d)]
1.466 +interface nsIUpdateProcessor : nsISupports
1.467 +{
1.468 + /**
1.469 + * Processes the update which has been downloaded.
1.470 + * This happens without restarting the application.
1.471 + * On Windows, this can also be used for switching to an applied
1.472 + * update request.
1.473 + * @param update The update being applied, or null if this is a switch
1.474 + * to updated application request. Must be non-null on GONK.
1.475 + */
1.476 + void processUpdate(in nsIUpdate update);
1.477 +};
1.478 +
1.479 +/**
1.480 + * An interface describing a global application service that maintains a list
1.481 + * of updates previously performed as well as the current active update.
1.482 + */
1.483 +[scriptable, uuid(c5df56de-919d-406b-aaf9-106dfa9b685b)]
1.484 +interface nsIUpdateManager : nsISupports
1.485 +{
1.486 + /**
1.487 + * Gets the update at the specified index
1.488 + * @param index
1.489 + * The index within the updates array
1.490 + * @returns The nsIUpdate object at the specified index
1.491 + */
1.492 + nsIUpdate getUpdateAt(in long index);
1.493 +
1.494 + /**
1.495 + * Gets the total number of updates in the history list.
1.496 + */
1.497 + readonly attribute long updateCount;
1.498 +
1.499 + /**
1.500 + * The active (current) update. The active update is not in the history list.
1.501 + */
1.502 + attribute nsIUpdate activeUpdate;
1.503 +
1.504 + /**
1.505 + * Saves all updates to disk.
1.506 + */
1.507 + void saveUpdates();
1.508 +
1.509 + /**
1.510 + * Refresh the update status based on the information in update.status.
1.511 + */
1.512 + void refreshUpdateStatus(in nsIUpdate update);
1.513 +};
1.514 +
1.515 +/**
1.516 + * An interface describing an object that can show various kinds of Update
1.517 + * notification UI to the user.
1.518 + */
1.519 +[scriptable, uuid(599fd3c6-ec68-4499-ada5-2997739c97a6)]
1.520 +interface nsIUpdatePrompt : nsISupports
1.521 +{
1.522 + /**
1.523 + * Shows the application update checking user interface and checks if there
1.524 + * is an update available.
1.525 + */
1.526 + void checkForUpdates();
1.527 +
1.528 + /**
1.529 + * Shows the application update available user interface advising that an
1.530 + * update is available for download and install. If the app.update.silent
1.531 + * preference is true or the user interface is already displayed the call will
1.532 + * be a no-op.
1.533 + * @param update
1.534 + * The nsIUpdate object to be downloaded and installed
1.535 + */
1.536 + void showUpdateAvailable(in nsIUpdate update);
1.537 +
1.538 + /**
1.539 + * Shows the application update downloaded user interface advising that an
1.540 + * update has now been downloaded and a restart is necessary to complete the
1.541 + * update. If background is true (e.g. the download was not user initiated)
1.542 + * and the app.update.silent preference is true the call will be a no-op.
1.543 + * @param update
1.544 + * The nsIUpdate object that was downloaded
1.545 + * @param background
1.546 + * Less obtrusive UI, starting with a non-modal notification alert
1.547 + */
1.548 + void showUpdateDownloaded(in nsIUpdate update,
1.549 + [optional] in boolean background);
1.550 +
1.551 + /**
1.552 + * Shows the application update installed user interface advising that an
1.553 + * update was installed successfully. If the app.update.silent preference is
1.554 + * true, the app.update.showInstalledUI preference is false, or the user
1.555 + * interface is already displayed the call will be a no-op.
1.556 + */
1.557 + void showUpdateInstalled();
1.558 +
1.559 + /**
1.560 + * Shows the application update error user interface advising that an error
1.561 + * occurred while checking for or applying an update. If the app.update.silent
1.562 + * preference is true the call will be a no-op.
1.563 + * @param update
1.564 + * An nsIUpdate object representing the update that could not be
1.565 + * installed. The nsIUpdate object will not be the actual update when
1.566 + * the error occurred during an update check and will instead be an
1.567 + * nsIUpdate object with the error information for the update check.
1.568 + */
1.569 + void showUpdateError(in nsIUpdate update);
1.570 +
1.571 + /**
1.572 + * Shows a list of all updates installed to date.
1.573 + * @param parent
1.574 + * An nsIDOMWindow to set as the parent for this window. Can be null.
1.575 + */
1.576 + void showUpdateHistory(in nsIDOMWindow parent);
1.577 +};
