ppapi/c/ppb_messaging.h

   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 /* From ppb_messaging.idl modified Wed Jun  5 10:32:59 2013. */
   7
   8 #ifndef PPAPI_C_PPB_MESSAGING_H_
   9 #define PPAPI_C_PPB_MESSAGING_H_
  10
  11 #include "ppapi/c/pp_bool.h"
  12 #include "ppapi/c/pp_instance.h"
  13 #include "ppapi/c/pp_macros.h"
  14 #include "ppapi/c/pp_stdint.h"
  15 #include "ppapi/c/pp_var.h"
  16
  17 #define PPB_MESSAGING_INTERFACE_1_0 "PPB_Messaging;1.0"
  18 #define PPB_MESSAGING_INTERFACE PPB_MESSAGING_INTERFACE_1_0
  19
  20 /**
  21  * @file
  22  * This file defines the <code>PPB_Messaging</code> interface implemented
  23  * by the browser for sending messages to DOM elements associated with a
  24  * specific module instance.
  25  */
  26
  27
  28 /**
  29  * @addtogroup Interfaces
  30  * @{
  31  */
  32 /**
  33  * The <code>PPB_Messaging</code> interface is implemented by the browser
  34  * and is related to sending messages to JavaScript message event listeners on
  35  * the DOM element associated with specific module instance.
  36  */
  37 struct PPB_Messaging_1_0 {
  38   /**
  39    * PostMessage() asynchronously invokes any listeners for message events on
  40    * the DOM element for the given module instance. A call to PostMessage()
  41    * will not block while the message is processed.
  42    *
  43    * @param[in] instance A <code>PP_Instance</code> identifying one instance
  44    * of a module.
  45    * @param[in] message A <code>PP_Var</code> containing the data to be sent to
  46    * JavaScript.
  47    * <code>message</code> can be any <code>PP_Var</code> type except
  48    * <code>PP_VARTYPE_OBJECT</code>. Array/Dictionary types are supported from
  49    * Chrome M29 onward. All var types are copied when passing them to
  50    * JavaScript.
  51    *
  52    * When passing array or dictionary <code>PP_Var</code>s, the entire reference
  53    * graph will be converted and transferred. If the reference graph has cycles,
  54    * the message will not be sent and an error will be logged to the console.
  55    *
  56    * Listeners for message events in JavaScript code will receive an object
  57    * conforming to the HTML 5 <code>MessageEvent</code> interface.
  58    * Specifically, the value of message will be contained as a property called
  59    *  data in the received <code>MessageEvent</code>.
  60    *
  61    * This messaging system is similar to the system used for listening for
  62    * messages from Web Workers. Refer to
  63    * <code>http://www.whatwg.org/specs/web-workers/current-work/</code> for
  64    * further information.
  65    *
  66    * <strong>Example:</strong>
  67    *
  68    * @code
  69    *
  70    * <body>
  71    *   <object id="plugin"
  72    *           type="application/x-ppapi-postMessage-example"/>
  73    *   <script type="text/javascript">
  74    *     var plugin = document.getElementById('plugin');
  75    *     plugin.addEventListener("message",
  76    *                             function(message) { alert(message.data); },
  77    *                             false);
  78    *   </script>
  79    * </body>
  80    *
  81    * @endcode
  82    *
  83    * The module instance then invokes PostMessage() as follows:
  84    *
  85    * @code
  86    *
  87    *  char hello_world[] = "Hello world!";
  88    *  PP_Var hello_var = ppb_var_interface->VarFromUtf8(instance,
  89    *                                                    hello_world,
  90    *                                                    sizeof(hello_world));
  91    *  ppb_messaging_interface->PostMessage(instance, hello_var); // Copies var.
  92    *  ppb_var_interface->Release(hello_var);
  93    *
  94    * @endcode
  95    *
  96    * The browser will pop-up an alert saying "Hello world!"
  97    */
  98   void (*PostMessage)(PP_Instance instance, struct PP_Var message);
  99 };
 100
 101 typedef struct PPB_Messaging_1_0 PPB_Messaging;
 102 /**
 103  * @}
 104  */
 105
 106 #endif  /* PPAPI_C_PPB_MESSAGING_H_ */
 107