/* 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 nsIDOMWindow;
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(502f206a-c6b4-4e98-b442-e335792e2594)]
interface amIWebInstallInfo : nsISupports
{
  readonly attribute nsISupports originator;
  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(a5503979-89c8-441e-9e4a-321df379c172)]
interface amIWebInstallListener : nsISupports
{
  /**
   * Called when installation by websites is currently disabled.
   *
   * @param  aOriginator
   *         The window or 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 nsISupports aOriginator, 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  aWindow
   *         The window or 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 nsISupports aOriginator, 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  aWindow
   *         The window or 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 nsISupports aOriginator, 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(c5529918-4291-4b56-bd46-e9268900f2a3)]
interface amIWebInstallPrompt : nsISupports
{
  /**
   * Get a confirmation that the user wants to start the installs.
   *
   * @param  aWindow
   *         The window 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 nsIDOMWindow aWindow, in nsIURI aUri,
               [array, size_is(aCount)] in nsIVariant aInstalls,
               [optional] in uint32_t aCount);
};
