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