1 /* Copyright 2013 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 6 /** 7 * This file defines the Pepper equivalent of the <code>chrome.alarms</code> 8 * extension API. 9 */ 10 11 label Chrome { 12 M33 = 0.1 13 }; 14 15 struct PP_Alarms_Alarm_Dev { 16 /** 17 * Name of this alarm. 18 */ 19 PP_Var name; 20 /** 21 * Time at which this alarm was scheduled to fire, in milliseconds past the 22 * epoch. For performance reasons, the alarm may have been delayed an 23 * arbitrary amount beyond this. 24 */ 25 double_t scheduled_time; 26 /** 27 * If set, the alarm is a repeating alarm and will fire again in 28 * <code>period_in_minutes</code> minutes. 29 */ 30 PP_Optional_Double_Dev period_in_minutes; 31 }; 32 33 struct PP_Alarms_AlarmCreateInfo_Dev { 34 /** 35 * Time at which the alarm should fire, in milliseconds past the epoch. 36 */ 37 PP_Optional_Double_Dev when; 38 /** 39 * Length of time in minutes after which the 40 * <code>PP_Alarms_OnAlarm_Dev</code> event should fire. 41 */ 42 PP_Optional_Double_Dev delay_in_minutes; 43 /** 44 * If set, the <code>PP_Alarms_OnAlarm_Dev</code> event should fire every 45 * <code>period_in_minutes</code> minutes after the initial event specified by 46 * <code>when</code> or <code>delay_in_minutes</code>. If not set, the alarm 47 * will only fire once. 48 */ 49 PP_Optional_Double_Dev period_in_minutes; 50 }; 51 52 struct PP_Alarms_Alarm_Array_Dev { 53 uint32_t size; 54 [size_is(count)] PP_Alarms_Alarm_Dev[] elements; 55 }; 56 57 /** 58 * Fired when an alarm has elapsed. Useful for event pages. 59 * 60 * @param[in] listener_id The listener ID. 61 * @param[inout] user_data The opaque pointer that was used when registering the 62 * listener. 63 * @param[in] alarm The alarm that has elapsed. 64 */ 65 typedef void PP_Alarms_OnAlarm_Dev( 66 [in] uint32_t listener_id, 67 [inout] mem_t user_data, 68 [in] PP_Alarms_Alarm_Dev alarm); 69 70 interface PPB_Alarms_Dev { 71 /** 72 * Creates an alarm. Near the time(s) specified by <code>alarm_info</code>, 73 * the <code>PP_Alarms_OnAlarm_Dev</code> event is fired. If there is another 74 * alarm with the same name (or no name if none is specified), it will be 75 * cancelled and replaced by this alarm. 76 * 77 * In order to reduce the load on the user's machine, Chrome limits alarms 78 * to at most once every 1 minute but may delay them an arbitrary amount more. 79 * That is, setting 80 * <code>PP_Alarms_AlarmCreateInfo_Dev.delay_in_minutes</code> or 81 * <code>PP_Alarms_AlarmCreateInfo_Dev.period_in_minutes</code> to less than 82 * <code>1</code> will not be honored and will cause a warning. 83 * <code>PP_Alarms_AlarmCreateInfo_Dev.when</code> can be set to less than 1 84 * minute after "now" without warning but won't actually cause the alarm to 85 * fire for at least 1 minute. 86 * 87 * To help you debug your app or extension, when you've loaded it unpacked, 88 * there's no limit to how often the alarm can fire. 89 * 90 * @param[in] instance A <code>PP_Instance</code>. 91 * @param[in] name A string or undefined <code>PP_Var</code>. Optional name to 92 * identify this alarm. Defaults to the empty string. 93 * @param[in] alarm_info Describes when the alarm should fire. The initial 94 * time must be specified by either <code>when</code> or 95 * <code>delay_in_minutes</code> (but not both). If 96 * <code>period_in_minutes</code> is set, the alarm will repeat every 97 * <code>period_in_minutes</code> minutes after the initial event. If neither 98 * <code>when</code> or <code>delay_in_minutes</code> is set for a repeating 99 * alarm, <code>period_in_minutes</code> is used as the default for 100 * <code>delay_in_minutes</code>. 101 */ 102 void Create( 103 [in] PP_Instance instance, 104 [in] PP_Var name, 105 [in] PP_Alarms_AlarmCreateInfo_Dev alarm_info); 106 107 /** 108 * Retrieves details about the specified alarm. 109 * 110 * @param[in] instance A <code>PP_Instance</code>. 111 * @param[in] name A string or undefined <code>PP_Var</code>. The name of the 112 * alarm to get. Defaults to the empty string. 113 * @param[out] alarm A <code>PP_Alarms_Alarm_Dev</code> struct to store the 114 * output result. 115 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 116 * completion. 117 * 118 * @return An error code from <code>pp_errors.h</code> 119 */ 120 int32_t Get( 121 [in] PP_Instance instance, 122 [in] PP_Var name, 123 [out] PP_Alarms_Alarm_Dev alarm, 124 [in] PP_CompletionCallback callback); 125 126 /** 127 * Gets an array of all the alarms. 128 * 129 * @param[in] instance A <code>PP_Instance</code>. 130 * @param[out] alarms A <code>PP_Alarms_Alarm_Array_Dev</code> to store the 131 * output result. 132 * @param[in] array_allocator A <code>PP_ArrayOutput</code> to allocate memory 133 * for <code>alarms</code>. 134 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 135 * completion. 136 * 137 * @return An error code from <code>pp_errors.h</code> 138 */ 139 int32_t GetAll( 140 [in] PP_Instance instance, 141 [out] PP_Alarms_Alarm_Array_Dev alarms, 142 [in] PP_ArrayOutput array_allocator, 143 [in] PP_CompletionCallback callback); 144 145 /** 146 * Clears the alarm with the given name. 147 * 148 * @param[in] instance A <code>PP_Instance</code>. 149 * @param[in] name A string or undefined <code>PP_Var</code>. The name of the 150 * alarm to clear. Defaults to the empty string. 151 */ 152 void Clear( 153 [in] PP_Instance instance, 154 [in] PP_Var name); 155 156 /** 157 * Clears all alarms. 158 * 159 * @param[in] instance A <code>PP_Instance</code>. 160 */ 161 void ClearAll( 162 [in] PP_Instance instance); 163 164 /** 165 * Registers <code>PP_Alarms_OnAlarm_Dev</code> event. 166 * 167 * @param[in] instance A <code>PP_Instance</code>. 168 * @param[in] callback The callback to receive notifications. 169 * @param[inout] user_data An opaque pointer that will be passed to 170 * <code>callback</code>. 171 * 172 * @return A listener ID, or 0 if failed. 173 * 174 * TODO(yzshen): add a PPB_Events_Dev interface for unregistering: 175 * void UnregisterListener(PP_instance instance, uint32_t listener_id); 176 */ 177 uint32_t AddOnAlarmListener( 178 [in] PP_Instance instance, 179 [in] PP_Alarms_OnAlarm_Dev callback, 180 [inout] mem_t user_data); 181 }; 182
