ppapi/api/dev/ppb_alarms_dev.idl

   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 };