ppapi/api/extensions/dev/ppb_ext_alarms_dev.idl

   1 /* Copyright (c) 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   M27 = 0.1
  13 };
  14
  15 #inline c
  16 #include "ppapi/c/extensions/dev/ppb_ext_events_dev.h"
  17 #endinl
  18
  19 /**
  20  * A dictionary <code>PP_Var</code> which contains:
  21  * - "name" : string <code>PP_Var</code>
  22  * Name of this alarm.
  23  *
  24  * - "scheduledTime" : double <code>PP_Var</code>
  25  * Time at which this alarm was scheduled to fire, in milliseconds past the
  26  * epoch (e.g. <code>Date.now() + n</code>).  For performance reasons, the
  27  * alarm may have been delayed an arbitrary amount beyond this.
  28  *
  29  * - "periodInMinutes" : double or undefined <code>PP_Var</code>
  30  * If not undefined, the alarm is a repeating alarm and will fire again in
  31  * <var>periodInMinutes</var> minutes.
  32  */
  33 typedef PP_Var PP_Ext_Alarms_Alarm_Dev;
  34
  35 /**
  36  * A dictionary <code>PP_Var</code> which contains
  37  * - "when" : double or undefined <code>PP_Var</code>
  38  * Time at which the alarm should fire, in milliseconds past the epoch
  39  * (e.g. <code>Date.now() + n</code>).
  40  *
  41  * - "delayInMinutes" : double or undefined <code>PP_Var</code>
  42  * Length of time in minutes after which the
  43  * <code>PP_Ext_Alarms_OnAlarm_Dev</code> event should fire.
  44  *
  45  * - "periodInMinutes" : double or undefined <code>PP_Var</code>
  46  * If set, the <code>PP_Ext_Alarms_OnAlarm_Dev</code> event should fire every
  47  * <var>periodInMinutes</var> minutes after the initial event specified by
  48  * <var>when</var> or <var>delayInMinutes</var>.  If not set, the alarm will
  49  * only fire once.
  50  */
  51 typedef PP_Var PP_Ext_Alarms_AlarmCreateInfo_Dev;
  52
  53 /**
  54  * An array <code>PP_Var</code> which contains elements of
  55  * <code>PP_Ext_Alarms_Alarm_Dev</code>.
  56  */
  57 typedef PP_Var PP_Ext_Alarms_Alarm_Dev_Array;
  58
  59 interface PPB_Ext_Alarms_Dev {
  60   /**
  61    * Creates an alarm.  Near the time(s) specified by <var>alarm_info</var>,
  62    * the <code>PP_Ext_Alarms_OnAlarm_Dev</code> event is fired. If there is
  63    * another alarm with the same name (or no name if none is specified), it will
  64    * be cancelled and replaced by this alarm.
  65    *
  66    * In order to reduce the load on the user's machine, Chrome limits alarms
  67    * to at most once every 1 minute but may delay them an arbitrary amount
  68    * more.  That is, setting
  69    * <code>$ref:[PP_Ext_Alarms_AlarmCreateInfo_Dev.delayInMinutes
  70    * delayInMinutes]</code> or
  71    * <code>$ref:[PP_Ext_Alarms_AlarmCreateInfo_Dev.periodInMinutes
  72    * periodInMinutes]</code> to less than <code>1</code> will not be honored
  73    * and will cause a warning.
  74    * <code>$ref:[PP_Ext_Alarms_AlarmCreateInfo_Dev.when when]</code> can be set
  75    * to less than 1 minute after "now" without warning but won't actually cause
  76    * the alarm to fire for at least 1 minute.
  77    *
  78    * To help you debug your app or extension, when you've loaded it unpacked,
  79    * there's no limit to how often the alarm can fire.
  80    *
  81    * @param[in] instance A <code>PP_Instance</code>.
  82    * @param[in] name A string or undefined <code>PP_Var</code>. Optional name to
  83    * identify this alarm. Defaults to the empty string.
  84    * @param[in] alarm_info A <code>PP_Var</code> whose contents conform to the
  85    * description of <code>PP_Ext_Alarms_AlarmCreateInfo_Dev</code>. Describes
  86    * when the alarm should fire.  The initial time must be specified by either
  87    * <var>when</var> or <var>delayInMinutes</var> (but not both).  If
  88    * <var>periodInMinutes</var> is set, the alarm will repeat every
  89    * <var>periodInMinutes</var> minutes after the initial event.  If neither
  90    * <var>when</var> or <var>delayInMinutes</var> is set for a repeating alarm,
  91    * <var>periodInMinutes</var> is used as the default for
  92    * <var>delayInMinutes</var>.
  93    */
  94   void Create(
  95       [in] PP_Instance instance,
  96       [in] PP_Var name,
  97       [in] PP_Ext_Alarms_AlarmCreateInfo_Dev alarm_info);
  98
  99   /**
 100    * Retrieves details about the specified alarm.
 101    *
 102    * @param[in] instance A <code>PP_Instance</code>.
 103    * @param[in] name A string or undefined <code>PP_Var</code>. The name of the
 104    * alarm to get. Defaults to the empty string.
 105    * @param[out] alarm A <code>PP_Var</code> whose contents conform to the
 106    * description of <code>PP_Ext_Alarms_Alarm_Dev</code>.
 107    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 108    * completion.
 109    *
 110    * @return An error code from <code>pp_errors.h</code>
 111    */
 112   int32_t Get(
 113       [in] PP_Instance instance,
 114       [in] PP_Var name,
 115       [out] PP_Ext_Alarms_Alarm_Dev alarm,
 116       [in] PP_CompletionCallback callback);
 117
 118   /**
 119    * Gets an array of all the alarms.
 120    *
 121    * @param[in] instance A <code>PP_Instance</code>.
 122    * @param[out] alarms A <code>PP_Var</code> whose contents conform to the
 123    * description of <code>PP_Ext_Alarms_Alarm_Dev_Array</code>.
 124    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 125    * completion.
 126    *
 127    * @return An error code from <code>pp_errors.h</code>
 128    */
 129   int32_t GetAll(
 130       [in] PP_Instance instance,
 131       [out] PP_Ext_Alarms_Alarm_Dev_Array alarms,
 132       [in] PP_CompletionCallback callback);
 133
 134   /**
 135    * Clears the alarm with the given name.
 136    *
 137    * @param[in] instance A <code>PP_Instance</code>.
 138    * @param[in] name A string or undefined <code>PP_Var</code>. The name of the
 139    * alarm to clear. Defaults to the empty string.
 140    */
 141   void Clear(
 142       [in] PP_Instance instance,
 143       [in] PP_Var name);
 144
 145   /**
 146    * Clears all alarms.
 147    *
 148    * @param[in] instance A <code>PP_Instance</code>.
 149    */
 150   void ClearAll(
 151       [in] PP_Instance instance);
 152 };
 153
 154 /**
 155  * Fired when an alarm has elapsed. Useful for event pages.
 156  *
 157  * @param[in] listener_id The listener ID.
 158  * @param[inout] user_data The opaque pointer that was used when registering the
 159  * listener.
 160  * @param[in] alarm A <code>PP_Var</code> whose contents conform to the
 161  * description of <code>PP_Ext_Alarms_Alarm_Dev</code>. The alarm that has
 162  * elapsed.
 163  */
 164 typedef void PP_Ext_Alarms_OnAlarm_Func_Dev_0_1(
 165     [in] uint32_t listener_id,
 166     [inout] mem_t user_data,
 167     [in] PP_Ext_Alarms_Alarm_Dev alarm);
 168
 169 #inline c
 170 PP_INLINE struct PP_Ext_EventListener PP_Ext_Alarms_OnAlarm_Dev_0_1(
 171     PP_Ext_Alarms_OnAlarm_Func_Dev_0_1 func,
 172     void* user_data) {
 173   return PP_Ext_MakeEventListener("alarms.onAlarm;0.1",
 174                                   (PP_Ext_GenericFuncType)(func), user_data);
 175 }
 176
 177 #define PP_Ext_Alarms_OnAlarm_Dev PP_Ext_Alarms_OnAlarm_Dev_0_1
 178 #endinl