/toolkit/mozapps/update/nsIUpdateService.idl
IDL | 545 lines | 104 code | 61 blank | 380 comment | 0 complexity | f9c62617104e2eee31f9a3a81c09b2d9 MD5 | raw file
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 40interface nsIDOMDocument; 41interface nsIDOMElement; 42interface nsIDOMWindow; 43interface nsIRequest; 44interface nsIRequestObserver; 45interface nsISimpleEnumerator; 46interface nsIXMLHttpRequest; 47 48/** 49 * An interface that describes an object representing a patch file that can 50 * be downloaded and applied to a version of this application so that it 51 * can be updated. 52 */ 53[scriptable, uuid(60523512-bb69-417c-9b2c-87a0664b0bbe)] 54interface nsIUpdatePatch : nsISupports 55{ 56 /** 57 * The type of this patch: 58 * "partial" A binary difference between two application versions 59 * "complete" A complete patch containing all of the replacement files 60 * to update to the new version 61 */ 62 attribute AString type; 63 64 /** 65 * The URL this patch was being downloaded from 66 */ 67 attribute AString URL; 68 69 /** 70 * The final URL this patch was being downloaded from 71 */ 72 attribute AString finalURL; 73 74 /** 75 * The hash function to use when determining this file's integrity 76 */ 77 attribute AString hashFunction; 78 79 /** 80 * The value of the hash function named above that should be computed if 81 * this file is not corrupt. 82 */ 83 attribute AString hashValue; 84 85 /** 86 * The size of this file, in bytes. 87 */ 88 attribute unsigned long size; 89 90 /** 91 * The state of this patch 92 */ 93 attribute AString state; 94 95 /** 96 * true if this patch is currently selected as the patch to be downloaded and 97 * installed for this update transaction, false if another patch from this 98 * update has been selected. 99 */ 100 attribute boolean selected; 101 102 /** 103 * Serializes this patch object into a DOM Element 104 * @param updates 105 * The document to serialize into 106 * @returns The DOM Element created by the serialization process 107 */ 108 nsIDOMElement serialize(in nsIDOMDocument updates); 109}; 110 111/** 112 * An interface that describes an object representing an available update to 113 * the current application - this update may have several available patches 114 * from which one must be selected to download and install, for example we 115 * might select a binary difference patch first and attempt to apply that, 116 * then if the application process fails fall back to downloading a complete 117 * file-replace patch. This object also contains information about the update 118 * that the front end and other application services can use to learn more 119 * about what is going on. 120 */ 121[scriptable, uuid(2379e2e1-8eab-4084-8d8c-94ffeee56804)] 122interface nsIUpdate : nsISupports 123{ 124 /** 125 * The type of update: 126 * "major" A major new version of the Application 127 * "minor" A minor update to the Application (e.g. security update) 128 */ 129 attribute AString type; 130 131 /** 132 * The name of the update, or "<Application Name> <Update Version>" 133 */ 134 attribute AString name; 135 136 /** 137 * The string to display in the user interface for the version. If you want 138 * a real version number use appVersion. 139 */ 140 attribute AString displayVersion; 141 142 /** 143 * The Application version of this update. 144 */ 145 attribute AString appVersion; 146 147 /** 148 * The Toolkit version of this update. 149 */ 150 attribute AString platformVersion; 151 152 /** 153 * The Application version prior to the application being updated. 154 */ 155 attribute AString previousAppVersion; 156 157 /** 158 * The Build ID of this update. Used to determine a particular build, down 159 * to the hour, minute and second of its creation. This allows the system 160 * to differentiate between several nightly builds with the same |version| 161 * for example. 162 */ 163 attribute AString buildID; 164 165 /** 166 * The URL to a page which offers details about the content of this 167 * update. Ideally, this page is not the release notes but some other page 168 * that summarizes the differences between this update and the previous, 169 * which also links to the release notes. 170 */ 171 attribute AString detailsURL; 172 173 /** 174 * The URL to a page that is typically localized to display in the update 175 * prompt. 176 */ 177 attribute AString billboardURL; 178 179 /** 180 * The URL to a HTML fragment that contains a license for this update. If 181 * this is specified, the user is shown the license file after they choose 182 * to install the update and they must agree to it before the download 183 * commences. 184 */ 185 attribute AString licenseURL; 186 187 /** 188 * The URL to the Update Service that supplied this update. 189 */ 190 attribute AString serviceURL; 191 192 /** 193 * The channel used to retrieve this update from the Update Service. 194 */ 195 attribute AString channel; 196 197 /** 198 * Whether to show the update prompt which requires user confirmation when an 199 * update is found during a background update check. This overrides the 200 * default setting to download the update in the background. 201 */ 202 attribute boolean showPrompt; 203 204 /** 205 * Whether to show the "No Thanks" button in the update prompt. This allows 206 * the user to never receive a notification for that specific update version 207 * again. 208 */ 209 attribute boolean showNeverForVersion; 210 211 /** 212 * Whether to show the survey link in the update prompt. The url must also be 213 * present in the app.update.surveyURL preference. 214 */ 215 attribute boolean showSurvey; 216 217 /** 218 * Whether or not the update being downloaded is a complete replacement of 219 * the user's existing installation or a patch representing the difference 220 * between the new version and the previous version. 221 */ 222 attribute boolean isCompleteUpdate; 223 224 /** 225 * Whether or not the update is a security update or not. If this is true, 226 * then we present more serious sounding user interface messages to the 227 * user. 228 */ 229 attribute boolean isSecurityUpdate; 230 231 /** 232 * When the update was installed. 233 */ 234 attribute long long installDate; 235 236 /** 237 * A message associated with this update, if any. 238 */ 239 attribute AString statusText; 240 241 /** 242 * The currently selected patch for this update. 243 */ 244 readonly attribute nsIUpdatePatch selectedPatch; 245 246 /** 247 * The state of the selected patch: 248 * "downloading" The update is being downloaded. 249 * "pending" The update is ready to be applied. 250 * "pending-service" The update is ready to be applied with the service. 251 * "applying" The update is being applied. 252 * "succeeded" The update was successfully applied. 253 * "download-failed" The update failed to be downloaded. 254 * "failed" The update failed to be applied. 255 */ 256 attribute AString state; 257 258 /** 259 * A numeric error code that conveys additional information about the state 260 * of a failed update or failed certificate attribute check during an update 261 * check. If the update is not in the "failed" state or the certificate 262 * attribute check has not failed the value is zero. 263 * 264 * TODO: Define typical error codes (for now, see updater/errors.h and the 265 * CERT_ATTR_CHECK_FAILED_* values in nsUpdateService.js) 266 */ 267 attribute long errorCode; 268 269 /** 270 * The number of patches supplied by this update. 271 */ 272 readonly attribute unsigned long patchCount; 273 274 /** 275 * Retrieves a patch. 276 * @param index 277 * The index of the patch to retrieve. 278 * @returns The nsIUpdatePatch at the specified index. 279 */ 280 nsIUpdatePatch getPatchAt(in unsigned long index); 281 282 /** 283 * Serializes this update object into a DOM Element 284 * @param updates 285 * The document to serialize into 286 * @returns The DOM Element created by the serialization process 287 */ 288 nsIDOMElement serialize(in nsIDOMDocument updates); 289}; 290 291/** 292 * An interface describing an object that listens to the progress of an update 293 * check operation. This object is notified as the check continues, finishes 294 * and if it has an error. 295 */ 296[scriptable, uuid(8cbceb6e-8e27-46f2-8808-444c6499f836)] 297interface nsIUpdateCheckListener : nsISupports 298{ 299 /** 300 * Called every time there is a progress notification loading the Update 301 * Service file. 302 * @param request 303 * The nsIXMLHttpRequest handling the update check. 304 * @param position 305 * The current byte downloaded 306 * @param totalSize 307 * The total number of bytes that have to be downloaded 308 */ 309 void onProgress(in nsIXMLHttpRequest request, 310 in unsigned long position, 311 in unsigned long totalSize); 312 313 /** 314 * The update check was completed. 315 * @param request 316 * The nsIXMLHttpRequest handling the update check. 317 * @param updates 318 * An array of nsIUpdate objects listing available updates. 319 * @param updateCount 320 * The size of the |updates| array. 321 */ 322 void onCheckComplete(in nsIXMLHttpRequest request, 323 [array, size_is(updateCount)] in nsIUpdate updates, 324 in unsigned long updateCount); 325 326 /** 327 * An error occurred while loading the remote update service file. 328 * @param request 329 * The nsIXMLHttpRequest handling the update check. 330 * @param update 331 * A nsIUpdate object that contains details about the 332 * error in its |statusText| property. 333 */ 334 void onError(in nsIXMLHttpRequest request, 335 in nsIUpdate update); 336}; 337 338/** 339 * An interface describing an object that knows how to check for updates. 340 */ 341[scriptable, uuid(877ace25-8bc5-452a-8586-9c1cf2871994)] 342interface nsIUpdateChecker : nsISupports 343{ 344 /** 345 * Checks for available updates, notifying a listener of the results. 346 * @param listener 347 * An object implementing nsIUpdateCheckListener which is notified 348 * of the results of an update check. 349 * @param force 350 * Forces the checker to check for updates, regardless of the 351 * current value of the user's update settings. This is used by 352 * any piece of UI that offers the user the imperative option to 353 * check for updates now, regardless of their update settings. 354 * force will not work if the system administrator has locked 355 * the app.update.enabled preference. 356 */ 357 void checkForUpdates(in nsIUpdateCheckListener listener, in boolean force); 358 359 /** 360 * Constants for the |stopChecking| function that tell the Checker how long 361 * to stop checking: 362 * 363 * CURRENT_CHECK: Stops the current (active) check only 364 * CURRENT_SESSION: Stops all checking for the current session 365 * ANY_CHECKS: Stops all checking, any session from now on 366 * (disables update checking preferences) 367 */ 368 const unsigned short CURRENT_CHECK = 1; 369 const unsigned short CURRENT_SESSION = 2; 370 const unsigned short ANY_CHECKS = 3; 371 372 /** 373 * Ends any pending update check. 374 * @param duration 375 * A value representing the set of checks to stop doing. 376 */ 377 void stopChecking(in unsigned short duration); 378}; 379 380/** 381 * An interface describing a global application service that handles performing 382 * background update checks and provides utilities for selecting and 383 * downloading update patches. 384 */ 385[scriptable, uuid(b5811144-ed30-4343-aff9-c514034aa19a)] 386interface nsIApplicationUpdateService : nsISupports 387{ 388 /** 389 * The Update Checker used for background update checking. 390 */ 391 readonly attribute nsIUpdateChecker backgroundChecker; 392 393 /** 394 * Selects the best update to install from a list of available updates. 395 * @param updates 396 * An array of updates that are available 397 * @param updateCount 398 * The length of the |updates| array 399 */ 400 nsIUpdate selectUpdate([array, size_is(updateCount)] in nsIUpdate updates, 401 in unsigned long updateCount); 402 403 /** 404 * Adds a listener that receives progress and state information about the 405 * update that is currently being downloaded, e.g. to update a user 406 * interface. 407 * @param listener 408 * An object implementing nsIRequestObserver and optionally 409 * nsIProgressEventSink that is to be notified of state and 410 * progress information as the update is downloaded. 411 */ 412 void addDownloadListener(in nsIRequestObserver listener); 413 414 /** 415 * Removes a listener that is receiving progress and state information 416 * about the update that is currently being downloaded. 417 * @param listener 418 * The listener object to remove. 419 */ 420 void removeDownloadListener(in nsIRequestObserver listener); 421 422 /** 423 * 424 */ 425 AString downloadUpdate(in nsIUpdate update, in boolean background); 426 427 /** 428 * Pauses the active update download process 429 */ 430 void pauseDownload(); 431 432 /** 433 * Whether or not there is an download happening at the moment. 434 */ 435 readonly attribute boolean isDownloading; 436 437 /** 438 * Whether or not the Update Service can check for updates. This is a function 439 * of whether or not application update is disabled by the application and the 440 * platform the application is running on. 441 */ 442 readonly attribute boolean canCheckForUpdates; 443 444 /** 445 * Whether or not the Update Service can download and install updates. 446 * This is a function of whether or not the current user has access 447 * privileges to the install directory. 448 */ 449 readonly attribute boolean canApplyUpdates; 450}; 451 452/** 453 * An interface describing a global application service that maintains a list 454 * of updates previously performed as well as the current active update. 455 */ 456[scriptable, uuid(fede66a9-9f96-4507-a22a-775ee885577e)] 457interface nsIUpdateManager : nsISupports 458{ 459 /** 460 * Gets the update at the specified index 461 * @param index 462 * The index within the updates array 463 * @returns The nsIUpdate object at the specified index 464 */ 465 nsIUpdate getUpdateAt(in long index); 466 467 /** 468 * Gets the total number of updates in the history list. 469 */ 470 readonly attribute long updateCount; 471 472 /** 473 * The active (current) update. The active update is not in the history list. 474 */ 475 attribute nsIUpdate activeUpdate; 476 477 /** 478 * Saves all updates to disk. 479 */ 480 void saveUpdates(); 481}; 482 483/** 484 * An interface describing an object that can show various kinds of Update 485 * notification UI to the user. 486 */ 487[scriptable, uuid(599fd3c6-ec68-4499-ada5-2997739c97a6)] 488interface nsIUpdatePrompt : nsISupports 489{ 490 /** 491 * Shows the application update checking user interface and checks if there 492 * is an update available. 493 */ 494 void checkForUpdates(); 495 496 /** 497 * Shows the application update available user interface advising that an 498 * update is available for download and install. If the app.update.silent 499 * preference is true or the user interface is already displayed the call will 500 * be a no-op. 501 * @param update 502 * The nsIUpdate object to be downloaded and installed 503 */ 504 void showUpdateAvailable(in nsIUpdate update); 505 506 /** 507 * Shows the application update downloaded user interface advising that an 508 * update has now been downloaded and a restart is necessary to complete the 509 * update. If background is true (e.g. the download was not user initiated) 510 * and the app.update.silent preference is true the call will be a no-op. 511 * @param update 512 * The nsIUpdate object that was downloaded 513 * @param background 514 * Less obtrusive UI, starting with a non-modal notification alert 515 */ 516 void showUpdateDownloaded(in nsIUpdate update, 517 [optional] in boolean background); 518 519 /** 520 * Shows the application update installed user interface advising that an 521 * update was installed successfully. If the app.update.silent preference is 522 * true, the app.update.showInstalledUI preference is false, or the user 523 * interface is already displayed the call will be a no-op. 524 */ 525 void showUpdateInstalled(); 526 527 /** 528 * Shows the application update error user interface advising that an error 529 * occurred while checking for or applying an update. If the app.update.silent 530 * preference is true the call will be a no-op. 531 * @param update 532 * An nsIUpdate object representing the update that could not be 533 * installed. The nsIUpdate object will not be the actual update when 534 * the error occurred during an update check and will instead be an 535 * nsIUpdate object with the error information for the update check. 536 */ 537 void showUpdateError(in nsIUpdate update); 538 539 /** 540 * Shows a list of all updates installed to date. 541 * @param parent 542 * An nsIDOMWindow to set as the parent for this window. Can be null. 543 */ 544 void showUpdateHistory(in nsIDOMWindow parent); 545};