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