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