toolkit/components/alerts/nsIAlertsService.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7 #include "nsIObserver.idl"
   8
   9 interface imgIRequest;
  10 interface nsICancelable;
  11 interface nsIPrincipal;
  12 interface nsIURI;
  13
  14 %{C++
  15 #define ALERT_NOTIFICATION_CONTRACTID "@mozilla.org/alert-notification;1"
  16 %}
  17
  18 [scriptable, uuid(a71a637d-de1d-47c6-a8d2-c60b2596f471)]
  19 interface nsIAlertNotificationImageListener : nsISupports
  20 {
  21   /**
  22    * Called when the image finishes loading.
  23    *
  24    * @param aUserData An opaque parameter passed to |loadImage|.
  25    * @param aRequest  The image request.
  26    */
  27   void onImageReady(in nsISupports aUserData, in imgIRequest aRequest);
  28
  29   /**
  30    * Called if the alert doesn't have an image, or if the image request times
  31    * out or fails.
  32    *
  33    * @param aUserData An opaque parameter passed to |loadImage|.
  34    */
  35   void onImageMissing(in nsISupports aUserData);
  36 };
  37
  38 [scriptable, uuid(a054c2c9-2787-4686-859c-45609d790056)]
  39 interface nsIAlertAction : nsISupports
  40 {
  41   /**
  42    * Returns a string identifying a user action to be displayed on the alert.
  43    *
  44    * This string is an opaque identifier that identifies an action in potential
  45    * callbacks; it is not displayed to the user.
  46    */
  47   readonly attribute AString action;
  48
  49   /**
  50    * Returns a string containing action text to be shown to the user.
  51    */
  52   readonly attribute AString title;
  53
  54   /**
  55    * Returns a string containing the URL of an icon to display with the action.
  56    */
  57   readonly attribute AString iconURL;
  58
  59   /**
  60    * On Windows, chrome-privileged notifications -- i.e., those with a
  61    * non-actionable principal -- can have actions that are activated by Windows
  62    * and not processed by Firefox.  When `windowsSystemActivationType` is true,
  63    * we request Windows to process `action`.  At the time of writing, Windows
  64    * recognizes the following actions:
  65    *
  66    * - `action="dismiss"` dismisses the alert entirely.
  67    * - `action="snooze"` snoozes the alert, generally making it disappear before
  68    *   reappearing a Windows-determined amount of time later.
  69    *
  70    * On non-Windows, this field is ignored.
  71    */
  72   readonly attribute boolean windowsSystemActivationType;
  73
  74   /**
  75    * On Windows, chrome-privileged notifications -- i.e., those with a
  76    * non-actionable principal -- can have action-specific `opaqueRelaunchData`.
  77    * This data will be provided to the application at relaunch and can trigger
  78    * specific actions.
  79    *
  80    * On non-Windows, this field is ignored.
  81    */
  82   readonly attribute AString opaqueRelaunchData;
  83 };
  84
  85 [scriptable, uuid(cf2e4cb6-4b8f-4eca-aea9-d51a8f9f7a50)]
  86 interface nsIAlertNotification : nsISupports
  87 {
  88   /** Initializes an alert notification. */
  89   void init([optional] in AString aName,
  90             [optional] in AString aImageURL,
  91             [optional] in AString aTitle,
  92             [optional] in AString aText,
  93             [optional] in boolean aTextClickable,
  94             [optional] in AString aCookie,
  95             [optional] in AString aDir,
  96             [optional] in AString aLang,
  97             [optional] in AString aData,
  98             [optional] in nsIPrincipal aPrincipal,
  99             [optional] in boolean aInPrivateBrowsing,
 100             [optional] in boolean aRequireInteraction,
 101             [optional] in boolean aSilent,
 102             [optional] in Array<uint32_t> aVibrate);
 103
 104   /**
 105    * The name of the notification. On Windows and Android, the name is hashed
 106    * and used as a notification ID. Notifications will replace previous
 107    * notifications with the same name.
 108    */
 109   readonly attribute AString name;
 110
 111   /**
 112    * A URL identifying the image to put in the alert. The OS X backend limits
 113    * the amount of time it will wait for the image to load to six seconds. After
 114    * that time, the alert will show without an image.
 115    */
 116   readonly attribute AString imageURL;
 117
 118   /** The title for the alert. */
 119   readonly attribute AString title;
 120
 121   /** The contents of the alert. */
 122   readonly attribute AString text;
 123
 124   /**
 125    * Controls the click behavior. If true, the alert listener will be notified
 126    * when the user clicks on the alert.
 127    */
 128   readonly attribute boolean textClickable;
 129
 130   /**
 131    * An opaque cookie that will be passed to the alert listener for each
 132    * callback.
 133    */
 134   readonly attribute AString cookie;
 135
 136   /**
 137    * Bidi override for the title and contents. Valid values are "auto", "ltr",
 138    * or "rtl". Ignored if the backend doesn't support localization.
 139    */
 140   readonly attribute AString dir;
 141
 142   /**
 143    * Language of the title and text. Ignored if the backend doesn't support
 144    * localization.
 145    */
 146   readonly attribute AString lang;
 147
 148   /**
 149    * A Base64-encoded structured clone buffer containing data associated with
 150    * this alert. Only used for web notifications. Chrome callers should use a
 151    * cookie instead.
 152    */
 153   readonly attribute AString data;
 154
 155   /**
 156    * The principal of the page that created the alert. Used for IPC security
 157    * checks, and to determine whether the alert is actionable.
 158    */
 159   readonly attribute nsIPrincipal principal;
 160
 161   /**
 162    * The URI of the page that created the alert. |null| if the alert is not
 163    * actionable.
 164    */
 165   readonly attribute nsIURI URI;
 166
 167   /**
 168    * Controls the image loading behavior. If true, the image request will be
 169    * loaded anonymously (without cookies or authorization tokens).
 170    */
 171   readonly attribute boolean inPrivateBrowsing;
 172
 173   /**
 174    * Indicates that the notification should remain readily available until
 175    * the user activates or dismisses the notification.
 176    */
 177   readonly attribute boolean requireInteraction;
 178
 179   /**
 180    * When set, indicates that no sounds or vibrations should be made.
 181    */
 182   readonly attribute boolean silent;
 183
 184   /**
 185    * A vibration pattern to run with the display of the notification. A
 186    * vibration pattern can be an array with as few as one member. The values
 187    * are times in milliseconds where the even indices (0, 2, 4, etc.) indicate
 188    * how long to vibrate and the odd indices indicate how long to pause. For
 189    * example, [300, 100, 400] would vibrate 300ms, pause 100ms, then vibrate
 190    * 400ms.
 191    */
 192   readonly attribute Array<uint32_t> vibrate;
 193
 194   /**
 195    * Actions available for users to choose from for interacting with
 196    * the notification.
 197    *
 198    * Implemented only for the system backend on Windows.
 199    */
 200   attribute Array<nsIAlertAction> actions;
 201
 202   /**
 203    * Indicates whether this alert should show the source string and action
 204    * buttons. False for system alerts (which can omit the principal), or
 205    * expanded, system, and null principals.
 206    */
 207   readonly attribute boolean actionable;
 208
 209   /**
 210    * The host and port of the originating page, or an empty string if the alert
 211    * is not actionable.
 212    */
 213   readonly attribute AString source;
 214
 215   /**
 216    * On Windows, chrome-privileged notifications -- i.e., those with a
 217    * non-actionable principal -- can have `opaqueRelaunchData`.  This data will
 218    * be provided to the application at relaunch and can trigger specific
 219    * actions.
 220    *
 221    * On non-Windows, this field is ignored.
 222    */
 223   attribute AString opaqueRelaunchData;
 224
 225   /**
 226    * Loads the image associated with this alert.
 227    *
 228    * @param aTimeout  The number of milliseconds to wait before cancelling the
 229    *                  image request. If zero, there is no timeout.
 230    * @param aListener An |nsIAlertNotificationImageListener| implementation,
 231    *                  notified when the image loads. The listener is kept alive
 232    *                  until the request completes.
 233    * @param aUserData An opaque parameter passed to the listener's methods.
 234    *                  Not used by the libnotify backend, but the OS X backend
 235    *                  passes the pending notification.
 236    */
 237   nsICancelable loadImage(in unsigned long aTimeout,
 238                           in nsIAlertNotificationImageListener aListener,
 239                           [optional] in nsISupports aUserData);
 240 };
 241
 242 [scriptable, uuid(f7a36392-d98b-4141-a7d7-4e46642684e3)]
 243 interface nsIAlertsService : nsISupports
 244 {
 245   void showPersistentNotification(in AString aPersistentData,
 246                                   in nsIAlertNotification aAlert,
 247                                   [optional] in nsIObserver aAlertListener);
 248
 249   void showAlert(in nsIAlertNotification aAlert,
 250                  [optional] in nsIObserver aAlertListener);
 251   /**
 252    * Initializes and shows an |nsIAlertNotification| with the given parameters.
 253    *
 254    * @param aAlertListener Used for callbacks. May be null if the caller
 255    *                       doesn't care about callbacks.
 256    * @see nsIAlertNotification for descriptions of all other parameters.
 257    * @throws NS_ERROR_NOT_AVAILABLE If the notification cannot be displayed.
 258    *
 259    * The following arguments will be passed to the alertListener's observe()
 260    * method:
 261    *   subject - null
 262    *   topic   - "alertfinished" when the alert goes away
 263    *             "alertdisablecallback" when alerts should be disabled for the principal
 264    *             "alertsettingscallback" when alert settings should be opened
 265    *             "alertclickcallback" when the text is clicked
 266    *             "alertshow" when the alert is shown
 267    *   data    - the value of the cookie parameter passed to showAlertNotification.
 268    *
 269    * @note Depending on current circumstances (if the user's in a fullscreen
 270    *       application, for instance), the alert might not be displayed at all.
 271    *       In that case, if an alert listener is passed in it will receive the
 272    *       "alertfinished" notification immediately.
 273    */
 274   void showAlertNotification(in AString aImageURL,
 275                              in AString aTitle,
 276                              in AString aText,
 277                              [optional] in boolean aTextClickable,
 278                              [optional] in AString aCookie,
 279                              [optional] in nsIObserver aAlertListener,
 280                              [optional] in AString aName,
 281                              [optional] in AString aDir,
 282                              [optional] in AString aLang,
 283                              [optional] in AString aData,
 284                              [optional] in nsIPrincipal aPrincipal,
 285                              [optional] in boolean aInPrivateBrowsing,
 286                              [optional] in boolean aRequireInteraction);
 287
 288   /**
 289    * Close alerts created by the service.
 290    *
 291    * @param aName          The name of the notification to close. If no name
 292    *                       is provided then only a notification created with
 293    *                       no name (if any) will be closed.
 294    * @param aContextClosed The notification was implicitly closed, e.g. by tab
 295    *                       or window closure. This is necessary to track as some
 296    *                       platforms intentionally leave the notification visible
 297    *                       unless explicitly closed, e.g. by notification.close().
 298    */
 299   void closeAlert([optional] in AString aName, [optional] in boolean aContextClosed);
 300
 301 };
 302
 303 [scriptable, uuid(c5d63e3a-259d-45a8-b964-8377967cb4d2)]
 304 interface nsIAlertsDoNotDisturb : nsISupports
 305 {
 306   /**
 307    * Toggles a manual Do Not Disturb mode for the service to reduce the amount
 308    * of disruption that alerts cause the user.
 309    * This may mean only displaying them in a notification tray/center or not
 310    * displaying them at all. If a system backend already supports a similar
 311    * feature controlled by the user, enabling this may not have any impact on
 312    * code to show an alert. e.g. on OS X, the system will take care not
 313    * disrupting a user if we simply create a notification like usual.
 314    */
 315   attribute bool manualDoNotDisturb;
 316
 317   /**
 318    * Toggles a mode for the service to suppress all notifications from
 319    * being dispatched when sharing the screen via the getMediaDisplay
 320    * API.
 321    */
 322   attribute bool suppressForScreenSharing;
 323 };
 324
 325 [scriptable, uuid(fc6d7f0a-0cf6-4268-8c71-ab640842b9b1)]
 326 interface nsIAlertsIconData : nsISupports
 327 {
 328   /**
 329    * Shows an alert with an icon. Web notifications use the favicon of the
 330    * page that created the alert. If the favicon is not in the Places database,
 331    * |aIconSize| will be zero.
 332   */
 333   void showAlertWithIconData(in nsIAlertNotification aAlert,
 334                              in nsIObserver aAlertListener,
 335                              in uint32_t aIconSize,
 336                              [const, array, size_is(aIconSize)] in uint8_t
 337                                                                 aIconData);
 338 };
 339
 340 [scriptable, uuid(f3c82915-bf60-41ea-91ce-6c46b22e381a)]
 341 interface nsIAlertsIconURI : nsISupports
 342 {
 343   /**
 344    * Shows an alert with an icon URI. Web notifications use |moz-anno:|
 345    * URIs to reference favicons from Places. If the page doesn't have a
 346    * favicon, |aIconURI| will be |null|.
 347    */
 348   void showAlertWithIconURI(in nsIAlertNotification aAlert,
 349                             [optional] in nsIObserver aAlertListener,
 350                             [optional] in nsIURI aIconURI);
 351 };