Google Git
Sign in
chromium / chromium / src / f2076791a3ed010fcacba4bb4e14bc2844c6813e / . / ppapi / c / ppb_messaging.h
blob: 5048d803e023d2ee5e9b2d4d686342dd02a7e52c [file] [log] [blame]
[email protected]256513872012-01-05 15:41:52[diff] [blame]1/* Copyright (c) 2012 The Chromium Authors. All rights reserved.
[email protected]9888f132011-03-23 21:07:15[diff] [blame]2 * Use of this source code is governed by a BSD-style license that can be
3 * found in the LICENSE file.
4 */
[email protected]9b37f4802011-07-19 00:09:28[diff] [blame]5
dmichael9be4c268e2014-09-26 20:39:33[diff] [blame]6/* From ppb_messaging.idl modified Wed Sep 24 10:48:37 2014. */
[email protected]9b37f4802011-07-19 00:09:28[diff] [blame]7
[email protected]5f2cb1c92011-04-08 21:36:23[diff] [blame]8#ifndef PPAPI_C_PPB_MESSAGING_H_
9#define PPAPI_C_PPB_MESSAGING_H_
[email protected]9888f132011-03-23 21:07:15[diff] [blame]10
[email protected]9b37f4802011-07-19 00:09:28[diff] [blame]11#include "ppapi/c/pp_bool.h"
[email protected]9888f132011-03-23 21:07:15[diff] [blame]12#include "ppapi/c/pp_instance.h"
[email protected]9b37f4802011-07-19 00:09:28[diff] [blame]13#include "ppapi/c/pp_macros.h"
[email protected]4d4880322014-06-02 22:16:41[diff] [blame]14#include "ppapi/c/pp_resource.h"
[email protected]9b37f4802011-07-19 00:09:28[diff] [blame]15#include "ppapi/c/pp_stdint.h"
[email protected]9888f132011-03-23 21:07:15[diff] [blame]16#include "ppapi/c/pp_var.h"
[email protected]4d4880322014-06-02 22:16:41[diff] [blame]17#include "ppapi/c/ppp_message_handler.h"
[email protected]9888f132011-03-23 21:07:15[diff] [blame]18
[email protected]49aa13872011-08-17 20:45:57[diff] [blame]19#define PPB_MESSAGING_INTERFACE_1_0 "PPB_Messaging;1.0"
dmichael9be4c268e2014-09-26 20:39:33[diff] [blame]20#define PPB_MESSAGING_INTERFACE_1_2 "PPB_Messaging;1.2"
21#define PPB_MESSAGING_INTERFACE PPB_MESSAGING_INTERFACE_1_2
[email protected]49aa13872011-08-17 20:45:57[diff] [blame]22
[email protected]9888f132011-03-23 21:07:15[diff] [blame]23/**
24 * @file
[email protected]8dd1f5772011-07-06 15:37:28[diff] [blame]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.
[email protected]c7eb5172011-07-14 16:02:19[diff] [blame]28 */
29
[email protected]9b37f4802011-07-19 00:09:28[diff] [blame]30
[email protected]c7eb5172011-07-14 16:02:19[diff] [blame]31/**
[email protected]9888f132011-03-23 21:07:15[diff] [blame]32 * @addtogroup Interfaces
33 * @{
34 */
[email protected]9888f132011-03-23 21:07:15[diff] [blame]35/**
[email protected]8dd1f5772011-07-06 15:37:28[diff] [blame]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.
[email protected]9888f132011-03-23 21:07:15[diff] [blame]39 */
dmichael9be4c268e2014-09-26 20:39:33[diff] [blame]40struct PPB_Messaging_1_2 {
[email protected]9888f132011-03-23 21:07:15[diff] [blame]41 /**
[email protected]8dd1f5772011-07-06 15:37:28[diff] [blame]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.
[email protected]9888f132011-03-23 21:07:15[diff] [blame]45 *
[email protected]216326c2011-08-30 19:10:40[diff] [blame]46 * @param[in] instance A <code>PP_Instance</code> identifying one instance
[email protected]8dd1f5772011-07-06 15:37:28[diff] [blame]47 * of a module.
48 * @param[in] message A <code>PP_Var</code> containing the data to be sent to
49 * JavaScript.
[email protected]ce40e542013-05-22 00:48:54[diff] [blame]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
[email protected]b3e3595a9d2013-06-19 03:10:36[diff] [blame]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.
[email protected]9888f132011-03-23 21:07:15[diff] [blame]58 *
[email protected]8585fd82011-05-13 23:11:54[diff] [blame]59 * Listeners for message events in JavaScript code will receive an object
[email protected]8dd1f5772011-07-06 15:37:28[diff] [blame]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>.
[email protected]8585fd82011-05-13 23:11:54[diff] [blame]63 *
[email protected]e2c2efab2011-05-31 20:27:10[diff] [blame]64 * This messaging system is similar to the system used for listening for
65 * messages from Web Workers. Refer to
[email protected]8dd1f5772011-07-06 15:37:28[diff] [blame]66 * <code>http://www.whatwg.org/specs/web-workers/current-work/</code> for
67 * further information.
[email protected]9888f132011-03-23 21:07:15[diff] [blame]68 *
[email protected]e2c2efab2011-05-31 20:27:10[diff] [blame]69 * <strong>Example:</strong>
[email protected]9888f132011-03-23 21:07:15[diff] [blame]70 *
[email protected]ca9bc122012-03-03 00:38:02[diff] [blame]71 * @code
[email protected]9888f132011-03-23 21:07:15[diff] [blame]72 *
73 * <body>
74 * <object id="plugin"
75 * type="application/x-ppapi-postMessage-example"/>
76 * <script type="text/javascript">
[email protected]8585fd82011-05-13 23:11:54[diff] [blame]77 * var plugin = document.getElementById('plugin');
[email protected]9071a3c2012-04-27 00:46:32[diff] [blame]78 * plugin.addEventListener("message",
[email protected]8585fd82011-05-13 23:11:54[diff] [blame]79 * function(message) { alert(message.data); },
80 * false);
[email protected]9888f132011-03-23 21:07:15[diff] [blame]81 * </script>
82 * </body>
83 *
[email protected]ca9bc122012-03-03 00:38:02[diff] [blame]84 * @endcode
[email protected]9888f132011-03-23 21:07:15[diff] [blame]85 *
[email protected]e2c2efab2011-05-31 20:27:10[diff] [blame]86 * The module instance then invokes PostMessage() as follows:
87 *
[email protected]ca9bc122012-03-03 00:38:02[diff] [blame]88 * @code
[email protected]e2c2efab2011-05-31 20:27:10[diff] [blame]89 *
[email protected]9888f132011-03-23 21:07:15[diff] [blame]90 * char hello_world[] = "Hello world!";
[email protected]a47a6fe2011-06-27 07:33:51[diff] [blame]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);
[email protected]9888f132011-03-23 21:07:15[diff] [blame]96 *
[email protected]ca9bc122012-03-03 00:38:02[diff] [blame]97 * @endcode
[email protected]e2c2efab2011-05-31 20:27:10[diff] [blame]98 *
99 * The browser will pop-up an alert saying "Hello world!"
[email protected]9888f132011-03-23 21:07:15[diff] [blame]100 */
101 void (*PostMessage)(PP_Instance instance, struct PP_Var message);
[email protected]4d4880322014-06-02 22:16:41[diff] [blame]102 /**
[email protected]4d4880322014-06-02 22:16:41[diff] [blame]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.
[email protected]e87640bd2014-06-18 16:44:00[diff] [blame]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.
[email protected]4d4880322014-06-02 22:16:41[diff] [blame]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,
Dave Michael970fa0cf2014-09-17 20:56:10[diff] [blame]140 const struct PPP_MessageHandler_0_2* handler,
[email protected]4d4880322014-06-02 22:16:41[diff] [blame]141 PP_Resource message_loop);
142 /**
[email protected]4d4880322014-06-02 22:16:41[diff] [blame]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
dmichael9be4c268e2014-09-26 20:39:33[diff] [blame]160typedef struct PPB_Messaging_1_2 PPB_Messaging;
161
[email protected]4d4880322014-06-02 22:16:41[diff] [blame]162struct PPB_Messaging_1_0 {
163 void (*PostMessage)(PP_Instance instance, struct PP_Var message);
[email protected]9888f132011-03-23 21:07:15[diff] [blame]164};
165/**
166 * @}
167 */
168
[email protected]5f2cb1c92011-04-08 21:36:23[diff] [blame]169#endif /* PPAPI_C_PPB_MESSAGING_H_ */
[email protected]9b37f4802011-07-19 00:09:28[diff] [blame]170