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