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   M39 = 0.2
  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                      [constptr_in] PP_Var message);
  42   /**
  43    * Invoked as a result of JavaScript invoking postMessageAndAwaitResponse()
  44    * on the plugin's DOM element.
  45    *
  46    * NOTE: JavaScript execution is blocked during the duration of this call.
  47    * Hence, the plugin should respond as quickly as possible. For this reason,
  48    * blocking completion callbacks are disallowed while handling a blocking
  49    * message.
  50    *
  51    * @param[in] instance A <code>PP_Instance</code> identifying one instance
  52    * of a module.
  53    * @param[in] user_data is the same pointer which was provided by a call to
  54    * RegisterMessageHandler().
  55    * @param[in] message is a copy of the parameter that JavaScript provided
  56    * to postMessageAndAwaitResponse().
  57    * @param[out] response will be copied to a JavaScript object which is
  58    * returned as the result of postMessageAndAwaitResponse() to the invoking
  59      JavaScript.
  60    */
  61   void HandleBlockingMessage([in] PP_Instance instance,
  62                              [inout] mem_t user_data,
  63                              [constptr_in] PP_Var message,
  64                              [out] PP_Var response);
  65   /**
  66    * Invoked when the handler object is no longer needed. After this, no more
  67    * calls will be made which pass this same value for <code>instance</code>
  68    * and <code>user_data</code>.
  69    *
  70    * @param[in] instance A <code>PP_Instance</code> identifying one instance
  71    * of a module.
  72    * @param[in] user_data is the same pointer which was provided by a call to
  73    * RegisterMessageHandler.
  74    */
  75   void Destroy([in] PP_Instance instance, [inout] mem_t user_data);
  76 };
  77