ipc/attachment_broker.h

   1 // Copyright 2015 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 IPC_ATTACHMENT_BROKER_H_
   6 #define IPC_ATTACHMENT_BROKER_H_
   7
   8 #include "base/gtest_prod_util.h"
   9 #include "base/macros.h"
  10 #include "base/process/process_handle.h"
  11 #include "ipc/brokerable_attachment.h"
  12 #include "ipc/ipc_export.h"
  13 #include "ipc/ipc_listener.h"
  14
  15 // If the platform has no attachments that need brokering, then it shouldn't
  16 // compile any code that calls member functions of AttachmentBroker. This
  17 // prevents symbols only used by AttachmentBroker and its subclasses from
  18 // making it into the binary.
  19 #if defined(OS_WIN)
  20 #define USE_ATTACHMENT_BROKER 1
  21 #else
  22 #define USE_ATTACHMENT_BROKER 0
  23 #endif  // defined(OS_WIN)
  24
  25 namespace IPC {
  26
  27 class AttachmentBroker;
  28 // Classes that inherit from this abstract base class are capable of
  29 // communicating with a broker to send and receive attachments to Chrome IPC
  30 // messages.
  31 class IPC_EXPORT SupportsAttachmentBrokering {
  32  public:
  33   // Returns an AttachmentBroker used to broker attachments of IPC messages to
  34   // other processes. There must be exactly one AttachmentBroker per process.
  35   virtual AttachmentBroker* GetAttachmentBroker() = 0;
  36 };
  37
  38 // Responsible for brokering attachments to Chrome IPC messages. On platforms
  39 // that support attachment brokering, every IPC channel should have a reference
  40 // to a AttachmentBroker.
  41 // This class is not thread safe. The implementation of this class assumes that
  42 // it is only ever used on the same thread as its consumers.
  43 class IPC_EXPORT AttachmentBroker : public Listener {
  44  public:
  45   // A standard observer interface that allows consumers of the AttachmentBroker
  46   // to be notified when a new attachment has been received.
  47   class Observer {
  48    public:
  49     virtual void ReceivedBrokerableAttachmentWithId(
  50         const BrokerableAttachment::AttachmentId& id) = 0;
  51   };
  52
  53   // Each process has at most one attachment broker. The process is responsible
  54   // for ensuring that |broker| stays alive for as long as the process is
  55   // sending/receiving ipc messages.
  56   static void SetGlobal(AttachmentBroker* broker);
  57   static AttachmentBroker* GetGlobal();
  58
  59   AttachmentBroker();
  60   ~AttachmentBroker() override;
  61
  62   // Sends |attachment| to |destination_process|. The implementation uses an
  63   // IPC::Channel to communicate with the broker process. This may be the same
  64   // IPC::Channel that is requesting the brokering of an attachment.
  65   // Returns true on success and false otherwise.
  66   virtual bool SendAttachmentToProcess(const BrokerableAttachment* attachment,
  67                                        base::ProcessId destination_process) = 0;
  68
  69   // Returns whether the attachment was available. If the attachment was
  70   // available, populates the output parameter |attachment|.
  71   bool GetAttachmentWithId(BrokerableAttachment::AttachmentId id,
  72                            scoped_refptr<BrokerableAttachment>* attachment);
  73
  74   // Any given observer should only ever add itself once to the observer list.
  75   void AddObserver(Observer* observer);
  76   void RemoveObserver(Observer* observer);
  77
  78  protected:
  79   using AttachmentVector = std::vector<scoped_refptr<BrokerableAttachment>>;
  80
  81   // Adds |attachment| to |attachments_|, and notifies the observers.
  82   void HandleReceivedAttachment(
  83       const scoped_refptr<BrokerableAttachment>& attachment);
  84
  85   // Informs the observers that a new BrokerableAttachment has been received.
  86   void NotifyObservers(const BrokerableAttachment::AttachmentId& id);
  87
  88   // This method is exposed for testing only.
  89   AttachmentVector* get_attachments() { return &attachments_; }
  90
  91  private:
  92 #if defined(OS_WIN)
  93   FRIEND_TEST_ALL_PREFIXES(AttachmentBrokerUnprivilegedWinTest,
  94                            ReceiveValidMessage);
  95   FRIEND_TEST_ALL_PREFIXES(AttachmentBrokerUnprivilegedWinTest,
  96                            ReceiveInvalidMessage);
  97 #endif  // defined(OS_WIN)
  98
  99   // A vector of BrokerableAttachments that have been received, but not yet
 100   // consumed.
 101   // A std::vector is used instead of a std::map because this container is
 102   // expected to have few elements, for which a std::vector is expected to have
 103   // better performance.
 104   AttachmentVector attachments_;
 105
 106   std::vector<Observer*> observers_;
 107   DISALLOW_COPY_AND_ASSIGN(AttachmentBroker);
 108 };
 109
 110 }  // namespace IPC
 111
 112 #endif  // IPC_ATTACHMENT_BROKER_H_