PPAPI: Add dev synchronous JS->Plugin messaging API

ppapi/c/ppp_message_handler.h

+/* 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.
+ */
+
+/* From ppp_message_handler.idl modified Thu May  1 13:44:17 2014. */
+
+#ifndef PPAPI_C_PPP_MESSAGE_HANDLER_H_
+#define PPAPI_C_PPP_MESSAGE_HANDLER_H_
+
+#include "ppapi/c/pp_bool.h"
+#include "ppapi/c/pp_instance.h"
+#include "ppapi/c/pp_macros.h"
+#include "ppapi/c/pp_stdint.h"
+#include "ppapi/c/pp_var.h"
+
+/**
+ * @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.
+ */
+
+
+/**
+ * @addtogroup Interfaces
+ * @{
+ */
+/**
+ * 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

[jvoung (off chromium), 2014/05/01 21:29:06]

Just checking: Will there be any direct nexe <-> IRT boundary crossing between
these methods? E.g., The ppapi proxy calls the HandleMessage function supplied
by the nexe directly, passing a PP_Var by value?

The methods returned by PPP_GetInterface are shimmed to fix up calling
conventions, but it looks like these won't be?

[dmichael (off chromium), 2014/05/02 18:03:42]

Yes, thanks for bringing it up...
Correct, right now. I'm hoping there might be an explicit way for me to use the
PNaCl Shim wrapper that gets generated for PPP_MessageHandler directly. I was
hoping to keep the new HandleMessage and HandleBlockingMessage consistent with
the old HandleMessage, in that they pass a PP_Var by value.

I *can* also make it work just by passing the PP_Var by pointer. I think in the
near-term I might just do that.

+ * must be passed as a parameter to PPB_Messaging::RegisterMessageHandler.
+ */
+struct PPP_MessageHandler_0_1 { /* dev */
+  /**
+   *  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)(PP_Instance instance,
+                        const void* user_data,
+                        struct 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.
+   */
+  struct PP_Var (*HandleBlockingMessage)(PP_Instance instance,
+                                         const void* user_data,
+                                         struct 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)(PP_Instance instance, const void* user_data);
+};
+/**
+ * @}
+ */
+
+#endif  /* PPAPI_C_PPP_MESSAGE_HANDLER_H_ */
+