DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (5b81998bb7ab)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551
/* -*- 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
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsIDOMDocument;
interface nsIDOMElement;
interface nsIDOMWindow;
interface nsIRequest;
interface nsIRequestObserver;
interface nsISimpleEnumerator;
interface nsIXMLHttpRequest;
interface nsIFile;

/**
 * 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(1134957d-9449-481b-a515-4d88b9998278)]
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.
   *   "applied"            The update is ready to be switched to.
   *   "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 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(900b4a18-3bef-4f3e-bcf5-84dce0021c6d)]
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);

  /**
   * Apply an update in the background.
   */
  void applyUpdateInBackground(in nsIUpdate update);

  /**
   * Get the Active Updates directory
   * @returns The active updates directory.
   */
  nsIFile getUpdatesDirectory();

  /**
   * 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;

  /**
   * Whether the Update Service is able to stage updates.
   */
  readonly attribute boolean canStageUpdates;
};

/**
 * 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
{
  /**
   * Processes the update which has been downloaded.
   * This happens without restarting the application.
   */
  void processUpdate(in nsIUpdate update);
};

/**
 * An interface describing a global application service that maintains a list
 * of updates previously performed as well as the current active update.
 */
[scriptable, uuid(c5df56de-919d-406b-aaf9-106dfa9b685b)]
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();

  /**
   * Refresh the update status based on the information in update.status.
   */
  void refreshUpdateStatus(in nsIUpdate update);
};

/**
 * 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);
};