Home | History | Annotate | Download | only in api 
      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 
     87