Add GetUsbKeyCode dev interface for Pepper key events

ppapi/api/dev/ppb_keyboard_input_event_dev.idl

+/* Copyright (c) 2012 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 <code>PPB_KeyboardInputEvent_Dev</code> interface,
+ * which provides access to the raw USB scancodes for key input events.

[Wez, 2012/02/17 01:31:01]

nit: It's not _the_ raw USB scancodes, but USB key codes identifying the
physical keys pressed - the interface doesn't get the details directly from USB.

[garykac, 2012/02/17 18:25:30]

Done.

+ */
+
+label Chrome {
+  M19 = 0.1
+};
+
+/**
+ * The <code>PPB_KeyboardInputEvent_Dev</code> interface is an extension to the
+ * PPB_KeyboardInputEvent</code> interface that provides
+ */
+[version=0.1, macro="PPB_KEYBOARD_INPUT_EVENT_DEV_INTERFACE"]
+interface PPB_KeyboardInputEvent_Dev {
+  /**
+   * This sets the usb_scan_code in the given <code>resource</code>. It is

[Wez, 2012/02/17 01:31:01]

nit: ... the given PP_InputEvent resource?

[Wez, 2012/02/17 01:31:01]

nit: ... sets the usb_scan_code ... -> ... set a USB key code ... 

[garykac, 2012/02/17 18:25:30]

Done.

[garykac, 2012/02/17 18:25:30]

Done.

+   * intended that this method be called immediately after any call to
+   * <code>Create</code>.
+   *
+   * When GetUsbScanCode moves out of this _Dev interface, then the
+   * <code>usb_scan_code</code> param will be added to the <code>Create</code>
+   * method and this method will be removed.

[Wez, 2012/02/17 01:31:01]

nit: I don't think this comment is necessary to understand this interface, and
we might keep USB key codes as a separate interface.

[garykac, 2012/02/17 18:25:30]

Done.

+   *
+   * @param[in] key_event A <code>PP_Resource</code> created by
+   * <code>PPB_KeyboardInputEvent</code>'s <code>Create</code> method.
+   *
+   * @param[in] usb_scan_code The USB scancode to assign for this

[Wez, 2012/02/17 01:31:01]

nit: assign for this -> assign to this (or associated with this)

[garykac, 2012/02/17 18:25:30]

Done.

+   * <code>key_event</code>.
+   *
+   * @return <code>PP_TRUE</code> if the usb scancode was set successfully.

[Wez, 2012/02/17 01:31:01]

Under what circumstances might setting the scancode fail?

[garykac, 2012/02/17 18:25:30]

If the thunking can't acquire the lock to update the resource. This failure case
is true for all of these api calls.

+   */
+  PP_Bool SetUsbScanCode([in] PP_Resource key_event,
+                         [in] uint32_t usb_scan_code);
+
+  /**
+   * GetUsbScanCode() returns the USB scancode that corresponds to the key
+   * that generated this keyboard event.

[Wez, 2012/02/17 01:31:01]

nit: ... that corresponds ... this keyboard event -> ... that is associated with
this event.

If the intent is that GetUsbScanCode() is the API plugins will normally care
about, and SetUsbScanCode() is there only for completeness then consider putting
GetUsbScanCode() first, and having the comment on it describe what the USB key
code comes from.

[garykac, 2012/02/17 18:25:30]

Done.

+   *
+   * @param[in] key_event A <code>PP_Resource</code> corresponding to a
+   * keyboard event.
+   *
+   * @return The USB scancode field for the keyboard event.

[Wez, 2012/02/17 01:31:01]

What if no USB key code was set, e.g. if the input event was generated by
JavaScript?

[garykac, 2012/02/17 18:25:30]

Done.

+   */
+  uint32_t GetUsbScanCode([in] PP_Resource key_event);
+};