gecko/dom/interfaces/apps/nsIDOMApplicationRegistry.idl

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "domstubs.idl"
#include "nsIDOMEventTarget.idl"

interface nsIDOMDOMRequest;

[scriptable, uuid(f8cb08ed-588e-465f-b2b3-a4b0afde711a)]
interface mozIDOMApplication  : nsISupports
{
  readonly attribute jsval manifest;
  readonly attribute jsval updateManifest;
  readonly attribute DOMString manifestURL;
  readonly attribute jsval receipts; /* an array of strings */
  readonly attribute DOMString origin;
  readonly attribute DOMString installOrigin;
  readonly attribute unsigned long long installTime;
  readonly attribute boolean removable;

  /**
   * The current progress when downloading an offline cache.
   */
  readonly attribute double progress;

  /**
   * The application installation state :
   * "pending"   : The application is being installed (eg, we're downloading the
   *               offline cache or the package).
   * "installed" : The application is installed and ready to be launched.
   * "updating"  : We are updating the offline-cache or the package.
   */
  readonly attribute DOMString installState;

  /**
   * fires a nsIDOMApplicationEvent when a change in appcache download or
   * package download happens.
   */
  attribute nsIDOMEventListener onprogress;

  /**
   * The date of the last update check.
   */
  readonly attribute unsigned long long lastUpdateCheck;

  /**
   * The date of the last updated manifest.
   */
  readonly attribute unsigned long long updateTime;

  /**
   * Starts the process of looking for an update.
   */
  nsIDOMDOMRequest checkForUpdate();

  readonly attribute boolean downloadAvailable;
  readonly attribute boolean downloading;
  readonly attribute boolean readyToApplyDownload;
  readonly attribute long downloadSize;

  // This is a DOMError
  readonly attribute nsISupports downloadError;

  attribute nsIDOMEventListener ondownloadsuccess;
  attribute nsIDOMEventListener ondownloaderror;
  attribute nsIDOMEventListener ondownloadavailable;

  /**
   * Will fire once the mgmt.applyDownload() call succeeds.
   */
  attribute nsIDOMEventListener ondownloadapplied;

  /**
   * Starts to download an update. If |downloading| is true, this
   * is a no-op.
   */
  void download();

  /**
   * Cancels an ongoing update download.
   */
  void cancelDownload();

  /* startPoint will be used when several launch_path exists for an app */
  nsIDOMDOMRequest launch([optional] in DOMString startPoint);

  /**
   * Clear data that has been collected through mozbrowser elements.
   * onsuccess will be called once data is actually cleared.
   */
  nsIDOMDOMRequest clearBrowserData();

  /**
   * Inter-App Communication APIs.
   *
   * https://wiki.mozilla.org/WebAPI/Inter_App_Communication_Alt_proposal
   */
  nsISupports connect(in DOMString keyword,
                      [optional] in jsval rules); // nsISupports is a Promise.

  nsISupports getConnections(); // nsISupports is a Promise.

  /* Receipts handling functions */
  nsIDOMDOMRequest addReceipt(in DOMString receipt);
  nsIDOMDOMRequest removeReceipt(in DOMString receipt);
  nsIDOMDOMRequest replaceReceipt(in DOMString oldReceipt, in DOMString newReceipt);
};

[scriptable, uuid(cf742022-5ba3-11e2-868f-03310341b006)]
interface mozIDOMApplicationMgmt : nsISupports
{
  /**
   * the request will return the all the applications installed. Only accessible
   * to privileged callers.
   */
  nsIDOMDOMRequest getAll();

  /**
   * the request will return the applications acquired from all origins but
   * which are not launchable (e.g. by not being natively installed), or null.
   */
  nsIDOMDOMRequest getNotInstalled();

  /**
   * event listener to get notified of application installs. Only settable by
   * privileged callers.
   * the event will be a mozIDOMApplicationEvent
   */
  attribute nsIDOMEventListener oninstall;

  /**
   * event listener to get notified of application uninstalls. Only settable by
   * privileged callers.
   * the event will be a mozIDOMApplicationEvent
   */
  attribute nsIDOMEventListener onuninstall;

  /**
   * Applies a downloaded update.
   * This function is a no-op if it's passed an app object which doesn't have
   * |readyToApplyDownload| set to true.
   */
  void applyDownload(in mozIDOMApplication app);

  /**
   * Uninstall a web app.
   *
   * @param app : the app object of the web app to be uninstalled.
   * @returns   : A DOMRequest object, returning the app's origin in |result|
   *              if uninstall succeeds; returning "NOT_INSTALLED" error otherwise.
   */
  nsIDOMDOMRequest uninstall(in mozIDOMApplication app);
};

[scriptable, uuid(52710c5f-b2a2-4b27-b5b9-f679a1bcc79b)]
interface mozIDOMApplicationRegistry : nsISupports
{
  /**
   * Install a web app.
   *
   * @param manifestUrl : the URL of the webapps manifest.
   * @param parameters  : A structure with optional information.
   *                      {
   *                       receipts: ...    Will be used to specify the payment receipts for this installation.
   *                       categories: ...  Will be used to specify the categories of the webapp.
   *                      }
   * @returns           : A DOMRequest object, returning the app object in |result| if install succeeds.
   */
  nsIDOMDOMRequest install(in DOMString manifestUrl, [optional] in jsval parameters);

  /**
   * the request will return the application currently installed, or null.
   */
  nsIDOMDOMRequest getSelf();

  /**
   * the request will return the application if the app from that origin is installed
   */
  nsIDOMDOMRequest checkInstalled(in DOMString manifestUrl);

  /**
   * the request will return the applications installed from this origin, or null.
   */
  nsIDOMDOMRequest getInstalled();

  /**
   * Install a packaged web app.
   *
   * @param packageUrl : the URL of the webapps manifest.
   * @param parameters : A structure with optional information.
   *                      {
   *                       receipts: ...    Will be used to specify the payment receipts for this installation.
   *                       categories: ...  Will be used to specify the categories of the webapp.
   *                      }
   * @returns          : A DOMRequest object, returning the app object in |result| if install succeeds.
   */
  nsIDOMDOMRequest installPackage(in DOMString packageUrl, [optional] in jsval parameters);

  readonly attribute mozIDOMApplicationMgmt mgmt;
};