toolkit/mozapps/update/public/nsIUpdateService.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is the Application Update Service
  16  *
  17  * The Initial Developer of the Original Code is Google Inc.
  18  * Portions created by the Initial Developer are Copyright (C) 2005
  19  * the Initial Developer. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *  Ben Goodger <ben@mozilla.org>
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsISupports.idl"
  39
  40 interface nsIDOMDocument;
  41 interface nsIDOMElement;
  42 interface nsIDOMWindow;
  43 interface nsIRequest;
  44 interface nsIRequestObserver;
  45 interface nsISimpleEnumerator;
  46 interface nsITimerCallback;
  47 interface nsIXMLHttpRequest;
  48
  49 /**
  50  * An interface that describes an object representing a patch file that can
  51  * be downloaded and applied to a version of this application so that it
  52  * can be updated.
  53  */
  54 [scriptable, uuid(56863a67-bd69-42de-9f40-583e625b457d)]
  55 interface nsIUpdatePatch : nsISupports
  56 {
  57   /**
  58    * The type of this patch:
  59    * "partial"      A binary difference between two application versions
  60    * "complete"     A complete patch containing all of the replacement files
  61    *                to update to the new version
  62    */
  63   attribute AString type;
  64
  65   /**
  66    * The URL this patch was being downloaded from
  67    */
  68   attribute AString URL;
  69
  70   /**
  71    * The hash function to use when determining this file's integrity
  72    */
  73   attribute AString hashFunction;
  74
  75   /**
  76    * The value of the hash function named above that should be computed if
  77    * this file is not corrupt.
  78    */
  79   attribute AString hashValue;
  80
  81   /**
  82    * The size of this file, in bytes.
  83    */
  84   attribute unsigned long size;
  85
  86   /**
  87    * The state of this patch
  88    */
  89   attribute AString state;
  90
  91   /**
  92    * true if this patch is currently selected as the patch to be downloaded and
  93    * installed for this update transaction, false if another patch from this
  94    * update has been selected.
  95    */
  96   attribute boolean selected;
  97
  98   /**
  99    * Serializes this patch object into a DOM Element
 100    * @param   updates
 101    *          The document to serialize into
 102    * @returns The DOM Element created by the serialization process
 103    */
 104   nsIDOMElement serialize(in nsIDOMDocument updates);
 105 };
 106
 107 /**
 108  * An interface that describes an object representing an available update to
 109  * the current application - this update may have several available patches
 110  * from which one must be selected to download and install, for example we
 111  * might select a binary difference patch first and attempt to apply that,
 112  * then if the application process fails fall back to downloading a complete
 113  * file-replace patch. This object also contains information about the update
 114  * that the front end and other application services can use to learn more
 115  * about what is going on.
 116  */
 117 [scriptable, uuid(9d6a388b-2e0c-4d0e-9a60-5c9739a7ada5)]
 118 interface nsIUpdate : nsISupports
 119 {
 120   /**
 121    * The type of update:
 122    *   "major"  A major new version of the Application
 123    *   "minor"  A minor update to the Application (e.g. security update)
 124    */
 125   attribute AString type;
 126
 127   /**
 128    * The name of the update, or "<Application Name> <Update Version>"
 129    */
 130   attribute AString name;
 131
 132   /**
 133    * The Application version of this update.
 134    */
 135   attribute AString version;
 136
 137   /**
 138    * The Toolkit version of this update.
 139    */
 140   attribute AString platformVersion;
 141
 142   /**
 143    * The Addon version of this update. Used by the Extension System to track
 144    * compatibility of installed addons with this update.
 145    */
 146   attribute AString extensionVersion;
 147
 148   /**
 149    * The Build ID of this update. Used to determine a particular build, down
 150    * to the hour, minute and second of its creation. This allows the system
 151    * to differentiate between several nightly builds with the same |version|
 152    * for example.
 153    */
 154   attribute AString buildID;
 155
 156   /**
 157    * The URL to a page which offers details about the content of this
 158    * update. Ideally, this page is not the release notes but some other page
 159    * that summarizes the differences between this update and the previous,
 160    * which also links to the release notes.
 161    */
 162   attribute AString detailsURL;
 163
 164   /**
 165    * The URL to a HTML fragment that contains a license for this update. If
 166    * this is specified, the user is shown the license file after they choose
 167    * to install the update and they must agree to it before the download
 168    * commences.
 169    */
 170   attribute AString licenseURL;
 171
 172   /**
 173    * The URL to the Update Service that supplied this update.
 174    */
 175   attribute AString serviceURL;
 176
 177   /**
 178    * The channel used to retrieve this update from the Update Service.
 179    */
 180   attribute AString channel;
 181
 182   /**
 183    * Whether or not the update being downloaded is a complete replacement of
 184    * the user's existing installation or a patch representing the difference
 185    * between the new version and the previous version.
 186    */
 187   attribute boolean isCompleteUpdate;
 188
 189   /**
 190    * Whether or not the update is a security update or not. If this is true,
 191    * then we present more serious sounding user interface messages to the
 192    * user.
 193    */
 194   attribute boolean isSecurityUpdate;
 195
 196   /**
 197    * When the update was installed.
 198    */
 199   attribute long long installDate;
 200
 201   /**
 202    * A message associated with this update, if any.
 203    */
 204   attribute AString statusText;
 205
 206   /**
 207    * The currently selected patch for this update.
 208    */
 209   readonly attribute nsIUpdatePatch selectedPatch;
 210
 211   /**
 212    * The state of the selected patch:
 213    *   "downloading"       The update is being downloaded.
 214    *   "pending"           The update is ready to be applied.
 215    *   "applying"          The update is being applied.
 216    *   "succeeded"         The update was successfully applied.
 217    *   "download-failed"   The update failed to be downloaded.
 218    *   "failed"            The update failed to be applied.
 219    */
 220   attribute AString state;
 221
 222   /**
 223    * A numeric error code that conveys additional information about the state
 224    * of a failed update.  If the update is not in the "failed" state, then this
 225    * value is zero.
 226    *
 227    * TODO: Define typical error codes (for now, see updater/errors.h)
 228    */
 229   attribute long errorCode;
 230
 231   /**
 232    * The number of patches supplied by this update.
 233    */
 234   readonly attribute unsigned long patchCount;
 235
 236   /**
 237    * Retrieves a patch.
 238    * @param   index
 239    *          The index of the patch to retrieve.
 240    * @returns The nsIUpdatePatch at the specified index.
 241    */
 242   nsIUpdatePatch getPatchAt(in unsigned long index);
 243
 244   /**
 245    * Serializes this update object into a DOM Element
 246    * @param   updates
 247    *          The document to serialize into
 248    * @returns The DOM Element created by the serialization process
 249    */
 250   nsIDOMElement serialize(in nsIDOMDocument updates);
 251 };
 252
 253 /**
 254  * An interface describing an object that listens to the progress of an update
 255  * check operation. This object is notified as the check continues, finishes
 256  * and if it has an error.
 257  */
 258 [scriptable, uuid(8cbceb6e-8e27-46f2-8808-444c6499f836)]
 259 interface nsIUpdateCheckListener : nsISupports
 260 {
 261   /**
 262    * Called every time there is a progress notification loading the Update
 263    * Service file.
 264    * @param   request
 265    *          The nsIXMLHttpRequest handling the update check.
 266    * @param   position
 267    *          The current byte downloaded
 268    * @param   totalSize
 269    *          The total number of bytes that have to be downloaded
 270    */
 271   void onProgress(in nsIXMLHttpRequest request,
 272                   in unsigned long position,
 273                   in unsigned long totalSize);
 274
 275   /**
 276    * The update check was completed.
 277    * @param   request
 278    *          The nsIXMLHttpRequest handling the update check.
 279    * @param   updates
 280    *          An array of nsIUpdate objects listing available updates.
 281    * @param   updateCount
 282    *          The size of the |updates| array.
 283    */
 284   void onCheckComplete(in nsIXMLHttpRequest request,
 285                        [array, size_is(updateCount)] in nsIUpdate updates,
 286                        in unsigned long updateCount);
 287
 288   /**
 289    * An error occurred while loading the remote update service file.
 290    * @param   request
 291    *          The nsIXMLHttpRequest handling the update check.
 292    * @param   update
 293    *          A nsIUpdate object that contains details about the
 294    *          error in its |statusText| property.
 295    */
 296   void onError(in nsIXMLHttpRequest request,
 297                in nsIUpdate update);
 298 };
 299
 300 /**
 301  * An interface describing an object that knows how to check for updates.
 302  */
 303 [scriptable, uuid(877ace25-8bc5-452a-8586-9c1cf2871994)]
 304 interface nsIUpdateChecker : nsISupports
 305 {
 306   /**
 307    * Checks for available updates, notifying a listener of the results.
 308    * @param   listener
 309    *          An object implementing nsIUpdateCheckListener which is notified
 310    *          of the results of an update check.
 311    * @param   force
 312    *          Forces the checker to check for updates, regardless of the
 313    *          current value of the user's update settings. This is used by
 314    *          any piece of UI that offers the user the imperative option to
 315    *          check for updates now, regardless of their update settings.
 316    *          force will not work if the system administrator has locked
 317    *          the app.update.enabled preference.
 318    */
 319   void checkForUpdates(in nsIUpdateCheckListener listener, in boolean force);
 320
 321   /**
 322    * Constants for the |stopChecking| function that tell the Checker how long
 323    * to stop checking:
 324    *
 325    * CURRENT_CHECK:     Stops the current (active) check only
 326    * CURRENT_SESSION:   Stops all checking for the current session
 327    * ANY_CHECKS:        Stops all checking, any session from now on
 328    *                    (disables update checking preferences)
 329    */
 330   const unsigned short CURRENT_CHECK    = 1;
 331   const unsigned short CURRENT_SESSION  = 2;
 332   const unsigned short ANY_CHECKS       = 3;
 333
 334   /**
 335    * Ends any pending update check.
 336    * @param   duration
 337    *          A value representing the set of checks to stop doing.
 338    */
 339   void stopChecking(in unsigned short duration);
 340 };
 341
 342 /**
 343  * An interface describing a global application service that handles performing
 344  * background update checks and provides utilities for selecting and
 345  * downloading update patches.
 346  */
 347 [scriptable, uuid(9849c4bf-5197-4d22-baa8-e3b44a1703d2)]
 348 interface nsIApplicationUpdateService : nsISupports
 349 {
 350   /**
 351    * The Update Checker used for background update checking.
 352    */
 353   readonly attribute nsIUpdateChecker backgroundChecker;
 354
 355   /**
 356    * Selects the best update to install from a list of available updates.
 357    * @param   updates
 358    *          An array of updates that are available
 359    * @param   updateCount
 360    *          The length of the |updates| array
 361    */
 362   nsIUpdate selectUpdate([array, size_is(updateCount)] in nsIUpdate updates,
 363                          in unsigned long updateCount);
 364
 365   /**
 366    * Adds a listener that receives progress and state information about the
 367    * update that is currently being downloaded, e.g. to update a user
 368    * interface.
 369    * @param   listener
 370    *          An object implementing nsIRequestObserver and optionally
 371    *          nsIProgressEventSink that is to be notified of state and
 372    *          progress information as the update is downloaded.
 373    */
 374   void addDownloadListener(in nsIRequestObserver listener);
 375
 376   /**
 377    * Removes a listener that is receiving progress and state information
 378    * about the update that is currently being downloaded.
 379    * @param   listener
 380    *          The listener object to remove.
 381    */
 382   void removeDownloadListener(in nsIRequestObserver listener);
 383
 384   /**
 385    *
 386    */
 387   AString downloadUpdate(in nsIUpdate update, in boolean background);
 388
 389   /**
 390    * Pauses the active update download process
 391    */
 392   void pauseDownload();
 393
 394   /**
 395    * Whether or not there is an download happening at the moment.
 396    */
 397   readonly attribute boolean isDownloading;
 398
 399   /**
 400    * Whether or not the Update Service can download and install updates.
 401    * This is a function of whether or not the current user has access
 402    * privileges to the install directory.
 403    */
 404   readonly attribute boolean canUpdate;
 405 };
 406
 407 /**
 408  * An interface describing a global application service that maintains a list
 409  * of updates previously performed as well as the current active update.
 410  */
 411 [scriptable, uuid(fede66a9-9f96-4507-a22a-775ee885577e)]
 412 interface nsIUpdateManager : nsISupports
 413 {
 414   /**
 415    * Gets the update at the specified index
 416    * @param   index
 417    *          The index within the updates array
 418    * @returns The nsIUpdate object at the specified index
 419    */
 420   nsIUpdate getUpdateAt(in long index);
 421
 422   /**
 423    * Gets the total number of updates in the history list.
 424    */
 425   readonly attribute long updateCount;
 426
 427   /**
 428    * The active (current) update. The active update is not in the history list.
 429    */
 430   attribute nsIUpdate activeUpdate;
 431
 432   /**
 433    * Saves all updates to disk.
 434    */
 435   void saveUpdates();
 436 };
 437
 438 /**
 439  * An interface describing an object that can show various kinds of Update
 440  * notification UI to the user.
 441  */
 442 [scriptable, uuid(599fd3c6-ec68-4499-ada5-2997739c97a6)]
 443 interface nsIUpdatePrompt : nsISupports
 444 {
 445   /**
 446    * Shows a user interface that checks for and then displays the available
 447    * updates.
 448    */
 449   void checkForUpdates();
 450
 451   /**
 452    * Show a message advising that an update is available for download and
 453    * install.
 454    * @param   update
 455    *          The update to be downloaded and installed
 456    */
 457   void showUpdateAvailable(in nsIUpdate update);
 458
 459   /**
 460    * Show a message advising that an update has now been downloaded and that
 461    * a restart is necessary to complete the update.
 462    * @param   update
 463    *          The update that was downloaded
 464    * @param   background
 465    *          Less obtrusive UI, starting with a non-modal notification alert
 466    */
 467   void showUpdateDownloaded(in nsIUpdate update,
 468                             [optional] in boolean background);
 469
 470   /**
 471    * Shows a message that an update was installed successfully.
 472    */
 473   void showUpdateInstalled();
 474
 475   /**
 476    * Shows an error message UI telling the user about some kind of update
 477    * failure, e.g. failure to apply patch.
 478    * @param   update
 479    *          The nsIUpdate object which we could not install
 480    */
 481   void showUpdateError(in nsIUpdate update);
 482
 483   /**
 484    * Shows a list of all updates installed to date.
 485    * @param   parent
 486    *          A parent window to anchor this window to. Can be null.
 487    */
 488   void showUpdateHistory(in nsIDOMWindow parent);
 489 };
 490
 491 /**
 492  * An interface describing a global application service that allows long
 493  * duration (e.g. 1-7 or more days, weeks or months) timers to be registered
 494  * and then fired.
 495  */
 496 [scriptable, uuid(0765c92c-6145-4253-9db4-594d8023087e)]
 497 interface nsIUpdateTimerManager : nsISupports
 498 {
 499   /**
 500    * Register an interval with the timer manager. The timer manager
 501    * periodically checks to see if the interval has expired and if it has
 502    * calls the specified callback. This is persistent across application
 503    * restarts and can handle intervals of long durations.
 504    * @param   id
 505    *          An id that identifies the interval, used for persistence
 506    * @param   callback
 507    *          A nsITimerCallback object that is notified when the interval
 508    *          expires
 509    * @param   interval
 510    *          The length of time, in seconds, of the interval
 511    */
 512   void registerTimer(in AString id,
 513                      in nsITimerCallback callback,
 514                      in unsigned long interval);
 515 };