src/ppapi/host/resource_message_filter.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 #ifndef PPAPI_HOST_RESOURCE_MESSAGE_FILTER_H_
   6 #define PPAPI_HOST_RESOURCE_MESSAGE_FILTER_H_
   7
   8 #include "base/memory/ref_counted.h"
   9 #include "ppapi/c/pp_stdint.h"
  10 #include "ppapi/host/host_message_context.h"
  11 #include "ppapi/host/ppapi_host_export.h"
  12 #include "ppapi/host/resource_message_handler.h"
  13
  14 namespace base {
  15 class MessageLoopProxy;
  16 class TaskRunner;
  17 }
  18
  19 namespace IPC {
  20 class Message;
  21 }
  22
  23 namespace ppapi {
  24 namespace host {
  25
  26 class ResourceHost;
  27
  28 // This is the base class of resource message filters that can handle resource
  29 // messages on another thread. ResourceHosts can handle most messages
  30 // directly, but if they need to handle something on a different thread it is
  31 // inconvenient. This class makes handling that case easier. This class is
  32 // similar to a BrowserMessageFilter but for resource messages. Note that the
  33 // liftetime of a ResourceHost is managed by a PpapiHost and may be destroyed
  34 // before or while your message is being processed on another thread.
  35 // If this is the case, the message handler will always be called but a reply
  36 // may not be sent back to the host.
  37 //
  38 // To handle a resource message on another thread you should implement a
  39 // subclass as follows:
  40 // class MyMessageFilter : public ResourceMessageFilter {
  41 //  protected:
  42 //   virtual scoped_refptr<base::TaskRunner> OverrideTaskRunnerForMessage(
  43 //       const IPC::Message& message) OVERRIDE {
  44 //     if (message.type() == MyMessage::ID)
  45 //       return BrowserThread::GetMessageLoopProxyForThread(BrowserThread::UI);
  46 //     return NULL;
  47 //   }
  48 //
  49 //   virtual int32_t OnResourceMessageReceived(
  50 //       const IPC::Message& msg,
  51 //       HostMessageContext* context) OVERRIDE {
  52 //     IPC_BEGIN_MESSAGE_MAP(MyMessageFilter, msg)
  53 //       PPAPI_DISPATCH_HOST_RESOURCE_CALL(MyMessage, OnMyMessage)
  54 //     IPC_END_MESSAGE_MAP()
  55 //     return PP_ERROR_FAILED;
  56 //   }
  57 //
  58 //  private:
  59 //   int32_t OnMyMessage(ppapi::host::HostMessageContext* context, ...) {
  60 //     // Will be run on the UI thread.
  61 //   }
  62 // }
  63 //
  64 // The filter should then be added in the resource host using:
  65 // AddFilter(make_scoped_refptr(new MyMessageFilter));
  66 class PPAPI_HOST_EXPORT ResourceMessageFilter
  67     : public ResourceMessageHandler,
  68       public base::RefCountedThreadSafe<ResourceMessageFilter> {
  69  public:
  70   // This object must be constructed on the same thread that a reply message
  71   // should be sent, i.e. the IO thread when constructed in the browser process
  72   // or the main thread when constructed in the renderer process. Since
  73   // ResourceMessageFilters are usually constructed in the constructor of the
  74   // owning ResourceHost, this will almost always be the case anyway.
  75   ResourceMessageFilter();
  76   // Test constructor. Allows you to specify the message loop which will be used
  77   // to dispatch replies on.
  78   ResourceMessageFilter(
  79       scoped_refptr<base::MessageLoopProxy> reply_thread_message_loop_proxy);
  80
  81   // Called when a filter is added to a ResourceHost.
  82   void OnFilterAdded(ResourceHost* resource_host);
  83   // Called when a filter is removed from a ResourceHost.
  84   void OnFilterDestroyed();
  85
  86   // This will dispatch the message handler on the target thread. It returns
  87   // true if the message was handled by this filter and false otherwise.
  88   virtual bool HandleMessage(const IPC::Message& msg,
  89                              HostMessageContext* context) OVERRIDE;
  90
  91   // This can be called from any thread.
  92   virtual void SendReply(const ReplyMessageContext& context,
  93       const IPC::Message& msg) OVERRIDE;
  94
  95  protected:
  96   friend class base::RefCountedThreadSafe<ResourceMessageFilter>;
  97   virtual ~ResourceMessageFilter();
  98
  99   // If you want the message to be handled on another thread, return a non-null
 100   // task runner which will target tasks accordingly.
 101   virtual scoped_refptr<base::TaskRunner> OverrideTaskRunnerForMessage(
 102       const IPC::Message& message);
 103
 104  private:
 105   // This method is posted to the target thread and runs the message handler.
 106   void DispatchMessage(const IPC::Message& msg,
 107                        HostMessageContext context);
 108
 109   // Message loop to send resource message replies on. This will be the message
 110   // loop proxy of the IO thread for the browser process or the main thread for
 111   // the renderer process.
 112   scoped_refptr<base::MessageLoopProxy> reply_thread_message_loop_proxy_;
 113
 114   // Non-owning pointer to the resource host owning this filter. Should only be
 115   // accessed from the thread which sends messages to the plugin resource (i.e.
 116   // the IO thread for the browser process or the main thread for the renderer).
 117   // This will be NULL upon creation of the filter and is set to the owning
 118   // ResourceHost when |OnFilterAdded| is called. When the owning ResourceHost
 119   // is destroyed, |OnFilterDestroyed| is called and this will be set to NULL.
 120   ResourceHost* resource_host_;
 121
 122   DISALLOW_COPY_AND_ASSIGN(ResourceMessageFilter);
 123 };
 124
 125 }  // namespace host
 126 }  // namespace ppapi
 127
 128 #endif  // PPAPI_HOST_RESOURCE_MESSAGE_FILTER_H_