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     // Sender's avatar, app icon, or a thumbnail for image notifications.
  57     // <em>Required for $(ref:notifications.create)</em> method.
  58     DOMString? iconUrl;
  59     [nodoc] NotificationBitmap? iconBitmap;
  60
  61     // Title of the notification (e.g. sender name for email).
  62     // <em>Required for $(ref:notifications.create)</em> method.
  63     DOMString? title;
  64
  65     // Main notification content.
  66     // <em>Required for $(ref:notifications.create)</em> method.
  67     DOMString? message;
  68
  69     // Alternate notification content with a lower-weight font.
  70     DOMString? contextMessage;
  71
  72     // Priority ranges from -2 to 2. -2 is lowest priority. 2 is highest. Zero
  73     // is default.
  74     long? priority;
  75
  76     // A timestamp associated with the notification, in milliseconds past the
  77     // epoch (e.g. <code>Date.now() + n</code>).
  78     double? eventTime;
  79
  80     // Text and icons for up to two notification action buttons.
  81     NotificationButton[]? buttons;
  82
  83     // Secondary notification content.
  84     [nodoc] DOMString? expandedMessage;
  85
  86     // Image thumbnail for image-type notifications.
  87     DOMString? imageUrl;
  88     [nodoc] NotificationBitmap? imageBitmap;
  89
  90     // Items for multi-item notifications.
  91     NotificationItem[]? items;
  92
  93     // Current progress ranges from 0 to 100.
  94     long? progress;
  95
  96     // Whether to show UI indicating that the app will visibly respond to
  97     // clicks on the body of a notification.
  98     boolean? isClickable;
  99   };
 100
 101   callback CreateCallback = void (DOMString notificationId);
 102
 103   callback UpdateCallback = void (boolean wasUpdated);
 104
 105   callback ClearCallback = void (boolean wasCleared);
 106
 107   callback GetAllCallback = void (object notifications);
 108
 109   callback PermissionLevelCallback = void (PermissionLevel level);
 110
 111   interface Functions {
 112     // Creates and displays a notification.
 113     // |notificationId|: Identifier of the notification. If it is empty, this
 114     // method generates an id. If it matches an existing notification, this
 115     // method first clears that notification before proceeding with the create
 116     // operation.
 117     // |options|: Contents of the notification.
 118     // |callback|: Returns the notification id (either supplied or generated)
 119     // that represents the created notification.
 120     static void create(DOMString notificationId,
 121                        NotificationOptions options,
 122                        CreateCallback callback);
 123
 124     // Updates an existing notification.
 125     // |notificationId|: The id of the notification to be updated. This is
 126     // returned by $(ref:notifications.create) method.
 127     // |options|: Contents of the notification to update to.
 128     // |callback|: Called to indicate whether a matching notification existed.
 129     static void update(DOMString notificationId,
 130                        NotificationOptions options,
 131                        UpdateCallback callback);
 132
 133     // Clears the specified notification.
 134     // |notificationId|: The id of the notification to be cleared. This is
 135     // returned by $(ref:notifications.create) method.
 136     // |callback|: Called to indicate whether a matching notification existed.
 137     static void clear(DOMString notificationId, ClearCallback callback);
 138
 139     // Retrieves all the notifications.
 140     // |callback|: Returns the set of notification_ids currently in the system.
 141     static void getAll(GetAllCallback callback);
 142
 143     // Retrieves whether the user has enabled notifications from this app
 144     // or extension.
 145     // |callback|: Returns the current permission level.
 146     static void getPermissionLevel(PermissionLevelCallback callback);
 147   };
 148
 149   interface Events {
 150     // The notification closed, either by the system or by user action.
 151     static void onClosed(DOMString notificationId, boolean byUser);
 152
 153     // The user clicked in a non-button area of the notification.
 154     static void onClicked(DOMString notificationId);
 155
 156     // The user pressed a button in the notification.
 157     static void onButtonClicked(DOMString notificationId, long buttonIndex);
 158
 159     // The user changes the permission level.
 160     static void onPermissionLevelChanged(PermissionLevel level);
 161
 162     // The user clicked on a link for the app's notification settings.
 163     static void onShowSettings();
 164   };
 165
 166 };