ppapi/api/ppp_message_handler.idl

   1 /* Copyright 2014 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>PPP_MessageHandler</code> interface that plugins
   8  * can implement and register using PPB_Messaging::RegisterMessageHandler in
   9  * order to handle messages sent from JavaScript via postMessage() or
  10  * postMessageAndAwaitResponse().
  11  */
  12
  13 label Chrome {
  14   [channel=none] M37 = 0.1
  15 };
  16
  17 /**
  18  * The <code>PPP_MessageHandler</code> interface is implemented by the plugin
  19  * if the plugin wants to receive messages from a thread other than the main
  20  * Pepper thread, or if the plugin wants to handle blocking messages which
  21  * JavaScript may send via postMessageAndAwaitResponse().
  22  *
  23  * This interface struct should not be returned by PPP_GetInterface; instead it
  24  * must be passed as a parameter to PPB_Messaging::RegisterMessageHandler.
  25  */
  26 [no_interface_string]
  27 interface PPP_MessageHandler {
  28   /**
  29    * Invoked as a result of JavaScript invoking postMessage() on the plugin's
  30    * DOM element.
  31    *
  32    * @param[in] instance A <code>PP_Instance</code> identifying one instance
  33    * of a module.
  34    * @param[in] user_data is the same pointer which was provided by a call to
  35    * RegisterMessageHandler.
  36    * @param[in] message A copy of the parameter that JavaScript provided to
  37    * postMessage().
  38    */
  39   void HandleMessage([in] PP_Instance instance,
  40                      [inout] mem_t user_data,
  41                      [in] PP_Var message);
  42   /**
  43    * Invoked as a result of JavaScript invoking postMessageAndAwaitResponse()
  44    * on the plugin's DOM element.
  45    *
  46    * @param[in] instance A <code>PP_Instance</code> identifying one instance
  47    * of a module.
  48    * @param[in] user_data is the same pointer which was provided by a call to
  49    * RegisterMessageHandler.
  50    * @param[in] message is a copy of the parameter that JavaScript provided
  51    * to postMessageAndAwaitResponse.
  52    * @return will be copied to a JavaScript object which is returned as
  53    * the result of postMessageAndAwaitResponse to the invoking JavaScript.
  54    */
  55   PP_Var HandleBlockingMessage([in] PP_Instance instance,
  56                                [inout] mem_t user_data,
  57                                [in] PP_Var message);
  58   /**
  59    * Invoked when the handler object is no longer needed. After this, no more
  60    * calls will be made which pass this same value for <code>instance</code>
  61    * and <code>user_data</code>.
  62    *
  63    * @param[in] instance A <code>PP_Instance</code> identifying one instance
  64    * of a module.
  65    * @param[in] user_data is the same pointer which was provided by a call to
  66    * RegisterMessageHandler.
  67    */
  68   void Destroy([in] PP_Instance instance, [inout] mem_t user_data);
  69 };
  70