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    * <code>message</code> can be any <code>PP_Var</code> type except
  34    * <code>PP_VARTYPE_OBJECT</code>. Array/Dictionary types are supported from
  35    * Chrome M29 onward. All var types are copied when passing them to
  36    * JavaScript.
  37    *
  38    * When passing array or dictionary <code>PP_Var</code>s, the entire reference
  39    * graph will be converted and transferred. If the reference graph has cycles,
  40    * the message will not be sent and an error will be logged to the console.
  41    *
  42    * Listeners for message events in JavaScript code will receive an object
  43    * conforming to the HTML 5 <code>MessageEvent</code> interface.
  44    * Specifically, the value of message will be contained as a property called
  45    *  data in the received <code>MessageEvent</code>.
  46    *
  47    * This messaging system is similar to the system used for listening for
  48    * messages from Web Workers. Refer to
  49    * <code>http://www.whatwg.org/specs/web-workers/current-work/</code> for
  50    * further information.
  51    *
  52    * <strong>Example:</strong>
  53    *
  54    * @code
  55    *
  56    * <body>
  57    *   <object id="plugin"
  58    *           type="application/x-ppapi-postMessage-example"/>
  59    *   <script type="text/javascript">
  60    *     var plugin = document.getElementById('plugin');
  61    *     plugin.addEventListener("message",
  62    *                             function(message) { alert(message.data); },
  63    *                             false);
  64    *   </script>
  65    * </body>
  66    *
  67    * @endcode
  68    *
  69    * The module instance then invokes PostMessage() as follows:
  70    *
  71    * @code
  72    *
  73    *  char hello_world[] = "Hello world!";
  74    *  PP_Var hello_var = ppb_var_interface->VarFromUtf8(instance,
  75    *                                                    hello_world,
  76    *                                                    sizeof(hello_world));
  77    *  ppb_messaging_interface->PostMessage(instance, hello_var); // Copies var.
  78    *  ppb_var_interface->Release(hello_var);
  79    *
  80    * @endcode
  81    *
  82    * The browser will pop-up an alert saying "Hello world!"
  83    */
  84   void PostMessage([in] PP_Instance instance, [in] PP_Var message);
  85 };
  86