ipc/ipc_message_attachment_set.h

   1 // Copyright (c) 2011 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_IPC_MESSAGE_ATTACHMENT_SET_H_
   6 #define IPC_IPC_MESSAGE_ATTACHMENT_SET_H_
   7
   8 #include <vector>
   9
  10 #include "base/macros.h"
  11 #include "base/memory/ref_counted.h"
  12 #include "ipc/ipc_export.h"
  13
  14 #if defined(OS_POSIX)
  15 #include "base/files/file.h"
  16 #endif
  17
  18 namespace IPC {
  19
  20 class BrokerableAttachment;
  21 class MessageAttachment;
  22
  23 // -----------------------------------------------------------------------------
  24 // A MessageAttachmentSet is an ordered set of MessageAttachment objects. These
  25 // are associated with IPC messages so that attachments, each of which is either
  26 // a platform file or a mojo handle, can be transmitted over the underlying UNIX
  27 // domain socket (for ChannelPosix) or Mojo MessagePipe (for ChannelMojo).
  28 // -----------------------------------------------------------------------------
  29 class IPC_EXPORT MessageAttachmentSet
  30     : public base::RefCountedThreadSafe<MessageAttachmentSet> {
  31  public:
  32   MessageAttachmentSet();
  33
  34   // Return the number of attachments
  35   unsigned size() const;
  36   // Return the number of file descriptors
  37   unsigned num_descriptors() const;
  38   // Return the number of mojo handles in the attachment set
  39   unsigned num_mojo_handles() const;
  40   // Return the number of brokerable attachments in the attachment set.
  41   unsigned num_brokerable_attachments() const;
  42
  43   // Return true if no unconsumed descriptors remain
  44   bool empty() const { return 0 == size(); }
  45
  46   bool AddAttachment(scoped_refptr<MessageAttachment> attachment);
  47
  48   // Take the nth attachment from the beginning of the set, Code using this
  49   // /must/ access the attachments in order, and must do it at most once.
  50   //
  51   // This interface is designed for the deserialising code as it doesn't
  52   // support close flags.
  53   //   returns: an attachment, or nullptr on error
  54   scoped_refptr<MessageAttachment> GetAttachmentAt(unsigned index);
  55
  56   // This must be called after transmitting the descriptors returned by
  57   // PeekDescriptors. It marks all the descriptors as consumed and closes those
  58   // which are auto-close.
  59   void CommitAll();
  60
  61   // Returns a vector of all brokerable attachments.
  62   std::vector<const BrokerableAttachment*> PeekBrokerableAttachments() const;
  63
  64   // Replaces a placeholder brokerable attachment with |attachment|, matching
  65   // them by their id.
  66   void ReplacePlaceholderWithAttachment(
  67       const scoped_refptr<BrokerableAttachment>& attachment);
  68
  69 #if defined(OS_POSIX)
  70   // This is the maximum number of descriptors per message. We need to know this
  71   // because the control message kernel interface has to be given a buffer which
  72   // is large enough to store all the descriptor numbers. Otherwise the kernel
  73   // tells us that it truncated the control data and the extra descriptors are
  74   // lost.
  75   //
  76   // In debugging mode, it's a fatal error to try and add more than this number
  77   // of descriptors to a MessageAttachmentSet.
  78   static const size_t kMaxDescriptorsPerMessage = 7;
  79
  80   // ---------------------------------------------------------------------------
  81   // Interfaces for transmission...
  82
  83   // Fill an array with file descriptors without 'consuming' them. CommitAll
  84   // must be called after these descriptors have been transmitted.
  85   //   buffer: (output) a buffer of, at least, size() integers.
  86   void PeekDescriptors(base::PlatformFile* buffer) const;
  87   // Returns true if any contained file descriptors appear to be handles to a
  88   // directory.
  89   bool ContainsDirectoryDescriptor() const;
  90   // Fetch all filedescriptors with the "auto close" property.
  91   // Used instead of CommitAll() when closing must be handled manually.
  92   void ReleaseFDsToClose(std::vector<base::PlatformFile>* fds);
  93
  94   // ---------------------------------------------------------------------------
  95
  96   // ---------------------------------------------------------------------------
  97   // Interfaces for receiving...
  98
  99   // Set the contents of the set from the given buffer. This set must be empty
 100   // before calling. The auto-close flag is set on all the descriptors so that
 101   // unconsumed descriptors are closed on destruction.
 102   void AddDescriptorsToOwn(const base::PlatformFile* buffer, unsigned count);
 103
 104 #endif  // OS_POSIX
 105
 106   // ---------------------------------------------------------------------------
 107
 108  private:
 109   friend class base::RefCountedThreadSafe<MessageAttachmentSet>;
 110
 111   ~MessageAttachmentSet();
 112
 113   // A vector of attachments of the message, which might be |PlatformFile| or
 114   // |MessagePipe|.
 115   std::vector<scoped_refptr<MessageAttachment>> attachments_;
 116
 117   // This contains the index of the next descriptor which should be consumed.
 118   // It's used in a couple of ways. Firstly, at destruction we can check that
 119   // all the descriptors have been read (with GetNthDescriptor). Secondly, we
 120   // can check that they are read in order.
 121   mutable unsigned consumed_descriptor_highwater_;
 122
 123   DISALLOW_COPY_AND_ASSIGN(MessageAttachmentSet);
 124 };
 125
 126 }  // namespace IPC
 127
 128 #endif  // IPC_IPC_MESSAGE_ATTACHMENT_SET_H_