Refactor chrome.alarms interface to support absolute alarm deadlines.

chrome/common/extensions/api/alarms.idl

 // Copyright (c) 2012 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.
 
 // File-level comment to appease parser. Eventually this will not be necessary.
 // TODO(mpcomplete): We need documentation before we can release this.
 
 namespace alarms {
   dictionary Alarm {
     // Name of this alarm.
     DOMString name;
 
-    // Original length of time in minutes after which the onAlarm event should
-    // fire.
+    // 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;
+
+    // If not null, the alarm is a repeating alarm and will fire again in
+    // 'periodInMinutes' minutes.
+    double? periodInMinutes;
+  };
+
+  // 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;
-
-    // True if the alarm repeatedly fires at regular intervals, false if it
-    // only fires once.
-    boolean repeating;
+    double? delayInMinutes;
   };
 
   // TODO(mpcomplete): rename to CreateInfo when http://crbug.com/123073 is
   // fixed.
-  dictionary AlarmCreateInfo {
-    // 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.
+  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 delayInMinutes;
-
-    // True if the alarm should repeatedly fire at regular intervals. Defaults
-    // to false.
-    boolean? repeating;
+    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.
     static void get(optional DOMString name, AlarmCallback callback);
 
     // Gets an array of all the alarms.
     static void getAll(AlarmListCallback callback);
 
     // Clears the alarm with the given name.
     // |name|: The name of the alarm to clear. Defaults to the empty string.
     static void clear(optional DOMString name);
 
     // Clears all alarms.
     static void clearAll();
   };
 
   interface Events {
     // Fired when an alarm has elapsed. Useful for transient background pages.
     // |alarm|: The alarm that has elapsed.
     static void onAlarm(Alarm alarm);
   };
 };