15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 61320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci/* From ppb_messaging.idl modified Wed Sep 24 10:48:37 2014. */ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef PPAPI_C_PPB_MESSAGING_H_ 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PPAPI_C_PPB_MESSAGING_H_ 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_bool.h" 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_instance.h" 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_macros.h" 1446d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#include "ppapi/c/pp_resource.h" 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_stdint.h" 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_var.h" 1746d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)#include "ppapi/c/ppp_message_handler.h" 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PPB_MESSAGING_INTERFACE_1_0 "PPB_Messaging;1.0" 201320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#define PPB_MESSAGING_INTERFACE_1_2 "PPB_Messaging;1.2" 211320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#define PPB_MESSAGING_INTERFACE PPB_MESSAGING_INTERFACE_1_2 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @file 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * This file defines the <code>PPB_Messaging</code> interface implemented 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * by the browser for sending messages to DOM elements associated with a 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * specific module instance. 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @addtogroup Interfaces 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @{ 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The <code>PPB_Messaging</code> interface is implemented by the browser 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * and is related to sending messages to JavaScript message event listeners on 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the DOM element associated with specific module instance. 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 401320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tuccistruct PPB_Messaging_1_2 { 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /** 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * PostMessage() asynchronously invokes any listeners for message events on 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * the DOM element for the given module instance. A call to PostMessage() 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * will not block while the message is processed. 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] instance A <code>PP_Instance</code> identifying one instance 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * of a module. 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @param[in] message A <code>PP_Var</code> containing the data to be sent to 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * JavaScript. 5090dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * <code>message</code> can be any <code>PP_Var</code> type except 5190dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * <code>PP_VARTYPE_OBJECT</code>. Array/Dictionary types are supported from 5290dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * Chrome M29 onward. All var types are copied when passing them to 5390dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * JavaScript. 5490dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * 5590dce4d38c5ff5333bea97d859d4e484e27edf0cTorne (Richard Coles) * When passing array or dictionary <code>PP_Var</code>s, the entire reference 567d4cd473f85ac64c3747c96c277f9e506a0d2246Torne (Richard Coles) * graph will be converted and transferred. If the reference graph has cycles, 577d4cd473f85ac64c3747c96c277f9e506a0d2246Torne (Richard Coles) * the message will not be sent and an error will be logged to the console. 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Listeners for message events in JavaScript code will receive an object 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * conforming to the HTML 5 <code>MessageEvent</code> interface. 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Specifically, the value of message will be contained as a property called 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * data in the received <code>MessageEvent</code>. 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * This messaging system is similar to the system used for listening for 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * messages from Web Workers. Refer to 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <code>http://www.whatwg.org/specs/web-workers/current-work/</code> for 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * further information. 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <strong>Example:</strong> 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @code 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <body> 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <object id="plugin" 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * type="application/x-ppapi-postMessage-example"/> 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * <script type="text/javascript"> 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * var plugin = document.getElementById('plugin'); 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * plugin.addEventListener("message", 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * function(message) { alert(message.data); }, 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * false); 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * </script> 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * </body> 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @endcode 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The module instance then invokes PostMessage() as follows: 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @code 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * char hello_world[] = "Hello world!"; 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * PP_Var hello_var = ppb_var_interface->VarFromUtf8(instance, 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * hello_world, 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * sizeof(hello_world)); 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * ppb_messaging_interface->PostMessage(instance, hello_var); // Copies var. 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * ppb_var_interface->Release(hello_var); 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @endcode 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The browser will pop-up an alert saying "Hello world!" 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void (*PostMessage)(PP_Instance instance, struct PP_Var message); 10246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) /** 10346d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * Registers a handler for receiving messages from JavaScript. If a handler 10446d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * is registered this way, it will replace PPP_Messaging, and all messages 10546d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * sent from JavaScript via postMessage and postMessageAndAwaitResponse will 10646d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * be dispatched to <code>handler</code>. 10746d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * 10846d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * The function calls will be dispatched via <code>message_loop</code>. This 10946d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * means that the functions will be invoked on the thread to which 11046d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * <code>message_loop</code> is attached, when <code>message_loop</code> is 11146d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * run. It is illegal to pass the main thread message loop; 11246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * RegisterMessageHandler will return PP_ERROR_WRONG_THREAD in that case. 113f8ee788a64d60abd8f2d742a5fdedde054ecd910Torne (Richard Coles) * If you quit <code>message_loop</code> before calling Unregister(), 114f8ee788a64d60abd8f2d742a5fdedde054ecd910Torne (Richard Coles) * the browser will not be able to call functions in the plugin's message 115f8ee788a64d60abd8f2d742a5fdedde054ecd910Torne (Richard Coles) * handler any more. That could mean missing some messages or could cause a 116f8ee788a64d60abd8f2d742a5fdedde054ecd910Torne (Richard Coles) * leak if you depend on Destroy() to free hander data. So you should, 117f8ee788a64d60abd8f2d742a5fdedde054ecd910Torne (Richard Coles) * whenever possible, Unregister() the handler prior to quitting its event 118f8ee788a64d60abd8f2d742a5fdedde054ecd910Torne (Richard Coles) * loop. 11946d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * 12046d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * Attempting to register a message handler when one is already registered 12146d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * will cause the current MessageHandler to be unregistered and replaced. In 12246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * that case, no messages will be sent to the "default" message handler 12346d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * (PPP_Messaging). Messages will stop arriving at the prior message handler 12446d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * and will begin to be dispatched at the new message handler. 12546d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * 12646d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * @param[in] instance A <code>PP_Instance</code> identifying one instance 12746d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * of a module. 12846d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * @param[in] user_data A pointer the plugin may choose to use when handling 12946d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * calls to functions within PPP_MessageHandler. The browser will pass this 13046d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * same pointer when invoking functions within PPP_MessageHandler. 13146d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * @param[in] handler The plugin-provided set of functions for handling 13246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * messages. 13346d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * @param[in] message_loop Represents the message loop on which 13446d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * PPP_MessageHandler functions should be invoked. 13546d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * @return PP_OK on success, or an error from pp_errors.h. 13646d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) */ 13746d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) int32_t (*RegisterMessageHandler)( 13846d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) PP_Instance instance, 13946d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) void* user_data, 1401320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci const struct PPP_MessageHandler_0_2* handler, 14146d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) PP_Resource message_loop); 14246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) /** 14346d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * Unregisters the current message handler for <code>instance</code> if one 14446d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * is registered. After this call, the message handler (if one was 14546d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * registered) will have "Destroy" called on it and will receive no further 14646d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * messages after that point. After that point, all messages sent from 14746d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * JavaScript using postMessage() will be dispatched to PPP_Messaging (if 14846d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * the plugin supports PPP_MESSAGING_INTERFACE). Attempts to call 14946d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * postMessageAndAwaitResponse() from JavaScript will fail. 15046d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * 15146d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * Attempting to unregister a message handler when none is registered has no 15246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * effect. 15346d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * 15446d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * @param[in] instance A <code>PP_Instance</code> identifying one instance 15546d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) * of a module. 15646d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) */ 15746d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) void (*UnregisterMessageHandler)(PP_Instance instance); 15846d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)}; 15946d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) 1601320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tuccitypedef struct PPB_Messaging_1_2 PPB_Messaging; 1611320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 16246d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles)struct PPB_Messaging_1_0 { 16346d4c2bc3267f3f028f39e7e311b0f89aba2e4fdTorne (Richard Coles) void (*PostMessage)(PP_Instance instance, struct PP_Var message); 1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/** 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * @} 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */ 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif /* PPAPI_C_PPB_MESSAGING_H_ */ 1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 171