PPAPI: Add dev synchronous JS->Plugin messaging API

ppapi/api/ppp_message_handler.idl

+/* Copyright 2014 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_Messaging</code> interface implemented
+ * by the browser for sending messages to DOM elements associated with a
+ * specific module instance.
+ */
+
+label Chrome {
+  [channel=dev] M36 = 0.1
+};
+
+/**
+ * The <code>PPP_MessageHandler</code> interface is implemented by the plugin
+ * if the plugin wants to receive messages from a thread other than the main
+ * Pepper thread, or if the plugin wants to handle blocking messages which
+ * JavaScript may send via postMessageAndAwaitResponse().
+ *
+ * This interface struct should not be returned by PPP_GetInterface; instead it
+ * must be passed as a parameter to PPB_Messaging::RegisterMessageHandler.
+ */
+[no_interface_string]
+interface PPP_MessageHandler {

[darin (slow to review), 2014/05/02 08:02:15]

Perhaps an alternative approach is to expose a PPB_MessageQueue interface with a
method to Get (w/ CompletionCallback). This queue could be queried from any
thread.

Maybe the currently proposed API is better because it offers nicer guide rails
for developers?

[dmichael (off chromium), 2014/05/02 16:28:54]

Right, I started out down that road. It actually gives more flexibility, but I
didn't like how it made it easier to leave JavaScript blocked, whereas the
PPP_MessageHandler and return value approach makes it really hard to mess up,
since it's hard to forget to return from a function :-). Here's what I had
thrown together:
https://codereview.chromium.org/253813006/diff/1/ppapi/api/ppb_messaging.idl

Another disadvantage with that: I want to be able to detect when there is no
handler waiting in the plugin, so that JavaScript will get an immediate failure
if the plugin isn't waiting to handle the sync message. Using completion
callbacks, there's a time window when the plugin has responded using:
RespondToBlockingMessage()
but has not yet called
GetBlockingMessage()
to ask for the next message. During that time window, it's not obvious that the
plugin is going to handle more JavaScript messages. There are ways to work
around it, but...  overall, I didn't like the tradeoffs of going that way.

+  /**
+   *  Invoked as a result of JavaScript invoking postMessage() on the plugin's
+   *  DOM element.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   * @param[in] user_data is the same pointer which was provided by a call to
+   * RegisterMessageHandler.
+   * @param[in] message A copy of the parameter that JavaScript provided to
+   * postMessage().
+   */
+  void HandleMessage([in] PP_Instance instance,
+                     [in] mem_t user_data,
+                     [in] PP_Var message);
+  /**
+   * Invoked as a result of JavaScript invoking postMessageAndAwaitResponse()
+   * on the plugin's DOM element.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   * @param[in] user_data is the same pointer which was provided by a call to
+   * RegisterMessageHandler.
+   * @param[in] message is a copy of the parameter that JavaScript provided
+   * to postMessageAndAwaitResponse.
+   * @return will be copied to a JavaScript object which is returned as
+   * the result of postMessageAndAwaitResponse to the invoking JavaScript.
+   */
+  PP_Var HandleBlockingMessage([in] PP_Instance instance,
+                               [in] mem_t user_data,
+                               [in] PP_Var message);
+  /**
+   * Invoked when the handler object is no longer needed. After this, no more
+   * calls will be made which pass this same value for <code>instance</code>
+   * and <code>user_data</code>.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   * @param[in] user_data is the same pointer which was provided by a call to
+   * RegisterMessageHandler.
+   */
+  void Destroy([in] PP_Instance instance,
+               [in] mem_t user_data);
+};
+