Import chrome idl into third_party

third_party/chrome/idl/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.
+
+// TODO(mpcomplete): We need documentation before we can release this.
+
+namespace alarms {
+  dictionary Alarm {
+    // Name of this alarm.
+    DOMString name;
+
+    // Time at which this alarm was scheduled to fire, in milliseconds past the
+    // epoch (e.g. <code>Date.now() + n</code>).  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
+    // <var>periodInMinutes</var> 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. <code>Date.now() + n</code>).
+    double? when;
+
+    // Length of time in minutes after which the <code>onAlarm</code> event
+    // should fire.
+    //
+    // <!-- TODO: need minimum=0 -->
+    double? delayInMinutes;
+
+    // If set, the onAlarm event should fire every <var>periodInMinutes</var>
+    // minutes after the initial event specified by <var>when</var> or
+    // <var>delayInMinutes</var>.  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.  Near the time(s) specified by <var>alarmInfo</var>,
+    // the <code>onAlarm</code> 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.
+    //
+    // In order to reduce the load on the user's machine, Chrome limits alarms
+    // to at most once every 1 minute but may delay them an arbitrary amount
+    // more.  That is, setting <code>$ref:[alarms.AlarmCreateInfo.delayInMinutes
+    // delayInMinutes]</code> or
+    // <code>$ref:[alarms.AlarmCreateInfo.periodInMinutes
+    // periodInMinutes]</code> to less than <code>1</code> will not be honored
+    // and will cause a warning.  <code>$ref:[alarms.AlarmCreateInfo.when
+    // when]</code> can be set to less than 1 minute after "now" without
+    // warning but won't actually cause the alarm to fire for at least 1 minute.
+    //
+    // To help you debug your app or extension, when you've loaded it unpacked,
+    // there's no limit to how often the alarm can fire.
+    //
+    // |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 <var>when</var> or <var>delayInMinutes</var> (but
+    // not both).  If <var>periodInMinutes</var> is set, the alarm will repeat
+    // every <var>periodInMinutes</var> minutes after the initial event.  If
+    // neither <var>when</var> or <var>delayInMinutes</var> is set for a
+    // repeating alarm, <var>periodInMinutes</var> is used as the default for
+    // <var>delayInMinutes</var>.
+    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 event pages.
+    // |alarm|: The alarm that has elapsed.
+    static void onAlarm(Alarm alarm);
+  };
+};