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 // -----------------------------------------------------------------------------
  22 // A MessageAttachmentSet is an ordered set of POSIX file descriptors. These are
  23 // associated with IPC messages so that descriptors can be transmitted over a
  24 // UNIX domain socket.
  25 // -----------------------------------------------------------------------------
  26 class IPC_EXPORT MessageAttachmentSet
  27     : public base::RefCountedThreadSafe<MessageAttachmentSet> {
  28  public:
  29   MessageAttachmentSet();
  30
  31   // Return the number of descriptors
  32   unsigned size() const;
  33   // Return true if no unconsumed descriptors remain
  34   bool empty() const { return 0 == size(); }
  35
  36 #if defined(OS_POSIX)
  37   // This is the maximum number of descriptors per message. We need to know this
  38   // because the control message kernel interface has to be given a buffer which
  39   // is large enough to store all the descriptor numbers. Otherwise the kernel
  40   // tells us that it truncated the control data and the extra descriptors are
  41   // lost.
  42   //
  43   // In debugging mode, it's a fatal error to try and add more than this number
  44   // of descriptors to a MessageAttachmentSet.
  45   static const size_t kMaxDescriptorsPerMessage = 7;
  46
  47   // ---------------------------------------------------------------------------
  48   // Interfaces for building during message serialisation...
  49
  50   // Add a descriptor to the end of the set. Returns false iff the set is full.
  51   bool AddToBorrow(base::PlatformFile fd);
  52   // Add a descriptor to the end of the set and automatically close it after
  53   // transmission. Returns false iff the set is full.
  54   bool AddToOwn(base::ScopedFD fd);
  55
  56   // ---------------------------------------------------------------------------
  57   // ---------------------------------------------------------------------------
  58   // Interfaces for accessing during message deserialisation...
  59
  60   // Take the nth descriptor from the beginning of the set,
  61   // transferring the ownership of the descriptor taken. Code using this
  62   // /must/ access the descriptors in order, and must do it at most once.
  63   //
  64   // This interface is designed for the deserialising code as it doesn't
  65   // support close flags.
  66   //   returns: file descriptor, or -1 on error
  67   base::PlatformFile TakeDescriptorAt(unsigned n);
  68
  69   // ---------------------------------------------------------------------------
  70
  71   // ---------------------------------------------------------------------------
  72   // Interfaces for transmission...
  73
  74   // Fill an array with file descriptors without 'consuming' them. CommitAll
  75   // must be called after these descriptors have been transmitted.
  76   //   buffer: (output) a buffer of, at least, size() integers.
  77   void PeekDescriptors(base::PlatformFile* buffer) const;
  78   // This must be called after transmitting the descriptors returned by
  79   // PeekDescriptors. It marks all the descriptors as consumed and closes those
  80   // which are auto-close.
  81   void CommitAll();
  82   // Returns true if any contained file descriptors appear to be handles to a
  83   // directory.
  84   bool ContainsDirectoryDescriptor() const;
  85   // Fetch all filedescriptors with the "auto close" property.
  86   // Used instead of CommitAll() when closing must be handled manually.
  87   void ReleaseFDsToClose(std::vector<base::PlatformFile>* fds);
  88
  89   // ---------------------------------------------------------------------------
  90
  91   // ---------------------------------------------------------------------------
  92   // Interfaces for receiving...
  93
  94   // Set the contents of the set from the given buffer. This set must be empty
  95   // before calling. The auto-close flag is set on all the descriptors so that
  96   // unconsumed descriptors are closed on destruction.
  97   void AddDescriptorsToOwn(const base::PlatformFile* buffer, unsigned count);
  98
  99 #endif  // OS_POSIX
 100
 101   // ---------------------------------------------------------------------------
 102
 103  private:
 104   friend class base::RefCountedThreadSafe<MessageAttachmentSet>;
 105
 106   ~MessageAttachmentSet();
 107
 108 #if defined(OS_POSIX)
 109   // A vector of descriptors and close flags. If this message is sent, then
 110   // these descriptors are sent as control data. After sending, any descriptors
 111   // with a true flag are closed. If this message has been received, then these
 112   // are the descriptors which were received and all close flags are true.
 113   std::vector<base::PlatformFile> descriptors_;
 114   ScopedVector<base::ScopedFD> owned_descriptors_;
 115 #endif
 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_