Refactor chrome.alarms interface to support absolute alarm deadlines.

chrome/common/extensions/api/alarms.idl

Index: chrome/common/extensions/api/alarms.idl
diff --git a/chrome/common/extensions/api/alarms.idl b/chrome/common/extensions/api/alarms.idl
index cd61d8696c7666faf4e5c7a06985fc1c1e159594..92771b625d9af0a482606416e9038804b04fb916 100644
--- a/chrome/common/extensions/api/alarms.idl
+++ b/chrome/common/extensions/api/alarms.idl
@@ -10,40 +10,57 @@ namespace alarms {
     // Name of this alarm.
     DOMString name;
 
-    // Original length of time in minutes after which the onAlarm event should
-    // fire.
-    // TODO: need minimum=0
-    double delayInMinutes;
+    // Time at which this alarm was scheduled to fire, in milliseconds past the
+    // epoch (e.g. Date.now() + n).  For performance reasons, the alarm may have
+    // been delayed an arbitrary amount beyond this.
+    double scheduledTime;
 
-    // True if the alarm repeatedly fires at regular intervals, false if it
-    // only fires once.
-    boolean repeating;
+    // If not null, the alarm is a repeating alarm and will fire again in
+    // 'periodInMinutes' minutes.
+    double? periodInMinutes;
   };
 
   // TODO(mpcomplete): rename to CreateInfo when http://crbug.com/123073 is
   // fixed.
   dictionary AlarmCreateInfo {
+    // Time at which the alarm should fire, in milliseconds past the epoch
+    // (e.g. Date.now() + n).
+    double? when;
+
     // Length of time in minutes after which the onAlarm event should fire.
-    // Note that granularity is not guaranteed: this value is more of a hint to
-    // the browser. For performance reasons, alarms may be delayed an arbitrary
-    // amount of time before firing.
+    //
     // TODO: need minimum=0
-    double delayInMinutes;
+    double? delayInMinutes;
 
-    // True if the alarm should repeatedly fire at regular intervals. Defaults
-    // to false.
-    boolean? repeating;
+    // If set, the onAlarm event should fire every |periodInMinutes| minutes
+    // after the initial event specified by |when| or |delayInMinutes|.  If not
+    // set, the alarm will only fire once.
+    //
+    // TODO: need minimum=0
+    double? periodInMinutes;
   };
 
   callback AlarmCallback = void (Alarm alarm);
   callback AlarmListCallback = void (Alarm[] alarms);
 
   interface Functions {
-    // Creates an alarm. After the delay is elapsed, the onAlarm event is
-    // fired. If there is another alarm with the same name (or no name if none
-    // is specified), it will be cancelled and replaced by this alarm.
+    // Creates an alarm.  Near the time(s) specified by 'alarmInfo', the onAlarm
+    // event is fired. If there is another alarm with the same name (or no name
+    // if none is specified), it will be cancelled and replaced by this alarm.
+    //
+    // Note that granularity is not guaranteed: times are more of a hint to the
+    // browser. For performance reasons, alarms may be delayed an arbitrary
+    // amount of time before firing.
+    //
     // |name|: Optional name to identify this alarm. Defaults to the empty
     // string.
+    //
+    // |alarmInfo|: Describes when the alarm should fire.  The initial time must
+    // be specified by either |when| or |delayInMinutes| (but not both).  If
+    // |periodInMinutes| is set, the alarm will repeat every |periodInMinutes|
+    // minutes after the initial event.  If neither |when| or |delayInMinutes|
+    // is set for a repeating alarm, |periodInMinutes| is used as the default
+    // for |delayInMinutes|.
     static void create(optional DOMString name, AlarmCreateInfo alarmInfo);
 
     // Retrieves details about the specified alarm.