1 files changed, 82 insertions, 0 deletions
diff --git a/ppapi/api/ppb_messaging.idl b/ppapi/api/ppb_messaging.idl
new file mode 100644
index 0000000..bbcff58
--- /dev/null
+++ b/ppapi/api/ppb_messaging.idl
@@ -0,0 +1,82 @@
+/* Copyright (c) 2011 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 {
+  M13 = 0.1,
+  M14 = 1.0
+};
+
+/**
+ * The <code>PPB_Messaging</code> interface is implemented by the browser
+ * and is related to sending messages to JavaScript message event listeners on
+ * the DOM element associated with specific module instance.
+ */
+[version=0.1]
+interface PPB_Messaging {
+  /**
+   * PostMessage() asynchronously invokes any listeners for message events on
+   * the DOM element for the given module instance. A call to PostMessage()
+   * will not block while the message is processed.
+   *
+   * @param[in] instance A <code>PP_Instance</code> indentifying one instance
+   * of a module.
+   * @param[in] message A <code>PP_Var</code> containing the data to be sent to
+   * JavaScript.
+   * Message can have a numeric, boolean, or string value; arrays and
+   * dictionaries are not yet supported. Ref-counted var types are copied, and
+   * are therefore not shared between the module instance and the browser.
+   *
+   * Listeners for message events in JavaScript code will receive an object
+   * conforming to the HTML 5 <code>MessageEvent</code> interface.
+   * Specifically, the value of message will be contained as a property called
+   *  data in the received <code>MessageEvent</code>.
+   *
+   * This messaging system is similar to the system used for listening for
+   * messages from Web Workers. Refer to
+   * <code>http://www.whatwg.org/specs/web-workers/current-work/</code> for
+   * further information.
+   *
+   * <strong>Example:</strong>
+   *
+   * @code
+   *
+   * <body>
+   *   <object id="plugin"
+   *           type="application/x-ppapi-postMessage-example"/>
+   *   <script type="text/javascript">
+   *     var plugin = document.getElementById('plugin');
+   *     plugin.AddEventListener("message",
+   *                             function(message) { alert(message.data); },
+   *                             false);
+   *   </script>
+   * </body>
+   *
+   * @endcode
+   *
+   * The module instance then invokes PostMessage() as follows:
+   *
+   * @code
+   *
+   *
+   *  char hello_world[] = "Hello world!";
+   *  PP_Var hello_var = ppb_var_interface->VarFromUtf8(instance,
+   *                                                    hello_world,
+   *                                                    sizeof(hello_world));
+   *  ppb_messaging_interface->PostMessage(instance, hello_var); // Copies var.
+   *  ppb_var_interface->Release(hello_var);
+   *
+   * @endcode
+   *
+   * The browser will pop-up an alert saying "Hello world!"
+   */
+  void PostMessage([in] PP_Instance instance, [in] PP_Var message);
+};
+