Update notifications API after review.

chrome/common/extensions/api/experimental_notification.idl

 // 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.
 
 [nodoc] namespace experimental.notification {
+  enum TemplateType {
+    // icon, title, message
+    simple,
+
+    // icon, title, message, expandedMessage, up to two buttons
+    basic,
+
+    // icon, title, message, expandedMessage, image, up to two buttons
+    image,
+
+    // icon, title, message, items, up to two buttons
+    list
+  };
+
   dictionary NotificationItem {
     // Title of one item of a list notification.
     DOMString title;
 
     // Additional details about this item.
     DOMString message;
   };
 
+  dictionary NotificationButton {
+    DOMString title;
+    DOMString? iconUrl;
+  };
+
   dictionary NotificationOptions {
     // Which type of notification to display.
-    //
-    // simple: icon, title, message
-    // basic: our MVP, with two buttons, expanded text, etc. TEMPORARY!
-    DOMString type;
+    TemplateType templateType;
 
     // Sender's avatar, app icon, or a thumbnail for image notifications.
+    // TODO(miket): see browserAction.setIcon() for a better approach.
     DOMString iconUrl;
 
     // Title of the notification (e.g. sender name for email).
     DOMString title;
 
     // Main notification content.
     DOMString message;
 
     // Priority ranges from -2 to 2. -2 is lowest priority. 2 is highest. Zero
     // is default.
     long? priority;
 
-    // A timestamp associated with the notification. An example is
-    // "Tue, 15 Nov 1994 12:45:26 GMT". Note that RFC822 doesn't specify the
-    // timezone label "UTC." To specify UTC, use "GMT" instead.
-    DOMString? timestamp;
+    // A timestamp associated with the notification, in W3C ISO 8601 format
+    // (http://www.w3.org/TR/NOTE-datetime) or ECMAScript date time string
+    // format (http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15)
+    // as generated by date.toISOString(), for example "1994-11-15T12:45:26Z."
+    DOMString? eventTime;
 
     // Smaller version of the icon.
     DOMString? secondIconUrl;
 
-    // A number, controlled entirely by the caller, that is intended to
-    // summarize the number of outstanding notifications. TODO(miket) what does
-    // that mean?
-    long? unreadCount;
-
-    // Text and icon of the first button in the notification.
-    DOMString? buttonOneTitle;
-    DOMString? buttonOneIconUrl;
-
-    // Text and icon of the second button in the notification.
-    DOMString? buttonTwoTitle;
-    DOMString? buttonTwoIconUrl;
+    // Text and icons of notification action buttons.
+    NotificationButton[]? buttons;
 
     // Secondary notification content.
     DOMString? expandedMessage;
 
-    // Image thumbnail for image-type notifications
+    // Image thumbnail for image-type notifications.
     DOMString? imageUrl;
 
     // Items for multi-item notifications.
     NotificationItem[]? items;
   };
 
   callback CreateCallback = void (DOMString notificationId);
 
   callback UpdateCallback = void (boolean wasUpdated);
 
   callback DeleteCallback = void (boolean wasDeleted);
 
   interface Functions {
     // Creates and displays a notification having the contents in |options|,
     // identified by the id |notificationId|. If |notificationId| is empty,
-    // |create| generates an id. |callback| returns the notification id (either
-    // supplied or generated) that represents the created notification.
+    // |create| generates an id. If |notificationId| matches an existing
+    // notification, |create| first deletes that notification before proceeding
+    // with the create operation. |callback| returns the notification id
+    // (either supplied or generated) that represents the created notification.
     static void create(DOMString notificationId,
                        NotificationOptions options,
                        CreateCallback callback);
 
     // Updates an existing notification having the id |notificationId| and the
     // options |options|. |callback| indicates whether a matching notification
     // existed.
     static void update(DOMString notificationId,
                        NotificationOptions options,
                        UpdateCallback callback);
 
     // Given a |notificationId| returned by the |create| method, deletes the
     // corresponding notification. |callback| indicates whether a matching
     // notification existed.
     static void delete(DOMString notificationId, DeleteCallback callback);
   };
 
   interface Events {
-    // The system displayed the notification.
+    // The system displayed the notification. Not all created notifications are
+    // displayed; for example, a low-priority notification might simply appear
+    // in the message center without interrupting the user.

[dharcourt, 2013/02/06 21:34:20]

I'm confused... will onDisplayed() be called: 1) every time a particular
notification is show to a user; 2) the first time it's shown; or 3) when the
notification is received in the notification center, even if there is no alert
for it? I think this comment could be clarified to better communicate what the
expected behavior is.

FWIW, onDisplayed() currently get called for low-priority notification, even
when the notification center is not opened. I'm guessing from this comment that
this is a bug... right?

     static void onDisplayed(DOMString notificationId);
 
-    // An error occurred. TODO(miket): which errors can happen, and when? In
-    // which form (string, ID) should we describe the error?
-    static void onError(DOMString notificationId);
-
     // 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);
   };
 
 };