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