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 Wed Jun 5 10:32:59 2013. */ 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_stdint.h" 15 #include "ppapi/c/pp_var.h" 16 17 #define PPB_MESSAGING_INTERFACE_1_0 "PPB_Messaging;1.0" 18 #define PPB_MESSAGING_INTERFACE PPB_MESSAGING_INTERFACE_1_0 19 20 /** 21 * @file 22 * This file defines the <code>PPB_Messaging</code> interface implemented 23 * by the browser for sending messages to DOM elements associated with a 24 * specific module instance. 25 */ 26 27 28 /** 29 * @addtogroup Interfaces 30 * @{ 31 */ 32 /** 33 * The <code>PPB_Messaging</code> interface is implemented by the browser 34 * and is related to sending messages to JavaScript message event listeners on 35 * the DOM element associated with specific module instance. 36 */ 37 struct PPB_Messaging_1_0 { 38 /** 39 * PostMessage() asynchronously invokes any listeners for message events on 40 * the DOM element for the given module instance. A call to PostMessage() 41 * will not block while the message is processed. 42 * 43 * @param[in] instance A <code>PP_Instance</code> identifying one instance 44 * of a module. 45 * @param[in] message A <code>PP_Var</code> containing the data to be sent to 46 * JavaScript. 47 * <code>message</code> can be any <code>PP_Var</code> type except 48 * <code>PP_VARTYPE_OBJECT</code>. Array/Dictionary types are supported from 49 * Chrome M29 onward. All var types are copied when passing them to 50 * JavaScript. 51 * 52 * When passing array or dictionary <code>PP_Var</code>s, the entire reference 53 * graph will be converted and transferred. If the reference graph has cycles, 54 * the message will not be sent and an error will be logged to the console. 55 * 56 * Listeners for message events in JavaScript code will receive an object 57 * conforming to the HTML 5 <code>MessageEvent</code> interface. 58 * Specifically, the value of message will be contained as a property called 59 * data in the received <code>MessageEvent</code>. 60 * 61 * This messaging system is similar to the system used for listening for 62 * messages from Web Workers. Refer to 63 * <code>http://www.whatwg.org/specs/web-workers/current-work/</code> for 64 * further information. 65 * 66 * <strong>Example:</strong> 67 * 68 * @code 69 * 70 * <body> 71 * <object id="plugin" 72 * type="application/x-ppapi-postMessage-example"/> 73 * <script type="text/javascript"> 74 * var plugin = document.getElementById('plugin'); 75 * plugin.addEventListener("message", 76 * function(message) { alert(message.data); }, 77 * false); 78 * </script> 79 * </body> 80 * 81 * @endcode 82 * 83 * The module instance then invokes PostMessage() as follows: 84 * 85 * @code 86 * 87 * char hello_world[] = "Hello world!"; 88 * PP_Var hello_var = ppb_var_interface->VarFromUtf8(instance, 89 * hello_world, 90 * sizeof(hello_world)); 91 * ppb_messaging_interface->PostMessage(instance, hello_var); // Copies var. 92 * ppb_var_interface->Release(hello_var); 93 * 94 * @endcode 95 * 96 * The browser will pop-up an alert saying "Hello world!" 97 */ 98 void (*PostMessage)(PP_Instance instance, struct PP_Var message); 99 }; 100 101 typedef struct PPB_Messaging_1_0 PPB_Messaging; 102 /** 103 * @} 104 */ 105 106 #endif /* PPAPI_C_PPB_MESSAGING_H_ */ 107 108