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(6f145728-abc0-11dc-8314-0800200c9a66)]
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 * the user should restart their software should be restarted so that the
462 * update can be installed.
463 * @param update
464 * The update that was downloaded
465 * @param background
466 * Less obtrusive UI, starting with a non-modal notification alert
467 */
468 void showUpdateDownloaded(in nsIUpdate update,
469 [optional] in boolean background);
470
471 /**
472 * Shows a message detailing the update which was installed.
473 * @param update
474 * The nsIUpdate object which was just installed
475 */
476 void showUpdateInstalled(in nsIUpdate update);
477
478 /**
479 * Shows an error message UI telling the user about some kind of update
480 * failure, e.g. failure to apply patch.
481 * @param update
482 * The nsIUpdate object which we could not install
483 */
484 void showUpdateError(in nsIUpdate update);
485
486 /**
487 * Shows a list of all updates installed to date.
488 * @param parent
489 * A parent window to anchor this window to. Can be null.
490 */
491 void showUpdateHistory(in nsIDOMWindow parent);
492 };
493
494 /**
495 * An interface describing a global application service that allows long
496 * duration (e.g. 1-7 or more days, weeks or months) timers to be registered
497 * and then fired.
498 */
499 [scriptable, uuid(0765c92c-6145-4253-9db4-594d8023087e)]
500 interface nsIUpdateTimerManager : nsISupports
501 {
502 /**
503 * Register an interval with the timer manager. The timer manager
504 * periodically checks to see if the interval has expired and if it has
505 * calls the specified callback. This is persistent across application
506 * restarts and can handle intervals of long durations.
507 * @param id
508 * An id that identifies the interval, used for persistence
509 * @param callback
510 * A nsITimerCallback object that is notified when the interval
511 * expires
512 * @param interval
513 * The length of time, in seconds, of the interval
514 */
515 void registerTimer(in AString id,
516 in nsITimerCallback callback,
517 in unsigned long interval);
518 };