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. 7namespace 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}; 97