ppapi/api/ppb_messaging.idl

   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 /**
   7  * This file defines the <code>PPB_Messaging</code> interface implemented
   8  * by the browser for sending messages to DOM elements associated with a
   9  * specific module instance.
  10  */
  11
  12 [generate_thunk]
  13
  14 label Chrome {
  15   M14 = 1.0,
  16   M39 = 1.2
  17 };
  18
  19 /**
  20  * The <code>PPB_Messaging</code> interface is implemented by the browser
  21  * and is related to sending messages to JavaScript message event listeners on
  22  * the DOM element associated with specific module instance.
  23  */
  24 interface PPB_Messaging {
  25   /**
  26    * PostMessage() asynchronously invokes any listeners for message events on
  27    * the DOM element for the given module instance. A call to PostMessage()
  28    * will not block while the message is processed.
  29    *
  30    * @param[in] instance A <code>PP_Instance</code> identifying one instance
  31    * of a module.
  32    * @param[in] message A <code>PP_Var</code> containing the data to be sent to
  33    * JavaScript.
  34    * <code>message</code> can be any <code>PP_Var</code> type except
  35    * <code>PP_VARTYPE_OBJECT</code>. Array/Dictionary types are supported from
  36    * Chrome M29 onward. All var types are copied when passing them to
  37    * JavaScript.
  38    *
  39    * When passing array or dictionary <code>PP_Var</code>s, the entire reference
  40    * graph will be converted and transferred. If the reference graph has cycles,
  41    * the message will not be sent and an error will be logged to the console.
  42    *
  43    * Listeners for message events in JavaScript code will receive an object
  44    * conforming to the HTML 5 <code>MessageEvent</code> interface.
  45    * Specifically, the value of message will be contained as a property called
  46    *  data in the received <code>MessageEvent</code>.
  47    *
  48    * This messaging system is similar to the system used for listening for
  49    * messages from Web Workers. Refer to
  50    * <code>http://www.whatwg.org/specs/web-workers/current-work/</code> for
  51    * further information.
  52    *
  53    * <strong>Example:</strong>
  54    *
  55    * @code
  56    *
  57    * <body>
  58    *   <object id="plugin"
  59    *           type="application/x-ppapi-postMessage-example"/>
  60    *   <script type="text/javascript">
  61    *     var plugin = document.getElementById('plugin');
  62    *     plugin.addEventListener("message",
  63    *                             function(message) { alert(message.data); },
  64    *                             false);
  65    *   </script>
  66    * </body>
  67    *
  68    * @endcode
  69    *
  70    * The module instance then invokes PostMessage() as follows:
  71    *
  72    * @code
  73    *
  74    *  char hello_world[] = "Hello world!";
  75    *  PP_Var hello_var = ppb_var_interface->VarFromUtf8(instance,
  76    *                                                    hello_world,
  77    *                                                    sizeof(hello_world));
  78    *  ppb_messaging_interface->PostMessage(instance, hello_var); // Copies var.
  79    *  ppb_var_interface->Release(hello_var);
  80    *
  81    * @endcode
  82    *
  83    * The browser will pop-up an alert saying "Hello world!"
  84    */
  85   [version=1.0]
  86   void PostMessage([in] PP_Instance instance, [in] PP_Var message);
  87
  88   /**
  89    * Registers a handler for receiving messages from JavaScript. If a handler
  90    * is registered this way, it will replace PPP_Messaging, and all messages
  91    * sent from JavaScript via postMessage and postMessageAndAwaitResponse will
  92    * be dispatched to <code>handler</code>.
  93    *
  94    * The function calls will be dispatched via <code>message_loop</code>. This
  95    * means that the functions will be invoked on the thread to which
  96    * <code>message_loop</code> is attached, when <code>message_loop</code> is
  97    * run. It is illegal to pass the main thread message loop;
  98    * RegisterMessageHandler will return PP_ERROR_WRONG_THREAD in that case.
  99    * If you quit <code>message_loop</code> before calling Unregister(),
 100    * the browser will not be able to call functions in the plugin's message
 101    * handler any more. That could mean missing some messages or could cause a
 102    * leak if you depend on Destroy() to free hander data. So you should,
 103    * whenever possible, Unregister() the handler prior to quitting its event
 104    * loop.
 105    *
 106    * Attempting to register a message handler when one is already registered
 107    * will cause the current MessageHandler to be unregistered and replaced. In
 108    * that case, no messages will be sent to the "default" message handler
 109    * (PPP_Messaging). Messages will stop arriving at the prior message handler
 110    * and will begin to be dispatched at the new message handler.
 111    *
 112    * @param[in] instance A <code>PP_Instance</code> identifying one instance
 113    * of a module.
 114    * @param[in] user_data A pointer the plugin may choose to use when handling
 115    * calls to functions within PPP_MessageHandler. The browser will pass this
 116    * same pointer when invoking functions within PPP_MessageHandler.
 117    * @param[in] handler The plugin-provided set of functions for handling
 118    * messages.
 119    * @param[in] message_loop Represents the message loop on which
 120    * PPP_MessageHandler functions should be invoked.
 121    * @return PP_OK on success, or an error from pp_errors.h.
 122    */
 123   [version=1.2]
 124   int32_t RegisterMessageHandler([in] PP_Instance instance,
 125                                  [inout] mem_t user_data,
 126                                  [in] PPP_MessageHandler handler,
 127                                  [in] PP_Resource message_loop);
 128   /**
 129    * Unregisters the current message handler for <code>instance</code> if one
 130    * is registered. After this call, the message handler (if one was
 131    * registered) will have "Destroy" called on it and will receive no further
 132    * messages after that point. After that point, all messages sent from
 133    * JavaScript using postMessage() will be dispatched to PPP_Messaging (if
 134    * the plugin supports PPP_MESSAGING_INTERFACE). Attempts to call
 135    * postMessageAndAwaitResponse() from JavaScript will fail.
 136    *
 137    * Attempting to unregister a message handler when none is registered has no
 138    * effect.
 139    *
 140    * @param[in] instance A <code>PP_Instance</code> identifying one instance
 141    * of a module.
 142    */
 143   [version=1.2]
 144   void UnregisterMessageHandler([in] PP_Instance instance);
 145 };
 146