Notification Provider API

chrome/common/extensions/api/notification_provider.idl

+// 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 get notifications.

[not at google - send to devlin, 2014/07/28 21:32:39]

This description is what is shown in the generated documentation. It could be
more helpful; "get notifications" could equally apply to the notifications API.

[liyanhou, 2014/07/29 18:26:53]

Done.

+namespace notificationProvider {
+
+  // TODO(liyanhou): Refactoer this to using notifications.PermissionLevel after

[not at google - send to devlin, 2014/07/28 21:32:39]

Refactor

also note that this will become the documentation for the
NotifierPermissionLevel so you might want to actually go:

// TODO(liyanhou): Use notifications.PermissionLevel everywhere and delete this
type. See http://crbug.com/etc.

// <some documentation about the permission level>

[liyanhou, 2014/07/29 18:26:54]

Done.

+  // hear back about how to reference enum from another IDL in a dictionary and
+  // keep the namespace right. 
+  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);

[not at google - send to devlin, 2014/07/28 21:32:39]

could you line-break after the =?

[liyanhou, 2014/07/29 18:26:54]

Done.

+
+  callback NotifyOnShowSettingsCallback = void (boolean notifierExists);
+
+  callback GetAllNotifiersCallback = void (object 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 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/28 21:32:39]

it would be good to either provide a method to get the details of a specific
notifier, or pass in the full Notifier rather than its ID. or both.

[liyanhou, 2014/07/29 18:26:54]

Done.

+                          DOMString notificaitonId, 

[not at google - send to devlin, 2014/07/28 21:32:39]

notificationId

[liyanhou, 2014/07/29 18:26:53]

Done.

+                          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);
+  };
+};