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
  65 #if defined(OS_POSIX)
  66   // This is the maximum number of descriptors per message. We need to know this
  67   // because the control message kernel interface has to be given a buffer which
  68   // is large enough to store all the descriptor numbers. Otherwise the kernel
  69   // tells us that it truncated the control data and the extra descriptors are
  70   // lost.
  71   //
  72   // In debugging mode, it's a fatal error to try and add more than this number
  73   // of descriptors to a MessageAttachmentSet.
  74   static const size_t kMaxDescriptorsPerMessage = 7;
  75
  76   // ---------------------------------------------------------------------------
  77   // Interfaces for transmission...
  78
  79   // Fill an array with file descriptors without 'consuming' them. CommitAll
  80   // must be called after these descriptors have been transmitted.
  81   //   buffer: (output) a buffer of, at least, size() integers.
  82   void PeekDescriptors(base::PlatformFile* buffer) const;
  83   // Returns true if any contained file descriptors appear to be handles to a
  84   // directory.
  85   bool ContainsDirectoryDescriptor() const;
  86   // Fetch all filedescriptors with the "auto close" property.
  87   // Used instead of CommitAll() when closing must be handled manually.
  88   void ReleaseFDsToClose(std::vector<base::PlatformFile>* fds);
  89
  90   // ---------------------------------------------------------------------------
  91
  92   // ---------------------------------------------------------------------------
  93   // Interfaces for receiving...
  94
  95   // Set the contents of the set from the given buffer. This set must be empty
  96   // before calling. The auto-close flag is set on all the descriptors so that
  97   // unconsumed descriptors are closed on destruction.
  98   void AddDescriptorsToOwn(const base::PlatformFile* buffer, unsigned count);
  99
 100 #endif  // OS_POSIX
 101
 102   // ---------------------------------------------------------------------------
 103
 104  private:
 105   friend class base::RefCountedThreadSafe<MessageAttachmentSet>;
 106
 107   ~MessageAttachmentSet();
 108
 109   // A vector of attachments of the message, which might be |PlatformFile| or
 110   // |MessagePipe|.
 111   std::vector<scoped_refptr<MessageAttachment>> attachments_;
 112
 113   // This contains the index of the next descriptor which should be consumed.
 114   // It's used in a couple of ways. Firstly, at destruction we can check that
 115   // all the descriptors have been read (with GetNthDescriptor). Secondly, we
 116   // can check that they are read in order.
 117   mutable unsigned consumed_descriptor_highwater_;
 118
 119   DISALLOW_COPY_AND_ASSIGN(MessageAttachmentSet);
 120 };
 121
 122 }  // namespace IPC
 123
 124 #endif  // IPC_IPC_MESSAGE_ATTACHMENT_SET_H_