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 14label 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 */ 23interface 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