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