src/ppapi/cpp/message_handler.h

   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 #ifndef PPAPI_CPP_MESSAGE_HANDLER_H_
   6 #define PPAPI_CPP_MESSAGE_HANDLER_H_
   7
   8 namespace pp {
   9
  10 /// <code>MessageHandler</code> is an abstract base class that the plugin may
  11 /// implement if it wants to receive messages from JavaScript on a background
  12 /// thread when JavaScript invokes  postMessage() or
  13 /// postMessageAndAwaitResponse(). See pp::Instance::RegisterMessageHandler()
  14 /// for usage.
  15 class MessageHandler {
  16  public:
  17   virtual ~MessageHandler() {};
  18
  19   /// Invoked as a result of JavaScript invoking postMessage() on the plugin's
  20   /// DOM element.
  21   ///
  22   /// @param[in] instance An <code>InstanceHandle</code> identifying one
  23   /// instance of a module.
  24   /// @param[in] message_data A copy of the parameter that JavaScript provided
  25   /// to postMessage().
  26   virtual void HandleMessage(pp::InstanceHandle instance,
  27                              const Var& message_data) = 0;
  28
  29   /// Invoked as a result of JavaScript invoking postMessageAndAwaitResponse()
  30   /// on the plugin's DOM element.
  31   ///
  32   /// NOTE: JavaScript execution is blocked during the duration of this call.
  33   /// Hence, the plugin should respond as quickly as possible. For this reason,
  34   /// blocking completion callbacks are disallowed while handling a blocking
  35   /// message.
  36   ///
  37   /// @param[in] instance An <code>InstanceHandle</code> identifying one
  38   /// instance of a module.
  39   /// @param[in] message_data A copy of the parameter that JavaScript provided
  40   /// to postMessage().
  41   /// @return Returns a pp::Var that is then copied to a JavaScript object
  42   /// which is returned as the result of JavaScript's call of
  43   /// postMessageAndAwaitResponse().
  44   virtual pp::Var HandleBlockingMessage(pp::InstanceHandle instance,
  45                                         const Var& message_data) = 0;
  46
  47   /// Invoked when this MessageHandler is no longer needed. After this, no more
  48   /// calls will be made to this object.
  49   ///
  50   /// @param[in] instance An <code>InstanceHandle</code> identifying one
  51   /// instance of a module.
  52   virtual void WasUnregistered(pp::InstanceHandle instance) = 0;
  53 };
  54
  55 }  // namespace pp
  56
  57 #endif  // PPAPI_CPP_MESSAGE_HANDLER_H_