PageRenderTime 24ms CodeModel.GetById 11ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 1ms

/toolkit/mozapps/update/nsIUpdateService.idl

http://github.com/zpao/v8monkey
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};