diff options
Diffstat (limited to 'chromium/extensions/common/api/alarms.idl')
-rw-r--r-- | chromium/extensions/common/api/alarms.idl | 96 |
1 files changed, 96 insertions, 0 deletions
diff --git a/chromium/extensions/common/api/alarms.idl b/chromium/extensions/common/api/alarms.idl new file mode 100644 index 00000000000..500d2ed9518 --- /dev/null +++ b/chromium/extensions/common/api/alarms.idl @@ -0,0 +1,96 @@ +// 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. + +// Use the <code>chrome.alarms</code> API to schedule code to run +// periodically or at a specified time in the future. +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 (optional Alarm alarm); + callback AlarmListCallback = void (Alarm[] alarms); + callback ClearCallback = void (boolean wasCleared); + + 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>delayInMinutes</code> or + // <code>periodInMinutes</code> to less than <code>1</code> will not be + // honored and will cause a warning. <code>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, optional ClearCallback callback); + + // Clears all alarms. + static void clearAll(optional ClearCallback callback); + }; + + interface Events { + // Fired when an alarm has elapsed. Useful for event pages. + // |alarm|: The alarm that has elapsed. + static void onAlarm(Alarm alarm); + }; +}; |