PPAPI: Add dev synchronous JS->Plugin messaging API

ppapi/api/ppp_message_handler.idl

+/* Copyright (c) 2012 The Chromium Authors. All rights reserved.

[teravest, 2014/05/01 19:20:38]

nit: 2014

[dmichael (off chromium), 2014/05/01 19:55:00]

Done.

+ * 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 {
+  /**
+   *  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] message A copy of the parameter that JavaScript provided to
+   * postMessage().
+   * @param[in] user_data is the same as was provided by a call to

[teravest, 2014/05/01 19:20:38]

nit: comments are out of order for params. Also true below.

[dmichael (off chromium), 2014/05/01 19:55:00]

Done.

+   * RegisterMessageHandler.
+   */
+  void HandleMessage([in] PP_Instance instance,
+                     [in] mem_t user_data,
+                     [in] PP_Var message);
+  /**
+   * Invoked as a result of JavaScript invoking postMessageAndAwaitResponse()

[teravest, 2014/05/01 19:20:38]

Where can I find more information on postMessageAndAwaitResponse()? I wasn't
able to find any information on it.

[dmichael (off chromium), 2014/05/01 19:55:00]

Sorry, this would be a new addition. Similar to how JavaScript can call
"postMessage" on the plugin element today:
https://code.google.com/p/chromium/codesearch#chromium/src/ppapi/examples/scr...
This API will expose a new function (in dev channel) called
postMessageAndAwaitResponse(), which has 1 parameter like postMessage, but
blocks until the plugin returns from HandleBlockingMessage...  and
postMessageAndAwaitResponse() will return a JavaScript value corresponding to
the PP_Var that HandleBlockingMessage returned.

I haven't done any of the plumbing, example, or test yet; so I don't have
anything to point you to yet.

The name is certainly up for debate; it's kind of long, but fairly descriptive.

+   * on the plugin's DOM element.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   * @param[in] message is a copy of the parameter that JavaScript provided
+   * to postMessageAndAwaitResponse.
+   * @param[in] user_data is the same as was provided by a call to
+   * RegisterMessageHandler.
+   * @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.
+   */
+  void Destroy([in] PP_Instance instance,
+               [in] mem_t user_data);
+};
+