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