Notification Provider API

chrome/common/extensions/api/notification_provider.idl

Index: chrome/common/extensions/api/notification_provider.idl
diff --git a/chrome/common/extensions/api/notification_provider.idl b/chrome/common/extensions/api/notification_provider.idl
new file mode 100644
index 0000000000000000000000000000000000000000..23a3dd8f06bd3e9a36a5bf80504f88d47f73fc1c
--- /dev/null
+++ b/chrome/common/extensions/api/notification_provider.idl
@@ -0,0 +1,132 @@
+// Copyright (c) 2014 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.notificationProvider</code> API to intercept
+// notifications that would otherwise go into the Chrome Notification Center,
+// get notifiers' information, and inform notifiers about users' actions on the
+// notifications.
+namespace notificationProvider {
+
+  // TODO(liyanhou): Use notifications.PermissionLevel everywhere and delete
+  // this type. See http://crbug.com/398266.
+
+  // whether notifications from this notifier is permitted or blocked.
+  enum NotifierPermissionLevel {
+    // User has elected to show notifications from the notifier.
+    // This is the default at install time.
+    granted,
+
+    // User has elected not to show notifications from the notifier.
+    denied
+  };
+
+  dictionary Notifier {
+    // Name of the notifier.
+    DOMString name;
+
+    // Icon of the notifier.
+    notifications.NotificationBitmap notifierIcon;
+
+    // Permission level of the notifier.
+    NotifierPermissionLevel permissionLevel;
+
+    // If a notifier has advanced settings.
+    boolean hasSettings;
+  };
+
+  callback NotifyOnClearedCallback = void (boolean wasCleared);
+
+  callback NotifyOnClickedCallback = void (boolean matchExists);
+
+  callback NotifyOnButtonClickedCallback = void (boolean matchExists);
+
+  callback NotifyOnPermissionLevelChangedCallback = 
+                                          void (boolean notifierExists);
+
+  callback NotifyOnShowSettingsCallback = void (boolean notifierExists);
+
+  callback GetNotifierCallback = void (Notifier notifier);
+
+  callback GetAllNotifiersCallback = void (Notifier[] notifiers);
+
+  interface Functions {
+    // Inform the notifier that the user cleared a notification sent from that
+    // notifier.
+    // |notifierId|: The id of the notifier that sent the notification.
+    // |notificationId|: The id of the notification that was closed.
+    // |callback|: Called to indicate whether a matching notification existed.
+    static void notifyOnCleared(DOMString notifierId,
+                                DOMString notificationId,
+                                NotifyOnClearedCallback callback);
+
+    // Inform the notifier that the user clicked in a non-button area of a
+    // notification sent from that notifier.
+    // |notifierId|: The id of the notifier that sent the notification.
+    // |notificationId|: The id of the notification that was clicked on.
+    // |callback|: Called to indicate whether a matching notification existed.
+    static void notifyOnClicked(DOMString notifierId,
+                                DOMString notificationId,
+                                NotifyOnClickedCallback callback);
+
+    // Inform the notifier that the user pressed a button in the notification
+    // sent from that notifier.
+    // |notifierId|: The id of the notifier that sent the notification.
+    // |notificationId|: The id of the notification that was clicked on its
+    // button.
+    // |buttonIndex|: The index of the button that was clicked.
+    // |callback|: Called to indicate whether a matching notification existed.
+    static void notifyOnButtonClicked(DOMString notifierId,
+                                      DOMString notificationId,
+                                      long buttonIndex,
+                                      NotifyOnButtonClickedCallback callback);
+
+    // Inform the notifier that the user changed the permission level of that
+    // notifier.
+    // |notifierId|: The id of the notifier that sent the notification.
+    // |level|: The perission level of the notifier
+    // |callback|: Called to indicate whether the notifier existed.
+    static void notifyOnPermissionLevelChanged(
+                              DOMString notifierId,
+                              NotifierPermissionLevel level,
+                              NotifyOnPermissionLevelChangedCallback callback);
+
+    // Inform the notifier that the user chose to see advanced settings of that
+    // notifier.
+    // |notifierId|: The id of the notifier that sent the notification.
+    // |callback|: Called to indicate whether a matching notifier existed.
+    static void notifyOnShowSettings(DOMString notifierId,
+                                     NotifyOnShowSettingsCallback callback);
+
+    // To get a notifier from it's notifier ID.
+    // |callback|: Returns the notifier object of the given ID.
+    static void getNotifier(GetNotifierCallback callback);
+
+    // To get all the notifiers that could send notifications.
+    // |callback|: Returns the set of notifiers currently in the system.
+    static void getAllNotifiers(GetAllNotifiersCallback callback);
+  };
+
+  interface Events {
+    // A new notification is created.
+    // |notifierId|: The id of the notifier that sent the new notification.
+    // |notificationId|: The id of the newly created notification.
+    // |options|: The content of the notification: type, title, message etc.
+    static void onCreated(DOMString notifierId, 

[not at google - send to devlin, 2014/07/29 20:09:38]

[following on from previous comment]

what's the expected behaviour here? if the notificationProvider is just going to
turn around and request the Notifier given |notifierId| then you might as well
save the round trip, and annoyance of needing to do that, and pass it in right
away.

if not, then this is fine I suppose. the only downside would be the expense of
serializing notifications.NotificationBitmap every event - but events should be
pretty rare.

[liyanhou, 2014/07/30 17:19:25]

The expected behavior is to store notifier ID, notification ID, and data of the
notification together, then when a user clicks on or close a notification, the
app/extension can use the notifier ID and notification ID to notify the
notifier.

The intent is that Notifier information is more for displaying the notifiers in
the settings page, for users to block and unblock notifications from certain
notifiers. I don't know if apps would want information about the notifier every
time they get a notification. If so, I suppose they can keep a mapping of
notifier IDs to Notifier information. In that case, they may also keep converted
images in the mapping, to avoid converting bitmaps of the same notifiers.

That's just my thought on the scenarios, feel free if you think of use cases
that apps would want to get full Notifier information when it gets a
notification.

[not at google - send to devlin, 2014/07/30 19:24:37]

Perhaps when onCreated() is called the provider will want to show the notifier's
name along with the notification?

but given this event is async anyway it's pretty easy for the app to turn around
and get the name if it wants, so this is fine.

+                          DOMString notificationId, 
+                          notifications.NotificationOptions options);
+
+    // A notification is updated by the notifier.
+    // |notifierId|: The id of the notifier that sent the updated notification.
+    // |notificationId|: The id of the updated notification.
+    // |options|: The content of the notification: type, title, message etc.
+    static void onUpdated(DOMString notifierId,
+                          DOMString notificationId,
+                          notifications.NotificationOptions options);
+
+    // A notification is cleared by the notifier.
+    // |notifierId|: The id of the notifier that cleared the notification.
+    // |notificationId|: The id of the cleared notification.
+    static void onCleared(DOMString notifierId, DOMString notificationId);
+  };
+};