ppapi/api/ppp_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 PPP_Messaging interface containing pointers to
   8  * functions that you must implement to handle postMessage messages
   9  * on the associated DOM element.
  10  *
  11  */
  12
  13 label Chrome {
  14   M14 = 1.0
  15 };
  16
  17 /**
  18  * The <code>PPP_Messaging</code> interface contains pointers to functions
  19  * that you must implement to handle postMessage events on the associated
  20  * DOM element.
  21  */
  22 interface PPP_Messaging {
  23   /**
  24    * HandleMessage() is a function that the browser calls when PostMessage()
  25    * is invoked on the DOM element for the module instance in JavaScript. Note
  26    * that PostMessage() in the JavaScript interface is asynchronous, meaning
  27    * JavaScript execution will not be blocked while HandleMessage() is
  28    * processing the message.
  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> which has been converted from a
  33    * JavaScript value. JavaScript array/object types are supported from Chrome
  34    * M29 onward. All JavaScript values are copied when passing them to the
  35    * plugin.
  36    *
  37    * When converting JavaScript arrays, any object properties whose name
  38    * is not an array index are ignored. When passing arrays and objects, the
  39    * entire reference graph will be converted and transferred. If the reference
  40    * graph has cycles, the message will not be sent and an error will be logged
  41    * to the console.
  42    *
  43    * The following JavaScript code invokes <code>HandleMessage</code>, passing
  44    * the module instance on which it was invoked, with <code>message</code>
  45    * being a string <code>PP_Var</code> containing "Hello world!"
  46    *
  47    * <strong>Example:</strong>
  48    *
  49    * @code
  50    *
  51    * <body>
  52    *   <object id="plugin"
  53    *           type="application/x-ppapi-postMessage-example"/>
  54    *   <script type="text/javascript">
  55    *     document.getElementById('plugin').postMessage("Hello world!");
  56    *   </script>
  57    * </body>
  58    *
  59    * @endcode
  60    *
  61    */
  62   void HandleMessage([in] PP_Instance instance, [in] PP_Var message);
  63 };
  64