Add PPB_Alarms_Dev interface definition.

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
+   * <code>period_in_minutes</code> 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>PP_Alarms_OnAlarm_Dev</code> event should fire.
+   */
+  PP_Optional_Double delay_in_minutes;
+  /**
+   * If set, the <code>PP_Alarms_OnAlarm_Dev</code> event should fire every
+   * <code>period_in_minutes</code> minutes after the initial event specified by
+   * <code>when</code> or <code>delay_in_minutes</code>. 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);

[teravest, 2013/12/10 14:56:05]

Why is it okay to pass a struct by value here? See
https://code.google.com/p/chromium/issues/detail?id=233439.

Why will this work on PNaCl, when the following is problematic?
// From ppapi/c/extensions/dev/ppb_ext_alarms_dev.h:
typedef void (*PP_Ext_Alarms_OnAlarm_Func_Dev_0_1)(
    uint32_t listener_id,
    void* user_data,
    PP_Ext_Alarms_Alarm_Dev alarm); // "alarm" is call-by-value struct

I don't like changing the logic in idl_c_header.py to permit this, without
understanding why this won't cause a problem for PNaCl.

[Mark Seaborn, 2013/12/10 15:56:17]

Indeed.  This is a problem and won't work under PNaCl.  You have to pass structs
to callbacks by pointer instead of by value.

[yzshen1, 2013/12/10 17:37:41]

I agree with both of you. :)

The whole PPB_Ext_Alarms_Dev interface has been removed yesterday by me:
https://codereview.chromium.org/103093004
So the example you used before is gone now.

Here PP_Alarms_OnAlarm_Dev passes PP_Alarms_Alarm_Dev *by reference*, so I think
it is okay. But the check in idl_c_header.py mistakenly regards it as
pass-by-value and issues an presumbit error. That is what I would like to fix.
 

[dmichael (off chromium), 2013/12/10 17:48:42]

The generated code here looks like this:
typedef void (*PP_Alarms_OnAlarm_Dev)(
    uint32_t listener_id,
    void* user_data,
    const struct PP_Alarms_Alarm_Dev* alarm);

Note that PP_Alarms_Alarm_Dev is passed by const-pointer, as Yuzhu noted. I
think the problem is not at this spot, but below. See comment there...

+
+interface PPB_Alarms_Dev {
+  /**
+   * Creates an alarm.  Near the time(s) specified by <code>alarm_info</code>,
+   * 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>PP_Alarms_AlarmCreateInfo_Dev.delay_in_minutes</code> or
+   * <code>PP_Alarms_AlarmCreateInfo_Dev.period_in_minutes</code> to less than
+   * <code>1</code> will not be honored and will cause a warning.
+   * <code>PP_Alarms_AlarmCreateInfo_Dev.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 <code>when</code> or
+   * <code>delay_in_minutes</code> (but not both).  If
+   * <code>period_in_minutes</code> is set, the alarm will repeat every
+   * <code>period_in_minutes</code> minutes after the initial event.  If neither
+   * <code>when</code> or <code>delay_in_minutes</code> is set for a repeating
+   * alarm, <code>period_in_minutes</code> is used as the default for
+   * <code>delay_in_minutes</code>.
+   */
+  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] array_allocator A <code>PP_ArrayOutput</code> to allocate memory
+   * for <code>alarms</code>.
+   * @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,

[dmichael (off chromium), 2013/12/10 17:48:42]

I think maybe this is the part that's getting flagged? The generated code looks
like this:

  uint32_t (*AddOnAlarmListener)(PP_Instance instance,
                                 PP_Alarms_OnAlarm_Dev callback,
                                 void* user_data);

See how PP_Alarms_OnAlarm_Dev appears to be by-value? However, it's a function
pointer, so it's probably safe (Mark, please correct me if I'm wrong).

We're going to run in to more and more function pointers with the new APIs
Yuzhu's working on. If it's at all possible, it would be best to make the IDL
generator understand that it's a function pointer and therefore safe to pass
this way. But I think using the whitelist for now is probably fine.

+      [inout] mem_t user_data);
+};