/* 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 "nsISupports.idl"

interface nsIDOMElement;
interface nsIURI;
interface nsIVariant;

/**
 * amIWebInstallInfo is used by the default implementation of
 * amIWebInstallListener to communicate with the running application and allow
 * it to warn the user about blocked installs and start the installs running.
 */
[scriptable, uuid(fa0b47a3-f819-47ac-bc66-4bd1d7f67b1d)]
interface amIWebInstallInfo : nsISupports
{
  readonly attribute nsIDOMElement browser;
  readonly attribute nsIURI originatingURI;
  readonly attribute nsIVariant installs;

  /**
   * Starts all installs.
   */
  void install();
};

/**
 * The registered amIWebInstallListener is used to notify about new installs
 * triggered by websites. The default implementation displays a confirmation
 * dialog when add-ons are ready to install and uses the observer service to
 * notify when installations are blocked.
 */
[scriptable, uuid(d9240d4b-6b3a-4cad-b402-de6c93337e0c)]
interface amIWebInstallListener : nsISupports
{
  /**
   * Called when installation by websites is currently disabled.
   *
   * @param  aBrowser
   *         The browser that triggered the installs
   * @param  aUri
   *         The URI of the site that triggered the installs
   * @param  aInstalls
   *         The AddonInstalls that were blocked
   * @param  aCount
   *         The number of AddonInstalls
   */
  void onWebInstallDisabled(in nsIDOMElement aBrowser, in nsIURI aUri,
                            [array, size_is(aCount)] in nsIVariant aInstalls,
                            [optional] in uint32_t aCount);

  /**
   * Called when the website is not allowed to directly prompt the user to
   * install add-ons.
   *
   * @param  aBrowser
   *         The browser that triggered the installs
   * @param  aUri
   *         The URI of the site that triggered the installs
   * @param  aInstalls
   *         The AddonInstalls that were blocked
   * @param  aCount
   *         The number of AddonInstalls
   * @return true if the caller should start the installs
   */
  boolean onWebInstallBlocked(in nsIDOMElement aBrowser, in nsIURI aUri,
                              [array, size_is(aCount)] in nsIVariant aInstalls,
                              [optional] in uint32_t aCount);

  /**
   * Called when a website wants to ask the user to install add-ons.
   *
   * @param  aBrowser
   *         The browser that triggered the installs
   * @param  aUri
   *         The URI of the site that triggered the installs
   * @param  aInstalls
   *         The AddonInstalls that were requested
   * @param  aCount
   *         The number of AddonInstalls
   * @return true if the caller should start the installs
   */
  boolean onWebInstallRequested(in nsIDOMElement aBrowser, in nsIURI aUri,
                                [array, size_is(aCount)] in nsIVariant aInstalls,
                                [optional] in uint32_t aCount);
};

[scriptable, uuid(a80b89ad-bb1a-4c43-9cb7-3ae656556f78)]
interface amIWebInstallListener2 : nsISupports
{
  /**
   * Called when a non-same-origin resource attempted to initiate an install.
   * Installs will have already been cancelled and cannot be restarted.
   *
   * @param  aBrowser
   *         The browser that triggered the installs
   * @param  aUri
   *         The URI of the site that triggered the installs
   * @param  aInstalls
   *         The AddonInstalls that were blocked
   * @param  aCount
   *         The number of AddonInstalls
   */
  boolean onWebInstallOriginBlocked(in nsIDOMElement aBrowser, in nsIURI aUri,
                                    [array, size_is(aCount)] in nsIVariant aInstalls,
                                    [optional] in uint32_t aCount);
};

/**
 * amIWebInstallPrompt is used, if available, by the default implementation of 
 * amIWebInstallInfo to display a confirmation UI to the user before running
 * installs.
 */
[scriptable, uuid(386906f1-4d18-45bf-bc81-5dcd68e42c3b)]
interface amIWebInstallPrompt : nsISupports
{
  /**
   * Get a confirmation that the user wants to start the installs.
   *
   * @param  aBrowser
   *         The browser that triggered the installs
   * @param  aUri
   *         The URI of the site that triggered the installs
   * @param  aInstalls
   *         The AddonInstalls that were requested
   * @param  aCount
   *         The number of AddonInstalls
   */
  void confirm(in nsIDOMElement aBrowser, in nsIURI aUri,
               [array, size_is(aCount)] in nsIVariant aInstalls,
               [optional] in uint32_t aCount);
};