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.
-    // 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.
     // |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);
   };
 };