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
13label 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]
27interface 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
78