blob: 3100d6ac410bb77fafb9229af853e08b423efe40 [file] [log] [blame]
// Copyright (c) 2013 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Use the <code>chrome.notifications</code> API to create rich notifications
// using templates and show these notifications to users in the system tray.
namespace notifications {
[noinline_doc] enum TemplateType {
// icon, title, message, expandedMessage, up to two buttons
basic,
// icon, title, message, expandedMessage, image, up to two buttons
[deprecated="The image is not visible for Mac OS X users."]
image,
// icon, title, message, items, up to two buttons. Users on Mac OS X only
// see the first item.
list,
// icon, title, message, progress, up to two buttons
progress
};
enum PermissionLevel {
// User has elected to show notifications from the app or extension.
// This is the default at install time.
granted,
// User has elected not to show notifications from the app or extension.
denied
};
dictionary NotificationItem {
// Title of one item of a list notification.
DOMString title;
// Additional details about this item.
DOMString message;
};
[nodoc] dictionary NotificationBitmap {
long width;
long height;
ArrayBuffer? data;
};
dictionary NotificationButton {
DOMString title;
[deprecated="Button icons not visible for Mac OS X users."]
DOMString? iconUrl;
[nodoc] NotificationBitmap? iconBitmap;
};
dictionary NotificationOptions {
// Which type of notification to display.
// <em>Required for $(ref:notifications.create)</em> method.
TemplateType? type;
// A URL to the sender's avatar, app icon, or a thumbnail for image
// notifications.
//
// URLs can be a data URL, a blob URL, or a URL relative to a resource
// within this extension's .crx file
// <em>Required for $(ref:notifications.create)</em> method.
DOMString? iconUrl;
[nodoc] NotificationBitmap? iconBitmap;
// A URL to the app icon mask. URLs have the same restrictions as
// $(ref:notifications.NotificationOptions.iconUrl iconUrl).
//
// The app icon mask should be in alpha channel, as only the alpha channel
// of the image will be considered.
[deprecated="The app icon mask is not visible for Mac OS X users."]
DOMString? appIconMaskUrl;
[nodoc] NotificationBitmap? appIconMaskBitmap;
// Title of the notification (e.g. sender name for email).
// <em>Required for $(ref:notifications.create)</em> method.
DOMString? title;
// Main notification content.
// <em>Required for $(ref:notifications.create)</em> method.
DOMString? message;
// Alternate notification content with a lower-weight font.
DOMString? contextMessage;
// Priority ranges from -2 to 2. -2 is lowest priority. 2 is highest. Zero
// is default. On platforms that don't support a notification center
// (Windows, Linux & Mac), -2 and -1 result in an error as notifications
// with those priorities will not be shown at all.
long? priority;
// A timestamp associated with the notification, in milliseconds past the
// epoch (e.g. <code>Date.now() + n</code>).
double? eventTime;
// Text and icons for up to two notification action buttons.
NotificationButton[]? buttons;
// Secondary notification content.
[nodoc] DOMString? expandedMessage;
// A URL to the image thumbnail for image-type notifications.
// URLs have the same restrictions as
// $(ref:notifications.NotificationOptions.iconUrl iconUrl).
[deprecated="The image is not visible for Mac OS X users."]
DOMString? imageUrl;
[nodoc] NotificationBitmap? imageBitmap;
// Items for multi-item notifications. Users on Mac OS X only see the first
// item.
NotificationItem[]? items;
// Current progress ranges from 0 to 100.
long? progress;
[deprecated="This UI hint is ignored as of Chrome 67"]
boolean? isClickable;
// Indicates that the notification should remain visible on screen until the
// user activates or dismisses the notification. This defaults to false.
boolean? requireInteraction;
// Indicates that no sounds or vibrations should be made when the
// notification is being shown. This defaults to false.
boolean? silent;
};
callback CreateCallback = void (DOMString notificationId);
callback UpdateCallback = void (boolean wasUpdated);
callback ClearCallback = void (boolean wasCleared);
callback GetAllCallback = void (object notifications);
callback PermissionLevelCallback = void (PermissionLevel level);
interface Functions {
// Creates and displays a notification.
// |notificationId|: Identifier of the notification. If not set or empty, an
// ID will automatically be generated. If it matches an existing
// notification, this method first clears that notification before
// proceeding with the create operation. The identifier may not be longer
// than 500 characters.
//
// The <code>notificationId</code> parameter is required before Chrome 42.
// |options|: Contents of the notification.
// |callback|: Returns the notification id (either supplied or generated)
// that represents the created notification.
//
// The callback is required before Chrome 42.
static void create(optional DOMString notificationId,
NotificationOptions options,
optional CreateCallback callback);
// Updates an existing notification.
// |notificationId|: The id of the notification to be updated. This is
// returned by $(ref:notifications.create) method.
// |options|: Contents of the notification to update to.
// |callback|: Called to indicate whether a matching notification existed.
//
// The callback is required before Chrome 42.
static void update(DOMString notificationId,
NotificationOptions options,
optional UpdateCallback callback);
// Clears the specified notification.
// |notificationId|: The id of the notification to be cleared. This is
// returned by $(ref:notifications.create) method.
// |callback|: Called to indicate whether a matching notification existed.
//
// The callback is required before Chrome 42.
static void clear(DOMString notificationId,
optional ClearCallback callback);
// Retrieves all the notifications.
// |callback|: Returns the set of notification_ids currently in the system.
static void getAll(GetAllCallback callback);
// Retrieves whether the user has enabled notifications from this app
// or extension.
// |callback|: Returns the current permission level.
static void getPermissionLevel(PermissionLevelCallback callback);
};
interface Events {
// The notification closed, either by the system or by user action.
static void onClosed(DOMString notificationId, boolean byUser);
// The user clicked in a non-button area of the notification.
static void onClicked(DOMString notificationId);
// The user pressed a button in the notification.
static void onButtonClicked(DOMString notificationId, long buttonIndex);
// The user changes the permission level. As of Chrome 47, only ChromeOS
// has UI that dispatches this event.
static void onPermissionLevelChanged(PermissionLevel level);
// The user clicked on a link for the app's notification settings. As of
// Chrome 47, only ChromeOS has UI that dispatches this event.
// As of Chrome 65, that UI has been removed from ChromeOS, too.
[deprecated="Custom notification settings button is no longer supported."]
static void onShowSettings();
};
};