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 label Chrome { 13 M14 = 1.0, 14 M39 = 1.2 15 }; 16 17 /** 18 * The <code>PPB_Messaging</code> interface is implemented by the browser 19 * and is related to sending messages to JavaScript message event listeners on 20 * the DOM element associated with specific module instance. 21 */ 22 interface PPB_Messaging { 23 /** 24 * PostMessage() asynchronously invokes any listeners for message events on 25 * the DOM element for the given module instance. A call to PostMessage() 26 * will not block while the message is processed. 27 * 28 * @param[in] instance A <code>PP_Instance</code> identifying one instance 29 * of a module. 30 * @param[in] message A <code>PP_Var</code> containing the data to be sent to 31 * JavaScript. 32 * <code>message</code> can be any <code>PP_Var</code> type except 33 * <code>PP_VARTYPE_OBJECT</code>. Array/Dictionary types are supported from 34 * Chrome M29 onward. All var types are copied when passing them to 35 * JavaScript. 36 * 37 * When passing array or dictionary <code>PP_Var</code>s, the entire reference 38 * graph will be converted and transferred. If the reference graph has cycles, 39 * the message will not be sent and an error will be logged to the console. 40 * 41 * Listeners for message events in JavaScript code will receive an object 42 * conforming to the HTML 5 <code>MessageEvent</code> interface. 43 * Specifically, the value of message will be contained as a property called 44 * data in the received <code>MessageEvent</code>. 45 * 46 * This messaging system is similar to the system used for listening for 47 * messages from Web Workers. Refer to 48 * <code>http://www.whatwg.org/specs/web-workers/current-work/</code> for 49 * further information. 50 * 51 * <strong>Example:</strong> 52 * 53 * @code 54 * 55 * <body> 56 * <object id="plugin" 57 * type="application/x-ppapi-postMessage-example"/> 58 * <script type="text/javascript"> 59 * var plugin = document.getElementById('plugin'); 60 * plugin.addEventListener("message", 61 * function(message) { alert(message.data); }, 62 * false); 63 * </script> 64 * </body> 65 * 66 * @endcode 67 * 68 * The module instance then invokes PostMessage() as follows: 69 * 70 * @code 71 * 72 * char hello_world[] = "Hello world!"; 73 * PP_Var hello_var = ppb_var_interface->VarFromUtf8(instance, 74 * hello_world, 75 * sizeof(hello_world)); 76 * ppb_messaging_interface->PostMessage(instance, hello_var); // Copies var. 77 * ppb_var_interface->Release(hello_var); 78 * 79 * @endcode 80 * 81 * The browser will pop-up an alert saying "Hello world!" 82 */ 83 [version=1.0] 84 void PostMessage([in] PP_Instance instance, [in] PP_Var message); 85 86 /** 87 * Registers a handler for receiving messages from JavaScript. If a handler 88 * is registered this way, it will replace PPP_Messaging, and all messages 89 * sent from JavaScript via postMessage and postMessageAndAwaitResponse will 90 * be dispatched to <code>handler</code>. 91 * 92 * The function calls will be dispatched via <code>message_loop</code>. This 93 * means that the functions will be invoked on the thread to which 94 * <code>message_loop</code> is attached, when <code>message_loop</code> is 95 * run. It is illegal to pass the main thread message loop; 96 * RegisterMessageHandler will return PP_ERROR_WRONG_THREAD in that case. 97 * If you quit <code>message_loop</code> before calling Unregister(), 98 * the browser will not be able to call functions in the plugin's message 99 * handler any more. That could mean missing some messages or could cause a 100 * leak if you depend on Destroy() to free hander data. So you should, 101 * whenever possible, Unregister() the handler prior to quitting its event 102 * loop. 103 * 104 * Attempting to register a message handler when one is already registered 105 * will cause the current MessageHandler to be unregistered and replaced. In 106 * that case, no messages will be sent to the "default" message handler 107 * (PPP_Messaging). Messages will stop arriving at the prior message handler 108 * and will begin to be dispatched at the new message handler. 109 * 110 * @param[in] instance A <code>PP_Instance</code> identifying one instance 111 * of a module. 112 * @param[in] user_data A pointer the plugin may choose to use when handling 113 * calls to functions within PPP_MessageHandler. The browser will pass this 114 * same pointer when invoking functions within PPP_MessageHandler. 115 * @param[in] handler The plugin-provided set of functions for handling 116 * messages. 117 * @param[in] message_loop Represents the message loop on which 118 * PPP_MessageHandler functions should be invoked. 119 * @return PP_OK on success, or an error from pp_errors.h. 120 */ 121 [version=1.2] 122 int32_t RegisterMessageHandler([in] PP_Instance instance, 123 [inout] mem_t user_data, 124 [in] PPP_MessageHandler handler, 125 [in] PP_Resource message_loop); 126 /** 127 * Unregisters the current message handler for <code>instance</code> if one 128 * is registered. After this call, the message handler (if one was 129 * registered) will have "Destroy" called on it and will receive no further 130 * messages after that point. After that point, all messages sent from 131 * JavaScript using postMessage() will be dispatched to PPP_Messaging (if 132 * the plugin supports PPP_MESSAGING_INTERFACE). Attempts to call 133 * postMessageAndAwaitResponse() from JavaScript will fail. 134 * 135 * Attempting to unregister a message handler when none is registered has no 136 * effect. 137 * 138 * @param[in] instance A <code>PP_Instance</code> identifying one instance 139 * of a module. 140 */ 141 [version=1.2] 142 void UnregisterMessageHandler([in] PP_Instance instance); 143 }; 144 145
