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