Draft: apps APIs in Pepper

ppapi/api/dev/ppb_alarms_dev.idl

+/* Copyright (c) 2013 The Chromium Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+/**
+ * This file defines the Pepper equivalent of the <code>chrome.alarms</code>
+ * extension API.
+ */
+
+label Chrome {
+  M33 = 0.1
+};
+
+struct PP_Alarms_Alarm_Dev {
+  /**
+   * Name of this alarm.
+   */
+  PP_Var name;
+  /**
+   * Time at which this alarm was scheduled to fire, in milliseconds past the
+   * epoch. For performance reasons, the alarm may have been delayed an
+   * arbitrary amount beyond this.
+   */
+  double_t scheduled_time;
+  /**
+   * If set, the alarm is a repeating alarm and will fire again in
+   * <var>period_in_minutes</var> minutes.
+   */
+  PP_Optional_Double period_in_minutes;
+};
+
+struct PP_Alarms_AlarmCreateInfo_Dev {
+  /**
+   * Time at which the alarm should fire, in milliseconds past the epoch.
+   */
+  PP_Optional_Double when;
+  /**
+   * Length of time in minutes after which the <code>onAlarm</code> event
+   * should fire.
+   */
+  PP_Optional_Double delay_in_minutes;
+  /**
+   * If set, the onAlarm event should fire every <var>period_in_minutes</var>
+   * minutes after the initial event specified by <var>when</var> or
+   * <var>delay_in_minutes</var>. If not set, the alarm will only fire once.
+   */
+  PP_Optional_Double period_in_minutes;
+};
+
+struct PP_Alarms_Alarm_Array_Dev {
+  uint32_t size;
+  [size_is(count)] PP_Alarms_Alarm_Dev[] elements;
+};
+
+/**
+ * Fired when an alarm has elapsed. Useful for event pages.
+ *
+ * @param[in] listener_id The listener ID.
+ * @param[inout] user_data The opaque pointer that was used when registering the
+ * listener.
+ * @param[in] alarm The alarm that has elapsed.
+ */
+typedef void PP_Alarms_OnAlarm_Dev(
+    [in] uint32_t listener_id,
+    [inout] mem_t user_data,
+    [in] PP_Alarms_Alarm_Dev alarm);
+
+interface PPB_Alarms_Dev {
+  /**
+   * Creates an alarm.  Near the time(s) specified by <var>alarm_info</var>,
+   * the <code>PP_Alarms_OnAlarm_Dev</code> event is fired. If there is another
+   * alarm with the same name (or no name if none is specified), it will be
+   * cancelled and replaced by this alarm.
+   *
+   * In order to reduce the load on the user's machine, Chrome limits alarms
+   * to at most once every 1 minute but may delay them an arbitrary amount more.
+   * That is, setting <code>$ref:[PP_Alarms_AlarmCreateInfo_Dev.delay_in_minutes
+   * delay_in_minutes]</code> or
+   * <code>$ref:[PP_Alarms_AlarmCreateInfo_Dev.period_in_minutes
+   * period_in_minutes]</code> to less than <code>1</code> will not be honored
+   * and will cause a warning.
+   * <code>$ref:[PP_Alarms_AlarmCreateInfo_Dev.when when]</code> can be set
+   * to less than 1 minute after "now" without warning but won't actually cause
+   * the alarm to fire for at least 1 minute.
+   *
+   * To help you debug your app or extension, when you've loaded it unpacked,
+   * there's no limit to how often the alarm can fire.
+   *
+   * @param[in] instance A <code>PP_Instance</code>.
+   * @param[in] name A string or undefined <code>PP_Var</code>. Optional name to
+   * identify this alarm. Defaults to the empty string.
+   * @param[in] alarm_info Describes when the alarm should fire. The initial
+   * time must be specified by either <var>when</var> or
+   * <var>delay_in_minutes</var> (but not both).  If
+   * <var>period_in_minutes</var> is set, the alarm will repeat every
+   * <var>period_in_minutes</var> minutes after the initial event.  If neither
+   * <var>when</var> or <var>delay_in_minutes</var> is set for a repeating
+   * alarm, <var>period_in_minutes</var> is used as the default for
+   * <var>delay_in_minutes</var>.
+   */
+  void Create(
+      [in] PP_Instance instance,
+      [in] PP_Var name,
+      [in] PP_Alarms_AlarmCreateInfo_Dev alarm_info);
+
+  /**
+   * Retrieves details about the specified alarm.
+   *
+   * @param[in] instance A <code>PP_Instance</code>.
+   * @param[in] name A string or undefined <code>PP_Var</code>. The name of the
+   * alarm to get. Defaults to the empty string.
+   * @param[out] alarm A <code>PP_Alarms_Alarm_Dev</code> struct to store the
+   * output result.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An error code from <code>pp_errors.h</code>
+   */
+  int32_t Get(
+      [in] PP_Instance instance,
+      [in] PP_Var name,
+      [out] PP_Alarms_Alarm_Dev alarm,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Gets an array of all the alarms.
+   *
+   * @param[in] instance A <code>PP_Instance</code>.
+   * @param[out] alarms A <code>PP_Alarms_Alarm_Array_Dev</code> to store the
+   * output result.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+   * completion.
+   *
+   * @return An error code from <code>pp_errors.h</code>
+   */
+  int32_t GetAll(
+      [in] PP_Instance instance,
+      [out] PP_Alarms_Alarm_Array_Dev alarms,
+      [in] PP_ArrayOutput array_allocator,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Clears the alarm with the given name.
+   *
+   * @param[in] instance A <code>PP_Instance</code>.
+   * @param[in] name A string or undefined <code>PP_Var</code>. The name of the
+   * alarm to clear. Defaults to the empty string.
+   */
+  void Clear(
+      [in] PP_Instance instance,
+      [in] PP_Var name);
+
+  /**
+   * Clears all alarms.
+   *
+   * @param[in] instance A <code>PP_Instance</code>.
+   */
+  void ClearAll(
+      [in] PP_Instance instance);
+
+  /**
+   * Registers <code>PP_Alarms_OnAlarm_Dev</code> event.
+   *
+   * @param[in] instance A <code>PP_Instance</code>.
+   * @param[in] callback The callback to receive notifications.
+   * @param[inout] user_data An opaque pointer that will be passed to
+   * <code>callback</code>.
+   *
+   * @return A listener ID, or 0 if failed.
+   *
+   * TODO(yzshen): add a PPB_Events_Dev interface for unregistering:
+   * void UnregisterListener(PP_instance instance, uint32_t listener_id);
+   */
+  uint32_t AddOnAlarmListener(
+      [in] PP_Instance instance,
+      [in] PP_Alarms_OnAlarm_Dev callback,
+      [inout] mem_t user_data);
+};