/* 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 "nsIAlertsService.idl"
#include "nsIFile.idl"

[scriptable, uuid(a46c385b-a45c-4b48-ab7c-aaed1252bb83)]
interface nsIWindowsAlertNotification : nsIAlertNotification
{
  /**
   * Image placements corresponding to placements in Windows Toast
   * Notification XML.
   */
  cenum ImagePlacement : 8 {
    eInline,
    eHero,
    eIcon,
  };

  /**
   * Enum to specify image placement we want in the notification. n.b. in the
   * future we could extend this to instead allow multiple images in differing
   * placements in the same notification.
   */
  attribute nsIWindowsAlertNotification_ImagePlacement imagePlacement;

  /**
   * An image file on disk to use in the notification. This allows callers to
   * control the image type used for the notification, bypassing limitations of
   * in-source encoders.
   *
   * TODO: note notification events which signal the image is displayed
   * Callers are responsible for removing the image if necessary, after the
   * notification has displayed.
   *
   * WARNING: No validation is performed on this file beyond that it was set
   * from a system principal. This should only be used for files from trusted
   * sources.
   */
  attribute AString imagePathUnchecked;
};

[scriptable, uuid(e01c8066-fb4b-4304-b9c9-ab6ed4a8322c)]
interface nsIWindowsAlertsService : nsIAlertsService
{
  /**
   * If callbacks for the given Windows-specific tag string will be handled by
   * this Firefox process, set the associated event.
   *
   * @param {AString} aWindowsTag the tag
   * @return {Promise}
   * @resolves {Object}
   *           Resolves with an Object, may contain the following optional
   *           properties if notification exists but wasn't registered with
   *           the WindowsAlertsService:
   *
   *           `notificationData` {string} relaunch data, generally opaque to
   *           the Windows notification server DLL, for this relaunch.
   *
   * @rejects `nsresult` when there was an error retrieving the notification.
   */
  [implicit_jscontext]
  Promise handleWindowsTag(in AString aWindowsTag);

  /**
   * Get the Windows-specific XML generated for the given alert.
   *
   * @note This method is intended for testing purposes.
   *
   * @param {nsIAlertNotification} aAlert the alert
   * @param {AString} an optional Windows tag; default is generated
   * @return {string} generated XML
   */
  AString getXmlStringForWindowsAlert(in nsIAlertNotification aAlert,
                                      [optional] in AString aWindowsTag);

  /**
   * Removes all action center and snoozed notifications associated with this
   * install. Note that this removes all notifications regardless of which profile
   * they originated from.
   */
  void removeAllNotificationsForInstall();
};