Home | History | Annotate | Download | only in c 
      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 
    108