chrome/common/extensions/api/notifications.idl

   1 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>chrome.notifications</code> API to create rich notifications
   6 // using templates and show these notifications to users in the system tray.
   7 namespace notifications {
   8   [noinline_doc] enum TemplateType {
   9     // icon, title, message, expandedMessage, up to two buttons
  10     basic,
  11
  12     // icon, title, message, expandedMessage, image, up to two buttons
  13     image,
  14
  15     // icon, title, message, items, up to two buttons
  16     list,
  17
  18     // icon, title, message, progress, up to two buttons
  19     progress
  20   };
  21
  22   enum PermissionLevel {
  23     // User has elected to show notifications from the app or extension.
  24     // This is the default at install time.
  25     granted,
  26
  27     // User has elected not to show notifications from the app or extension.
  28     denied
  29   };
  30
  31   dictionary NotificationItem {
  32     // Title of one item of a list notification.
  33     DOMString title;
  34
  35     // Additional details about this item.
  36     DOMString message;
  37   };
  38
  39   [nodoc] dictionary NotificationBitmap {
  40     long width;
  41     long height;
  42     ArrayBuffer? data;
  43   };
  44
  45   dictionary NotificationButton {
  46     DOMString title;
  47     DOMString? iconUrl;
  48     [nodoc] NotificationBitmap? iconBitmap;
  49   };
  50
  51   dictionary NotificationOptions {
  52     // Which type of notification to display.
  53     // <em>Required for $(ref:notifications.create)</em> method.
  54     TemplateType? type;
  55
  56     // A URL to the sender's avatar, app icon, or a thumbnail for image
  57     // notifications.
  58     //
  59     // URLs can be a data URL, a blob URL, or a URL relative to a resource
  60     // within this extension's .crx file
  61     // <em>Required for $(ref:notifications.create)</em> method.
  62     DOMString? iconUrl;
  63     [nodoc] NotificationBitmap? iconBitmap;
  64
  65     // A URL to the app icon mask. URLs have the same restrictions as
  66     // $(ref:notifications.NotificationOptions.iconUrl iconUrl).
  67     //
  68     // The app icon mask should be in alpha channel, as only the alpha channel
  69     // of the image will be considered.
  70     DOMString? appIconMaskUrl;
  71     [nodoc] NotificationBitmap? appIconMaskBitmap;
  72
  73     // Title of the notification (e.g. sender name for email).
  74     // <em>Required for $(ref:notifications.create)</em> method.
  75     DOMString? title;
  76
  77     // Main notification content.
  78     // <em>Required for $(ref:notifications.create)</em> method.
  79     DOMString? message;
  80
  81     // Alternate notification content with a lower-weight font.
  82     DOMString? contextMessage;
  83
  84     // Priority ranges from -2 to 2. -2 is lowest priority. 2 is highest. Zero
  85     // is default.
  86     long? priority;
  87
  88     // A timestamp associated with the notification, in milliseconds past the
  89     // epoch (e.g. <code>Date.now() + n</code>).
  90     double? eventTime;
  91
  92     // Text and icons for up to two notification action buttons.
  93     NotificationButton[]? buttons;
  94
  95     // Secondary notification content.
  96     [nodoc] DOMString? expandedMessage;
  97
  98     // A URL to the image thumbnail for image-type notifications.
  99     // URLs have the same restrictions as
 100     // $(ref:notifications.NotificationOptions.iconUrl iconUrl).
 101     DOMString? imageUrl;
 102     [nodoc] NotificationBitmap? imageBitmap;
 103
 104     // Items for multi-item notifications.
 105     NotificationItem[]? items;
 106
 107     // Current progress ranges from 0 to 100.
 108     long? progress;
 109
 110     // Whether to show UI indicating that the app will visibly respond to
 111     // clicks on the body of a notification.
 112     boolean? isClickable;
 113   };
 114
 115   callback CreateCallback = void (DOMString notificationId);
 116
 117   callback UpdateCallback = void (boolean wasUpdated);
 118
 119   callback ClearCallback = void (boolean wasCleared);
 120
 121   callback GetAllCallback = void (object notifications);
 122
 123   callback PermissionLevelCallback = void (PermissionLevel level);
 124
 125   interface Functions {
 126     // Creates and displays a notification.
 127     // |notificationId|: Identifier of the notification. If not set or empty, an
 128     // ID will automatically be generated. If it matches an existing
 129     // notification, this method first clears that notification before
 130     // proceeding with the create operation.
 131     //
 132     // The <code>notificationId</code> parameter is required before Chrome 42.
 133     // |options|: Contents of the notification.
 134     // |callback|: Returns the notification id (either supplied or generated)
 135     // that represents the created notification.
 136     //
 137     // The callback is required before Chrome 42.
 138     static void create(optional DOMString notificationId,
 139                        NotificationOptions options,
 140                        optional CreateCallback callback);
 141
 142     // Updates an existing notification.
 143     // |notificationId|: The id of the notification to be updated. This is
 144     // returned by $(ref:notifications.create) method.
 145     // |options|: Contents of the notification to update to.
 146     // |callback|: Called to indicate whether a matching notification existed.
 147     //
 148     // The callback is required before Chrome 42.
 149     static void update(DOMString notificationId,
 150                        NotificationOptions options,
 151                        optional UpdateCallback callback);
 152
 153     // Clears the specified notification.
 154     // |notificationId|: The id of the notification to be cleared. This is
 155     // returned by $(ref:notifications.create) method.
 156     // |callback|: Called to indicate whether a matching notification existed.
 157     //
 158     // The callback is required before Chrome 42.
 159     static void clear(DOMString notificationId,
 160                       optional ClearCallback callback);
 161
 162     // Retrieves all the notifications.
 163     // |callback|: Returns the set of notification_ids currently in the system.
 164     static void getAll(GetAllCallback callback);
 165
 166     // Retrieves whether the user has enabled notifications from this app
 167     // or extension.
 168     // |callback|: Returns the current permission level.
 169     static void getPermissionLevel(PermissionLevelCallback callback);
 170   };
 171
 172   interface Events {
 173     // The notification closed, either by the system or by user action.
 174     static void onClosed(DOMString notificationId, boolean byUser);
 175
 176     // The user clicked in a non-button area of the notification.
 177     static void onClicked(DOMString notificationId);
 178
 179     // The user pressed a button in the notification.
 180     static void onButtonClicked(DOMString notificationId, long buttonIndex);
 181
 182     // The user changes the permission level.
 183     static void onPermissionLevelChanged(PermissionLevel level);
 184
 185     // The user clicked on a link for the app's notification settings.
 186     static void onShowSettings();
 187   };
 188
 189 };