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.
+  // 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).  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.
+    //
+    // Cannot be specified with |delayInMinutes|, and one of |when|,

[Aaron Boodman, 2012/06/12 23:02:38]

Maybe it would be simpler to just describe the allowed calls in the structure's
comments, rather than repeating for each parameter.

[Jeffrey Yasskin, 2012/06/12 23:37:28]

Done.

+    // |delayInMinutes|, or |periodInMinutes| must be set.
+    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.
+    //
+    // Cannot be specified with |when|, and one of |when|, |delayInMinutes|, or
+    // |periodInMinutes| 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;
+    // If set, the onAlarm event should fire every |periodInMinutes| minutes
+    // after the initial event specified by |when| or |delayInMinutes|.  If
+    // neither |when| nor |delayInMinutes| is set, |delayInMinutes| defaults to
+    // |periodInMinutes|.  If not set, the alarm will only fire once.
+    //
+    // 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.
+    // Creates an alarm.  Near the time 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.
     // |name|: Optional name to identify this alarm. Defaults to the empty
     // string.
     static void create(optional DOMString name, AlarmCreateInfo alarmInfo);
 
+

[Aaron Boodman, 2012/06/12 23:02:38]

extra line

[Jeffrey Yasskin, 2012/06/12 23:37:28]

Oops, fixed.

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