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