extensions/common/api/alarms.idl

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>chrome.alarms</code> API to schedule code to run
   6 // periodically or at a specified time in the future.
   7 namespace alarms {
   8   dictionary Alarm {
   9     // Name of this alarm.
  10     DOMString name;
  11
  12     // Time at which this alarm was scheduled to fire, in milliseconds past the
  13     // epoch (e.g. <code>Date.now() + n</code>).  For performance reasons, the
  14     // alarm may have been delayed an arbitrary amount beyond this.
  15     double scheduledTime;
  16
  17     // If not null, the alarm is a repeating alarm and will fire again in
  18     // <var>periodInMinutes</var> minutes.
  19     double? periodInMinutes;
  20   };
  21
  22   // TODO(mpcomplete): rename to CreateInfo when http://crbug.com/123073 is
  23   // fixed.
  24   dictionary AlarmCreateInfo {
  25     // Time at which the alarm should fire, in milliseconds past the epoch
  26     // (e.g. <code>Date.now() + n</code>).
  27     double? when;
  28
  29     // Length of time in minutes after which the <code>onAlarm</code> event
  30     // should fire.
  31     //
  32     // <!-- TODO: need minimum=0 -->
  33     double? delayInMinutes;
  34
  35     // If set, the onAlarm event should fire every <var>periodInMinutes</var>
  36     // minutes after the initial event specified by <var>when</var> or
  37     // <var>delayInMinutes</var>.  If not set, the alarm will only fire once.
  38     //
  39     // <!-- TODO: need minimum=0 -->
  40     double? periodInMinutes;
  41   };
  42
  43   callback AlarmCallback = void (optional Alarm alarm);
  44   callback AlarmListCallback = void (Alarm[] alarms);
  45   callback ClearCallback = void (boolean wasCleared);
  46
  47   interface Functions {
  48     // Creates an alarm.  Near the time(s) specified by <var>alarmInfo</var>,
  49     // the <code>onAlarm</code> event is fired. If there is another alarm with
  50     // the same name (or no name if none is specified), it will be cancelled and
  51     // replaced by this alarm.
  52     //
  53     // In order to reduce the load on the user's machine, Chrome limits alarms
  54     // to at most once every 1 minute but may delay them an arbitrary amount
  55     // more.  That is, setting <code>delayInMinutes</code> or
  56     // <code>periodInMinutes</code> to less than <code>1</code> will not be
  57     // honored and will cause a warning.  <code>when</code> can be set to less
  58     // than 1 minute after "now" without warning but won't actually cause the
  59     // alarm to fire for at least 1 minute.
  60     //
  61     // To help you debug your app or extension, when you've loaded it unpacked,
  62     // there's no limit to how often the alarm can fire.
  63     //
  64     // |name|: Optional name to identify this alarm. Defaults to the empty
  65     // string.
  66     //
  67     // |alarmInfo|: Describes when the alarm should fire.  The initial time must
  68     // be specified by either <var>when</var> or <var>delayInMinutes</var> (but
  69     // not both).  If <var>periodInMinutes</var> is set, the alarm will repeat
  70     // every <var>periodInMinutes</var> minutes after the initial event.  If
  71     // neither <var>when</var> or <var>delayInMinutes</var> is set for a
  72     // repeating alarm, <var>periodInMinutes</var> is used as the default for
  73     // <var>delayInMinutes</var>.
  74     static void create(optional DOMString name, AlarmCreateInfo alarmInfo);
  75
  76     // Retrieves details about the specified alarm.
  77     // |name|: The name of the alarm to get. Defaults to the empty string.
  78     static void get(optional DOMString name, AlarmCallback callback);
  79
  80     // Gets an array of all the alarms.
  81     static void getAll(AlarmListCallback callback);
  82
  83     // Clears the alarm with the given name.
  84     // |name|: The name of the alarm to clear. Defaults to the empty string.
  85     static void clear(optional DOMString name, optional ClearCallback callback);
  86
  87     // Clears all alarms.
  88     static void clearAll(optional ClearCallback callback);
  89   };
  90
  91   interface Events {
  92     // Fired when an alarm has elapsed. Useful for event pages.
  93     // |alarm|: The alarm that has elapsed.
  94     static void onAlarm(Alarm alarm);
  95   };
  96 };