| {{+bindTo:partials.standard_nacl_api}} |
| <h1>PPB_Messaging Struct Reference</h1> |
| <div id="doxygen-ref"> |
| {{- dummy div to appease doxygen -}} |
| <div> |
| <!-- Generated by Doxygen 1.7.6.1 --> |
| |
| |
| </div> |
| <!--header--> |
| <div class="contents"> |
| <!-- doxytag: class="PPB_Messaging" --><h2> |
| Data Fields</h2><table class="memberdecls"> |
| |
| <tr><td class="memItemLeft" align="right" valign="top">void(* </td><td class="memItemRight" valign="bottom"><a class="el" href="struct_p_p_b___messaging__1__2.html#a3ad76397ae4e47e768a6b12d8dc0ea11">PostMessage</a> )(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance, struct <a class="el" href="struct_p_p___var.html">PP_Var</a> message)</td></tr> |
| <tr><td class="memItemLeft" align="right" valign="top">int32_t(* </td><td class="memItemRight" valign="bottom"><a class="el" href="struct_p_p_b___messaging__1__2.html#ae5abee73dc21a290514f7f3554a7e895">RegisterMessageHandler</a> )(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance, void *user_data, const struct <a class="el" href="struct_p_p_p___message_handler__0__2.html">PPP_MessageHandler</a> *handler, <a class="el" href="group___typedefs.html#gafdc3895ee80f4750d0d95ae1b677e9b7">PP_Resource</a> message_loop)</td></tr> |
| <tr><td class="memItemLeft" align="right" valign="top">void(* </td><td class="memItemRight" valign="bottom"><a class="el" href="struct_p_p_b___messaging__1__2.html#a898754602cac55875f298938e18bf017">UnregisterMessageHandler</a> )(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance)</td></tr> |
| </table> |
| <hr /><a name="details" id="details"></a><h2>Detailed Description</h2> |
| <div class="textblock"><p>The <code>PPB_Messaging</code> interface is implemented by the browser and is related to sending messages to JavaScript message event listeners on the DOM element associated with specific module instance. </p> |
| </div><hr /><h2>Field Documentation</h2> |
| <a class="anchor" id="a3ad76397ae4e47e768a6b12d8dc0ea11"></a><!-- doxytag: member="PPB_Messaging::PostMessage" ref="a3ad76397ae4e47e768a6b12d8dc0ea11" args=")(PP_Instance instance, struct PP_Var message)" --> |
| <div class="memitem"> |
| <div class="memproto"> |
| <table class="memname"> |
| <tr> |
| <td class="memname">void(* <a class="el" href="struct_p_p_b___messaging__1__2.html#a3ad76397ae4e47e768a6b12d8dc0ea11">PPB_Messaging::PostMessage</a>)(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance, struct <a class="el" href="struct_p_p___var.html">PP_Var</a> message)</td> |
| </tr> |
| </table> |
| </div> |
| <div class="memdoc"> |
| <p><a class="el" href="struct_p_p_b___messaging__1__2.html#a3ad76397ae4e47e768a6b12d8dc0ea11" title="PostMessage() asynchronously invokes any listeners for message events on the DOM element for the give...">PostMessage()</a> asynchronously invokes any listeners for message events on the DOM element for the given module instance. </p> |
| <p>A call to <a class="el" href="struct_p_p_b___messaging__1__2.html#a3ad76397ae4e47e768a6b12d8dc0ea11" title="PostMessage() asynchronously invokes any listeners for message events on the DOM element for the give...">PostMessage()</a> will not block while the message is processed.</p> |
| <dl class="params"><dt><b>Parameters:</b></dt><dd> |
| <table class="params"> |
| <tr><td class="paramdir">[in]</td><td class="paramname">instance</td><td>A <code>PP_Instance</code> identifying one instance of a module. </td></tr> |
| <tr><td class="paramdir">[in]</td><td class="paramname">message</td><td>A <code><a class="el" href="struct_p_p___var.html" title="The PP_VAR struct is a variant data type and can contain any value of one of the types named in the P...">PP_Var</a></code> containing the data to be sent to JavaScript. <code>message</code> can be any <code><a class="el" href="struct_p_p___var.html" title="The PP_VAR struct is a variant data type and can contain any value of one of the types named in the P...">PP_Var</a></code> type except <code>PP_VARTYPE_OBJECT</code>. Array/Dictionary types are supported from Chrome M29 onward. All var types are copied when passing them to JavaScript.</td></tr> |
| </table> |
| </dd> |
| </dl> |
| <p>When passing array or dictionary <code><a class="el" href="struct_p_p___var.html" title="The PP_VAR struct is a variant data type and can contain any value of one of the types named in the P...">PP_Var</a></code>s, the entire reference graph will be converted and transferred. If the reference graph has cycles, the message will not be sent and an error will be logged to the console.</p> |
| <p>Listeners for message events in JavaScript code will receive an object conforming to the HTML 5 <code>MessageEvent</code> interface. Specifically, the value of message will be contained as a property called data in the received <code>MessageEvent</code>.</p> |
| <p>This messaging system is similar to the system used for listening for messages from Web Workers. Refer to <code><a href="http://www.whatwg.org/specs/web-workers/current-work/">http://www.whatwg.org/specs/web-workers/current-work/</a></code> for further information.</p> |
| <p><b>Example:</b></p> |
| <div class="fragment"><pre class="fragment"> <body> |
| <<span class="keywordtype">object</span> <span class="keywordtype">id</span>=<span class="stringliteral">"plugin"</span> |
| type=<span class="stringliteral">"application/x-ppapi-postMessage-example"</span>/> |
| <script type=<span class="stringliteral">"text/javascript"</span>> |
| var plugin = document.getElementById(<span class="stringliteral">'plugin'</span>); |
| plugin.addEventListener(<span class="stringliteral">"message"</span>, |
| <span class="keyword">function</span>(message) { alert(message.data); }, |
| <span class="keyword">false</span>); |
| </script> |
| </body> |
| </pre></div><p>The module instance then invokes <a class="el" href="struct_p_p_b___messaging__1__2.html#a3ad76397ae4e47e768a6b12d8dc0ea11" title="PostMessage() asynchronously invokes any listeners for message events on the DOM element for the give...">PostMessage()</a> as follows:</p> |
| <div class="fragment"><pre class="fragment"> <span class="keywordtype">char</span> hello_world[] = <span class="stringliteral">"Hello world!"</span>; |
| <a class="code" href="struct_p_p___var.html" title="The PP_VAR struct is a variant data type and can contain any value of one of the types named in the P...">PP_Var</a> hello_var = ppb_var_interface->VarFromUtf8(instance, |
| hello_world, |
| <span class="keyword">sizeof</span>(hello_world)); |
| ppb_messaging_interface->PostMessage(instance, hello_var); <span class="comment">// Copies var.</span> |
| ppb_var_interface->Release(hello_var); |
| </pre></div><p>The browser will pop-up an alert saying "Hello world!" </p> |
| </div> |
| </div> |
| <a class="anchor" id="ae5abee73dc21a290514f7f3554a7e895"></a><!-- doxytag: member="PPB_Messaging::RegisterMessageHandler" ref="ae5abee73dc21a290514f7f3554a7e895" args=")(PP_Instance instance, void *user_data, const struct PPP_MessageHandler *handler, PP_Resource message_loop)" --> |
| <div class="memitem"> |
| <div class="memproto"> |
| <table class="memname"> |
| <tr> |
| <td class="memname">int32_t(* <a class="el" href="struct_p_p_b___messaging__1__2.html#ae5abee73dc21a290514f7f3554a7e895">PPB_Messaging::RegisterMessageHandler</a>)(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance, void *user_data, const struct <a class="el" href="struct_p_p_p___message_handler__0__2.html">PPP_MessageHandler</a> *handler, <a class="el" href="group___typedefs.html#gafdc3895ee80f4750d0d95ae1b677e9b7">PP_Resource</a> message_loop)</td> |
| </tr> |
| </table> |
| </div> |
| <div class="memdoc"> |
| <p>Registers a handler for receiving messages from JavaScript. </p> |
| <p>If a handler is registered this way, it will replace PPP_Messaging, and all messages sent from JavaScript via postMessage and postMessageAndAwaitResponse will be dispatched to <code>handler</code>.</p> |
| <p>The function calls will be dispatched via <code>message_loop</code>. This means that the functions will be invoked on the thread to which <code>message_loop</code> is attached, when <code>message_loop</code> is run. It is illegal to pass the main thread message loop; RegisterMessageHandler will return PP_ERROR_WRONG_THREAD in that case. If you quit <code>message_loop</code> before calling Unregister(), the browser will not be able to call functions in the plugin's message handler any more. That could mean missing some messages or could cause a leak if you depend on Destroy() to free hander data. So you should, whenever possible, Unregister() the handler prior to quitting its event loop.</p> |
| <p>Attempting to register a message handler when one is already registered will cause the current MessageHandler to be unregistered and replaced. In that case, no messages will be sent to the "default" message handler (PPP_Messaging). Messages will stop arriving at the prior message handler and will begin to be dispatched at the new message handler.</p> |
| <dl class="params"><dt><b>Parameters:</b></dt><dd> |
| <table class="params"> |
| <tr><td class="paramdir">[in]</td><td class="paramname">instance</td><td>A <code>PP_Instance</code> identifying one instance of a module. </td></tr> |
| <tr><td class="paramdir">[in]</td><td class="paramname">user_data</td><td>A pointer the plugin may choose to use when handling calls to functions within PPP_MessageHandler. The browser will pass this same pointer when invoking functions within PPP_MessageHandler. </td></tr> |
| <tr><td class="paramdir">[in]</td><td class="paramname">handler</td><td>The plugin-provided set of functions for handling messages. </td></tr> |
| <tr><td class="paramdir">[in]</td><td class="paramname">message_loop</td><td>Represents the message loop on which PPP_MessageHandler functions should be invoked. </td></tr> |
| </table> |
| </dd> |
| </dl> |
| <dl class="return"><dt><b>Returns:</b></dt><dd>PP_OK on success, or an error from <a class="el" href="pp__errors_8h.html" title="This file defines an enumeration of all PPAPI error codes.">pp_errors.h</a>. </dd></dl> |
| </div> |
| </div> |
| <a class="anchor" id="a898754602cac55875f298938e18bf017"></a><!-- doxytag: member="PPB_Messaging::UnregisterMessageHandler" ref="a898754602cac55875f298938e18bf017" args=")(PP_Instance instance)" --> |
| <div class="memitem"> |
| <div class="memproto"> |
| <table class="memname"> |
| <tr> |
| <td class="memname">void(* <a class="el" href="struct_p_p_b___messaging__1__2.html#a898754602cac55875f298938e18bf017">PPB_Messaging::UnregisterMessageHandler</a>)(<a class="el" href="group___typedefs.html#ga89b662403e6a687bb914b80114c0d19d">PP_Instance</a> instance)</td> |
| </tr> |
| </table> |
| </div> |
| <div class="memdoc"> |
| <p>Unregisters the current message handler for <code>instance</code> if one is registered. </p> |
| <p>After this call, the message handler (if one was registered) will have "Destroy" called on it and will receive no further messages after that point. After that point, all messages sent from JavaScript using postMessage() will be dispatched to PPP_Messaging (if the plugin supports PPP_MESSAGING_INTERFACE). Attempts to call postMessageAndAwaitResponse() from JavaScript will fail.</p> |
| <p>Attempting to unregister a message handler when none is registered has no effect.</p> |
| <dl class="params"><dt><b>Parameters:</b></dt><dd> |
| <table class="params"> |
| <tr><td class="paramdir">[in]</td><td class="paramname">instance</td><td>A <code>PP_Instance</code> identifying one instance of a module. </td></tr> |
| </table> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <hr />The documentation for this struct was generated from the following file:<ul> |
| <li><a class="el" href="ppb__messaging_8h.html">ppb_messaging.h</a></li> |
| </ul> |
| </div><!-- contents --> |
| </div> |
| {{/partials.standard_nacl_api}} |
