Pepper_47_C_interfaces
ppb_messaging.h
Go to the documentation of this file.
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 Thu Oct 20 13:57:04 2016. */
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_2 "PPB_Messaging;1.2"
21 #define PPB_MESSAGING_INTERFACE PPB_MESSAGING_INTERFACE_1_2
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_2 {
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_2* 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 typedef struct PPB_Messaging_1_2 PPB_Messaging;
161 
162 struct PPB_Messaging_1_0 {
163  void (*PostMessage)(PP_Instance instance, struct PP_Var message);
164 };
165 /**
166  * @}
167  */
168 
169 #endif /* PPAPI_C_PPB_MESSAGING_H_ */
170 
pp_macros.h
PPP_MessageHandler_0_2
Definition: ppp_message_handler.h:39
PPB_Messaging_1_2::RegisterMessageHandler
int32_t(* RegisterMessageHandler)(PP_Instance instance, void *user_data, const struct PPP_MessageHandler_0_2 *handler, PP_Resource message_loop)
Definition: ppb_messaging.h:137
pp_bool.h
pp_instance.h
PP_Resource
int32_t PP_Resource
Definition: pp_resource.h:40
ppp_message_handler.h
PPB_Messaging_1_2
Definition: ppb_messaging.h:40
PPB_Messaging_1_2::PostMessage
void(* PostMessage)(PP_Instance instance, struct PP_Var message)
Definition: ppb_messaging.h:101
pp_resource.h
PPB_Messaging_1_0::PostMessage
void(* PostMessage)(PP_Instance instance, struct PP_Var message)
Definition: ppb_messaging.h:163
PP_Var
Definition: pp_var.h:166
PPB_Messaging_1_2::UnregisterMessageHandler
void(* UnregisterMessageHandler)(PP_Instance instance)
Definition: ppb_messaging.h:157
pp_stdint.h
pp_var.h
PP_Instance
int32_t PP_Instance
Definition: pp_instance.h:34
PPB_Messaging_1_0
Definition: ppb_messaging.h:162
Generated on Wed Apr 5 2017 11:09:16 for Pepper_47_C_interfaces by   doxygen 1.8.6