toolkit/mozapps/update/nsIUpdateService.idl@6474c204b198
toolkit/mozapps/update/nsIUpdateService.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #include "nsISupports.idl"
8 interface nsIDOMDocument;
9 interface nsIDOMElement;
10 interface nsIDOMWindow;
11 interface nsIRequest;
12 interface nsIRequestObserver;
13 interface nsISimpleEnumerator;
14 interface nsIXMLHttpRequest;
15 interface nsIFile;
17 /**
18 * An interface that describes an object representing a patch file that can
19 * be downloaded and applied to a version of this application so that it
20 * can be updated.
21 */
22 [scriptable, uuid(dc8fb8a9-3a53-4031-9469-2a5197ea30e7)]
23 interface nsIUpdatePatch : nsISupports
24 {
25 /**
26 * The type of this patch:
27 * "partial" A binary difference between two application versions
28 * "complete" A complete patch containing all of the replacement files
29 * to update to the new version
30 */
31 attribute AString type;
33 /**
34 * The URL this patch was being downloaded from
35 */
36 attribute AString URL;
38 /**
39 * The final URL this patch was being downloaded from
40 */
41 attribute AString finalURL;
43 /**
44 * The hash function to use when determining this file's integrity
45 */
46 attribute AString hashFunction;
48 /**
49 * The value of the hash function named above that should be computed if
50 * this file is not corrupt.
51 */
52 attribute AString hashValue;
54 /**
55 * The size of this file, in bytes.
56 */
57 attribute unsigned long size;
59 /**
60 * The state of this patch
61 */
62 attribute AString state;
64 /**
65 * true if this patch is currently selected as the patch to be downloaded and
66 * installed for this update transaction, false if another patch from this
67 * update has been selected.
68 */
69 attribute boolean selected;
71 /**
72 * Serializes this patch object into a DOM Element
73 * @param updates
74 * The document to serialize into
75 * @returns The DOM Element created by the serialization process
76 */
77 nsIDOMElement serialize(in nsIDOMDocument updates);
78 };
80 /**
81 * An interface that describes an object representing an available update to
82 * the current application - this update may have several available patches
83 * from which one must be selected to download and install, for example we
84 * might select a binary difference patch first and attempt to apply that,
85 * then if the application process fails fall back to downloading a complete
86 * file-replace patch. This object also contains information about the update
87 * that the front end and other application services can use to learn more
88 * about what is going on.
89 */
90 [scriptable, uuid(6b0b7721-6746-443d-8cb0-c6199d7f28a6)]
91 interface nsIUpdate : nsISupports
92 {
93 /**
94 * The type of update:
95 * "major" A major new version of the Application
96 * "minor" A minor update to the Application (e.g. security update)
97 */
98 attribute AString type;
100 /**
101 * The name of the update, or "<Application Name> <Update Version>"
102 */
103 attribute AString name;
105 /**
106 * The string to display in the user interface for the version. If you want
107 * a real version number use appVersion.
108 */
109 attribute AString displayVersion;
111 /**
112 * The Application version of this update.
113 */
114 attribute AString appVersion;
116 /**
117 * The Toolkit version of this update.
118 */
119 attribute AString platformVersion;
121 /**
122 * The Application version prior to the application being updated.
123 */
124 attribute AString previousAppVersion;
126 /**
127 * The Build ID of this update. Used to determine a particular build, down
128 * to the hour, minute and second of its creation. This allows the system
129 * to differentiate between several nightly builds with the same |version|
130 * for example.
131 */
132 attribute AString buildID;
134 /**
135 * The URL to a page which offers details about the content of this
136 * update. Ideally, this page is not the release notes but some other page
137 * that summarizes the differences between this update and the previous,
138 * which also links to the release notes.
139 */
140 attribute AString detailsURL;
142 /**
143 * The URL to a page that is typically localized to display in the update
144 * prompt.
145 */
146 attribute AString billboardURL;
148 /**
149 * The URL to a HTML fragment that contains a license for this update. If
150 * this is specified, the user is shown the license file after they choose
151 * to install the update and they must agree to it before the download
152 * commences.
153 */
154 attribute AString licenseURL;
156 /**
157 * The URL to the Update Service that supplied this update.
158 */
159 attribute AString serviceURL;
161 /**
162 * The channel used to retrieve this update from the Update Service.
163 */
164 attribute AString channel;
166 /**
167 * Whether to show the update prompt which requires user confirmation when an
168 * update is found during a background update check. This overrides the
169 * default setting to download the update in the background.
170 */
171 attribute boolean showPrompt;
173 /**
174 * Whether to show the "No Thanks" button in the update prompt. This allows
175 * the user to never receive a notification for that specific update version
176 * again.
177 */
178 attribute boolean showNeverForVersion;
180 /**
181 * Whether the update is no longer supported on this system.
182 */
183 attribute boolean unsupported;
185 /**
186 * Allows overriding the default amount of time in seconds before prompting the
187 * user to apply an update. If not specified, the value of
188 * app.update.promptWaitTime will be used.
189 */
190 attribute long long promptWaitTime;
192 /**
193 * Whether or not the update being downloaded is a complete replacement of
194 * the user's existing installation or a patch representing the difference
195 * between the new version and the previous version.
196 */
197 attribute boolean isCompleteUpdate;
199 /**
200 * Whether or not the update is a security update or not. If this is true,
201 * then we present more serious sounding user interface messages to the
202 * user.
203 */
204 attribute boolean isSecurityUpdate;
206 /**
207 * Whether or not the update being downloaded is an OS update. This is
208 * generally only possible in Gonk right now.
209 */
210 attribute boolean isOSUpdate;
212 /**
213 * When the update was installed.
214 */
215 attribute long long installDate;
217 /**
218 * A message associated with this update, if any.
219 */
220 attribute AString statusText;
222 /**
223 * The currently selected patch for this update.
224 */
225 readonly attribute nsIUpdatePatch selectedPatch;
227 /**
228 * The state of the selected patch:
229 * "downloading" The update is being downloaded.
230 * "pending" The update is ready to be applied.
231 * "pending-service" The update is ready to be applied with the service.
232 * "applying" The update is being applied.
233 * "applied" The update is ready to be switched to.
234 * "applied-os" The update is OS update and to be installed.
235 * "applied-service" The update is ready to be switched to with the service.
236 * "succeeded" The update was successfully applied.
237 * "download-failed" The update failed to be downloaded.
238 * "failed" The update failed to be applied.
239 */
240 attribute AString state;
242 /**
243 * A numeric error code that conveys additional information about the state
244 * of a failed update or failed certificate attribute check during an update
245 * check. If the update is not in the "failed" state or the certificate
246 * attribute check has not failed the value is zero.
247 *
248 * TODO: Define typical error codes (for now, see updater/errors.h and the
249 * CERT_ATTR_CHECK_FAILED_* values in nsUpdateService.js)
250 */
251 attribute long errorCode;
253 /**
254 * The number of patches supplied by this update.
255 */
256 readonly attribute unsigned long patchCount;
258 /**
259 * Retrieves a patch.
260 * @param index
261 * The index of the patch to retrieve.
262 * @returns The nsIUpdatePatch at the specified index.
263 */
264 nsIUpdatePatch getPatchAt(in unsigned long index);
266 /**
267 * Serializes this update object into a DOM Element
268 * @param updates
269 * The document to serialize into
270 * @returns The DOM Element created by the serialization process
271 */
272 nsIDOMElement serialize(in nsIDOMDocument updates);
273 };
275 /**
276 * An interface describing an object that listens to the progress of an update
277 * check operation. This object is notified as the check continues, finishes
278 * and if it has an error.
279 */
280 [scriptable, uuid(4aa2b4bb-39ea-407b-98ff-89f19134d4c0)]
281 interface nsIUpdateCheckListener : nsISupports
282 {
283 /**
284 * The update check was completed.
285 * @param request
286 * The nsIXMLHttpRequest handling the update check.
287 * @param updates
288 * An array of nsIUpdate objects listing available updates.
289 * @param updateCount
290 * The size of the |updates| array.
291 */
292 void onCheckComplete(in nsIXMLHttpRequest request,
293 [array, size_is(updateCount)] in nsIUpdate updates,
294 in unsigned long updateCount);
296 /**
297 * An error occurred while loading the remote update service file.
298 * @param request
299 * The nsIXMLHttpRequest handling the update check.
300 * @param update
301 * A nsIUpdate object that contains details about the
302 * error in its |statusText| property.
303 */
304 void onError(in nsIXMLHttpRequest request,
305 in nsIUpdate update);
306 };
308 /**
309 * An interface describing an object that knows how to check for updates.
310 */
311 [scriptable, uuid(877ace25-8bc5-452a-8586-9c1cf2871994)]
312 interface nsIUpdateChecker : nsISupports
313 {
314 /**
315 * Checks for available updates, notifying a listener of the results.
316 * @param listener
317 * An object implementing nsIUpdateCheckListener which is notified
318 * of the results of an update check.
319 * @param force
320 * Forces the checker to check for updates, regardless of the
321 * current value of the user's update settings. This is used by
322 * any piece of UI that offers the user the imperative option to
323 * check for updates now, regardless of their update settings.
324 * force will not work if the system administrator has locked
325 * the app.update.enabled preference.
326 */
327 void checkForUpdates(in nsIUpdateCheckListener listener, in boolean force);
329 /**
330 * Constants for the |stopChecking| function that tell the Checker how long
331 * to stop checking:
332 *
333 * CURRENT_CHECK: Stops the current (active) check only
334 * CURRENT_SESSION: Stops all checking for the current session
335 * ANY_CHECKS: Stops all checking, any session from now on
336 * (disables update checking preferences)
337 */
338 const unsigned short CURRENT_CHECK = 1;
339 const unsigned short CURRENT_SESSION = 2;
340 const unsigned short ANY_CHECKS = 3;
342 /**
343 * Ends any pending update check.
344 * @param duration
345 * A value representing the set of checks to stop doing.
346 */
347 void stopChecking(in unsigned short duration);
348 };
350 /**
351 * An interface describing a global application service that handles performing
352 * background update checks and provides utilities for selecting and
353 * downloading update patches.
354 */
355 [scriptable, uuid(9f9b51f5-340e-47ce-85ae-9eb077c6cd39)]
356 interface nsIApplicationUpdateService : nsISupports
357 {
358 /**
359 * Checks for available updates in the background using the listener provided
360 * by the application update service for background checks.
361 */
362 void checkForBackgroundUpdates();
364 /**
365 * The Update Checker used for background update checking.
366 */
367 readonly attribute nsIUpdateChecker backgroundChecker;
369 /**
370 * Selects the best update to install from a list of available updates.
371 * @param updates
372 * An array of updates that are available
373 * @param updateCount
374 * The length of the |updates| array
375 */
376 nsIUpdate selectUpdate([array, size_is(updateCount)] in nsIUpdate updates,
377 in unsigned long updateCount);
379 /**
380 * Adds a listener that receives progress and state information about the
381 * update that is currently being downloaded, e.g. to update a user
382 * interface.
383 * @param listener
384 * An object implementing nsIRequestObserver and optionally
385 * nsIProgressEventSink that is to be notified of state and
386 * progress information as the update is downloaded.
387 */
388 void addDownloadListener(in nsIRequestObserver listener);
390 /**
391 * Removes a listener that is receiving progress and state information
392 * about the update that is currently being downloaded.
393 * @param listener
394 * The listener object to remove.
395 */
396 void removeDownloadListener(in nsIRequestObserver listener);
398 /**
399 *
400 */
401 AString downloadUpdate(in nsIUpdate update, in boolean background);
403 /**
404 * Apply the OS update which has been downloaded and staged as applied.
405 * @param update
406 * The update has been downloaded and staged as applied.
407 * @throws if the update object is not an OS update.
408 */
409 void applyOsUpdate(in nsIUpdate update);
411 /**
412 * Get the Active Updates directory
413 * @returns An nsIFile for the active updates directory.
414 */
415 nsIFile getUpdatesDirectory();
417 /**
418 * Pauses the active update download process
419 */
420 void pauseDownload();
422 /**
423 * Whether or not there is an download happening at the moment.
424 */
425 readonly attribute boolean isDownloading;
427 /**
428 * Whether or not the Update Service can check for updates. This is a function
429 * of whether or not application update is disabled by the application and the
430 * platform the application is running on.
431 */
432 readonly attribute boolean canCheckForUpdates;
434 /**
435 * Whether or not the Update Service can download and install updates.
436 * On Windows, this is a function of whether or not the maintenance service
437 * is installed and enabled. On other systems, and as a fallback on Windows,
438 * this depends on whether the current user has write access to the install
439 * directory.
440 */
441 readonly attribute boolean canApplyUpdates;
443 /**
444 * Whether or not a different instance is handling updates of this
445 * installation. This currently only ever returns true on Windows
446 * when 2 instances of an application are open or when both the Metro
447 * and Desktop browsers are open. Only one of the instances will actually
448 * handle updates for the installation.
449 */
450 readonly attribute boolean isOtherInstanceHandlingUpdates;
452 /**
453 * Whether the Update Service is able to stage updates.
454 */
455 readonly attribute boolean canStageUpdates;
456 };
458 /**
459 * An interface describing a component which handles the job of processing
460 * an update after it's been downloaded.
461 */
462 [scriptable, uuid(74439497-d796-4915-8cef-3dfe43027e4d)]
463 interface nsIUpdateProcessor : nsISupports
464 {
465 /**
466 * Processes the update which has been downloaded.
467 * This happens without restarting the application.
468 * On Windows, this can also be used for switching to an applied
469 * update request.
470 * @param update The update being applied, or null if this is a switch
471 * to updated application request. Must be non-null on GONK.
472 */
473 void processUpdate(in nsIUpdate update);
474 };
476 /**
477 * An interface describing a global application service that maintains a list
478 * of updates previously performed as well as the current active update.
479 */
480 [scriptable, uuid(c5df56de-919d-406b-aaf9-106dfa9b685b)]
481 interface nsIUpdateManager : nsISupports
482 {
483 /**
484 * Gets the update at the specified index
485 * @param index
486 * The index within the updates array
487 * @returns The nsIUpdate object at the specified index
488 */
489 nsIUpdate getUpdateAt(in long index);
491 /**
492 * Gets the total number of updates in the history list.
493 */
494 readonly attribute long updateCount;
496 /**
497 * The active (current) update. The active update is not in the history list.
498 */
499 attribute nsIUpdate activeUpdate;
501 /**
502 * Saves all updates to disk.
503 */
504 void saveUpdates();
506 /**
507 * Refresh the update status based on the information in update.status.
508 */
509 void refreshUpdateStatus(in nsIUpdate update);
510 };
512 /**
513 * An interface describing an object that can show various kinds of Update
514 * notification UI to the user.
515 */
516 [scriptable, uuid(599fd3c6-ec68-4499-ada5-2997739c97a6)]
517 interface nsIUpdatePrompt : nsISupports
518 {
519 /**
520 * Shows the application update checking user interface and checks if there
521 * is an update available.
522 */
523 void checkForUpdates();
525 /**
526 * Shows the application update available user interface advising that an
527 * update is available for download and install. If the app.update.silent
528 * preference is true or the user interface is already displayed the call will
529 * be a no-op.
530 * @param update
531 * The nsIUpdate object to be downloaded and installed
532 */
533 void showUpdateAvailable(in nsIUpdate update);
535 /**
536 * Shows the application update downloaded user interface advising that an
537 * update has now been downloaded and a restart is necessary to complete the
538 * update. If background is true (e.g. the download was not user initiated)
539 * and the app.update.silent preference is true the call will be a no-op.
540 * @param update
541 * The nsIUpdate object that was downloaded
542 * @param background
543 * Less obtrusive UI, starting with a non-modal notification alert
544 */
545 void showUpdateDownloaded(in nsIUpdate update,
546 [optional] in boolean background);
548 /**
549 * Shows the application update installed user interface advising that an
550 * update was installed successfully. If the app.update.silent preference is
551 * true, the app.update.showInstalledUI preference is false, or the user
552 * interface is already displayed the call will be a no-op.
553 */
554 void showUpdateInstalled();
556 /**
557 * Shows the application update error user interface advising that an error
558 * occurred while checking for or applying an update. If the app.update.silent
559 * preference is true the call will be a no-op.
560 * @param update
561 * An nsIUpdate object representing the update that could not be
562 * installed. The nsIUpdate object will not be the actual update when
563 * the error occurred during an update check and will instead be an
564 * nsIUpdate object with the error information for the update check.
565 */
566 void showUpdateError(in nsIUpdate update);
568 /**
569 * Shows a list of all updates installed to date.
570 * @param parent
571 * An nsIDOMWindow to set as the parent for this window. Can be null.
572 */
573 void showUpdateHistory(in nsIDOMWindow parent);
574 };
