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..c145134f84e727947eb08761921878aa875ba629 100644
--- a/chrome/common/extensions/api/alarms.idl
+++ b/chrome/common/extensions/api/alarms.idl
@@ -10,41 +10,70 @@ 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 {
+  // TODO(mpcomplete): rename to OneShotCreateInfo when http://crbug.com/123073
+  // is fixed.
+  dictionary AlarmOneShotCreateInfo {
+    // Time at which the alarm should fire, in milliseconds past the epoch
+    // (e.g. Date.now() + n).  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.
+    //
+    // Exactly one of timeToFire or delayInMinutes must be set.
+    double? timeToFire;

[Aaron Boodman, 2012/06/11 20:57:28]

Just 'time' is fine for the name.

[Jeffrey Yasskin, 2012/06/11 21:05:06]

Done.

+
     // 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.
+    //
+    // Exactly one of timeToFire or delayInMinutes must be set.
+    //
     // TODO: need minimum=0
-    double delayInMinutes;
+    double? delayInMinutes;
+  };
 
-    // True if the alarm should repeatedly fire at regular intervals. Defaults
-    // to false.
-    boolean? repeating;
+  // TODO(mpcomplete): rename to CreateInfo when http://crbug.com/123073 is
+  // fixed.
+  dictionary AlarmRepeatingCreateInfo {
+    // Length of time in minutes between times the onAlarm event should fire,
+    // and the delay before the first time it fires.  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 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.
-    // |name|: Optional name to identify this alarm. Defaults to the empty
-    // string.
-    static void create(optional DOMString name, AlarmCreateInfo alarmInfo);
+    // Creates an alarm that will fire once.  Near the time specified by
+    // 'alarmInfo', the onAlarm event is fired. If there is another alarm
+    // (either one-shot or repeating) with the same name (or no name if none is
+    // specified), it will be cancelled and replaced by this alarm.  |name|:
+    // Optional name to identify this alarm. Defaults to the empty string.
+    static void createOneShot(optional DOMString name,
+                              AlarmOneShotCreateInfo alarmInfo);
+
+    // Creates an alarm that will fire repeatedly.  The onAlarm event is fired
+    // with a period specified by 'alarmInfo'. If there is another alarm (either
+    // one-shot or repeating) with the same name (or no name if none is
+    // specified), it will be cancelled and replaced by this alarm.  |name|:
+    // Optional name to identify this alarm. Defaults to the empty string.
+    static void createRepeating(optional DOMString name,
+                                AlarmRepeatingCreateInfo alarmInfo);
 
     // Retrieves details about the specified alarm.
     // |name|: The name of the alarm to get. Defaults to the empty string.