Data Fields

void(*	PostMessage )(PP_Instance instance, struct PP_Var message)
int32_t(*	RegisterMessageHandler )(PP_Instance instance, void user_data, const struct PPP_MessageHandler handler, PP_Resource message_loop)
void(*	UnregisterMessageHandler )(PP_Instance instance)

Detailed Description

The PPB_Messaging 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.

Field Documentation

void(* PPB_Messaging::PostMessage)(PP_Instance instance, struct PP_Var message)

PostMessage() asynchronously invokes any listeners for message events on the DOM element for the given module instance.

A call to PostMessage() will not block while the message is processed.

Parameters:

[in]	instance	A `PP_Instance` identifying one instance of a module.
[in]	message	A `PP_Var` containing the data to be sent to JavaScript. `message` can be any `PP_Var` type except `PP_VARTYPE_OBJECT`. Array/Dictionary types are supported from Chrome M29 onward. All var types are copied when passing them to JavaScript.

When passing array or dictionary PP_Vars, 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.

Listeners for message events in JavaScript code will receive an object conforming to the HTML 5 MessageEvent interface. Specifically, the value of message will be contained as a property called data in the received MessageEvent.

This messaging system is similar to the system used for listening for messages from Web Workers. Refer to http://www.whatwg.org/specs/web-workers/current-work/ for further information.

Example:

 <body>
   <object id="plugin"
           type="application/x-ppapi-postMessage-example"/>
   <script type="text/javascript">
     var plugin = document.getElementById('plugin');
     plugin.addEventListener("message",
                             function(message) { alert(message.data); },
                             false);
   </script>
 </body>

The module instance then invokes PostMessage() as follows:

  char hello_world[] = "Hello world!";
  PP_Var hello_var = ppb_var_interface->VarFromUtf8(instance,
                                                    hello_world,
                                                    sizeof(hello_world));
  ppb_messaging_interface->PostMessage(instance, hello_var); // Copies var.
  ppb_var_interface->Release(hello_var);

The browser will pop-up an alert saying "Hello world!"

int32_t(* PPB_Messaging::RegisterMessageHandler)(PP_Instance instance, void *user_data, const struct PPP_MessageHandler *handler, PP_Resource message_loop)

Registers a handler for receiving messages from JavaScript.

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 handler.

The function calls will be dispatched via message_loop. This means that the functions will be invoked on the thread to which message_loop is attached, when message_loop 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 message_loop 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.

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.

Parameters:

[in]	instance	A `PP_Instance` identifying one instance of a module.
[in]	user_data	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.
[in]	handler	The plugin-provided set of functions for handling messages.
[in]	message_loop	Represents the message loop on which PPP_MessageHandler functions should be invoked.

Returns:: PP_OK on success, or an error from pp_errors.h.

void(* PPB_Messaging::UnregisterMessageHandler)(PP_Instance instance)

Unregisters the current message handler for instance if one is registered.

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.

Attempting to unregister a message handler when none is registered has no effect.

Parameters:

[in] instance A PP_Instance identifying one instance of a module.

The documentation for this struct was generated from the following file:

ppb_messaging.h