ppapi/api/ppb_messaging.idl

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * This file defines the <code>PPB_Messaging</code> interface implemented
   8  * by the browser for sending messages to DOM elements associated with a
   9  * specific module instance.
  10  */
  11
  12 [generate_thunk]
  13
  14 label Chrome {
  15   M14 = 1.0
  16 };
  17
  18 /**
  19  * The <code>PPB_Messaging</code> interface is implemented by the browser
  20  * and is related to sending messages to JavaScript message event listeners on
  21  * the DOM element associated with specific module instance.
  22  */
  23 interface PPB_Messaging {
  24   /**
  25    * PostMessage() asynchronously invokes any listeners for message events on
  26    * the DOM element for the given module instance. A call to PostMessage()
  27    * will not block while the message is processed.
  28    *
  29    * @param[in] instance A <code>PP_Instance</code> identifying one instance
  30    * of a module.
  31    * @param[in] message A <code>PP_Var</code> containing the data to be sent to
  32    * JavaScript.
  33    * Message can have a numeric, boolean, or string value; arrays and
  34    * dictionaries are not yet supported. Ref-counted var types are copied, and
  35    * are therefore not shared between the module instance and the browser.
  36    *
  37    * Listeners for message events in JavaScript code will receive an object
  38    * conforming to the HTML 5 <code>MessageEvent</code> interface.
  39    * Specifically, the value of message will be contained as a property called
  40    *  data in the received <code>MessageEvent</code>.
  41    *
  42    * This messaging system is similar to the system used for listening for
  43    * messages from Web Workers. Refer to
  44    * <code>http://www.whatwg.org/specs/web-workers/current-work/</code> for
  45    * further information.
  46    *
  47    * <strong>Example:</strong>
  48    *
  49    * @code
  50    *
  51    * <body>
  52    *   <object id="plugin"
  53    *           type="application/x-ppapi-postMessage-example"/>
  54    *   <script type="text/javascript">
  55    *     var plugin = document.getElementById('plugin');
  56    *     plugin.addEventListener("message",
  57    *                             function(message) { alert(message.data); },
  58    *                             false);
  59    *   </script>
  60    * </body>
  61    *
  62    * @endcode
  63    *
  64    * The module instance then invokes PostMessage() as follows:
  65    *
  66    * @code
  67    *
  68    *  char hello_world[] = "Hello world!";
  69    *  PP_Var hello_var = ppb_var_interface->VarFromUtf8(instance,
  70    *                                                    hello_world,
  71    *                                                    sizeof(hello_world));
  72    *  ppb_messaging_interface->PostMessage(instance, hello_var); // Copies var.
  73    *  ppb_var_interface->Release(hello_var);
  74    *
  75    * @endcode
  76    *
  77    * The browser will pop-up an alert saying "Hello world!"
  78    */
  79   void PostMessage([in] PP_Instance instance, [in] PP_Var message);
  80 };
  81