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 <stddef.h> 9 10 #include <vector> 11 12 #include "base/macros.h" 13 #include "base/memory/ref_counted.h" 14 #include "build/build_config.h" 15 #include "ipc/ipc_export.h" 16 17 #if defined(OS_POSIX) 18 #include "base/files/file.h" 19 #endif 20 21 namespace IPC { 22 23 class BrokerableAttachment; 24 class MessageAttachment; 25 26 // ----------------------------------------------------------------------------- 27 // A MessageAttachmentSet is an ordered set of MessageAttachment objects 28 // associated with an IPC message. There are three types of MessageAttachments: 29 // 1) TYPE_PLATFORM_FILE is transmitted over the Channel's underlying 30 // UNIX domain socket 31 // 2) TYPE_MOJO_HANDLE is transmitted over the Mojo MessagePipe. 32 // 3) TYPE_BROKERABLE_ATTACHMENT is transmitted by the Attachment Broker. 33 // Any given IPC Message can have attachments of type (1) or (2), but not both. 34 // These are stored in |attachments_|. Attachments of type (3) are stored in 35 // |brokerable_attachments_|. 36 // 37 // To produce a deterministic ordering, all attachments in |attachments_| are 38 // considered to come before those in |brokerable_attachments_|. These 39 // attachments are transmitted across different communication channels, and 40 // multiplexed by the receiver, so ordering between them cannot be guaranteed. 41 // 42 // ----------------------------------------------------------------------------- 43 class IPC_EXPORT MessageAttachmentSet 44 : public base::RefCountedThreadSafe<MessageAttachmentSet> { 45 public: 46 MessageAttachmentSet(); 47 48 // Return the number of attachments 49 unsigned size() const; 50 // Return the number of file descriptors 51 unsigned num_descriptors() const; 52 // Return the number of mojo handles in the attachment set 53 unsigned num_mojo_handles() const; 54 // Return the number of brokerable attachments in the attachment set. 55 unsigned num_brokerable_attachments() const; 56 // Return the number of non-brokerable attachments in the attachment set. 57 unsigned num_non_brokerable_attachments() const; 58 59 // Return true if no unconsumed descriptors remain 60 bool empty() const { return 0 == size(); } 61 62 // Returns whether the attachment was successfully added. 63 // |index| is an output variable. On success, it contains the index of the 64 // newly added attachment. 65 // |brokerable| is an output variable. On success, it describes which vector 66 // the attachment was added to. 67 bool AddAttachment(scoped_refptr<MessageAttachment> attachment, 68 size_t* index, 69 bool* brokerable); 70 71 // Similar to the above method, but without output variables. 72 bool AddAttachment(scoped_refptr<MessageAttachment> attachment); 73 74 // Take the nth non-brokerable attachment from the beginning of the vector, 75 // Code using this /must/ access the attachments in order, and must do it at 76 // most once. 77 // 78 // This interface is designed for the deserialising code as it doesn't 79 // support close flags. 80 // returns: an attachment, or nullptr on error 81 scoped_refptr<MessageAttachment> GetNonBrokerableAttachmentAt(unsigned index); 82 83 // Similar to GetNonBrokerableAttachmentAt, but there are no ordering 84 // requirements. 85 scoped_refptr<MessageAttachment> GetBrokerableAttachmentAt(unsigned index); 86 87 // This must be called after transmitting the descriptors returned by 88 // PeekDescriptors. It marks all the non-brokerable descriptors as consumed 89 // and closes those which are auto-close. 90 void CommitAllDescriptors(); 91 92 // Returns a vector of all brokerable attachments. 93 std::vector<scoped_refptr<IPC::BrokerableAttachment>> 94 GetBrokerableAttachments() const; 95 96 // Replaces a placeholder brokerable attachment with |attachment|, matching 97 // them by their id. 98 void ReplacePlaceholderWithAttachment( 99 const scoped_refptr<BrokerableAttachment>& attachment); 100 101 #if defined(OS_POSIX) 102 // This is the maximum number of descriptors per message. We need to know this 103 // because the control message kernel interface has to be given a buffer which 104 // is large enough to store all the descriptor numbers. Otherwise the kernel 105 // tells us that it truncated the control data and the extra descriptors are 106 // lost. 107 // 108 // In debugging mode, it's a fatal error to try and add more than this number 109 // of descriptors to a MessageAttachmentSet. 110 static const size_t kMaxDescriptorsPerMessage = 7; 111 112 // --------------------------------------------------------------------------- 113 // Interfaces for transmission... 114 115 // Fill an array with file descriptors without 'consuming' them. 116 // CommitAllDescriptors must be called after these descriptors have been 117 // transmitted. 118 // buffer: (output) a buffer of, at least, size() integers. 119 void PeekDescriptors(base::PlatformFile* buffer) const; 120 // Returns true if any contained file descriptors appear to be handles to a 121 // directory. 122 bool ContainsDirectoryDescriptor() const; 123 // Fetch all filedescriptors with the "auto close" property. Used instead of 124 // CommitAllDescriptors() when closing must be handled manually. 125 void ReleaseFDsToClose(std::vector<base::PlatformFile>* fds); 126 127 // --------------------------------------------------------------------------- 128 129 // --------------------------------------------------------------------------- 130 // Interfaces for receiving... 131 132 // Set the contents of the set from the given buffer. This set must be empty 133 // before calling. The auto-close flag is set on all the descriptors so that 134 // unconsumed descriptors are closed on destruction. 135 void AddDescriptorsToOwn(const base::PlatformFile* buffer, unsigned count); 136 137 #endif // OS_POSIX 138 139 // --------------------------------------------------------------------------- 140 141 private: 142 friend class base::RefCountedThreadSafe<MessageAttachmentSet>; 143 144 ~MessageAttachmentSet(); 145 146 // All elements either have type TYPE_PLATFORM_FILE or TYPE_MOJO_HANDLE. 147 std::vector<scoped_refptr<MessageAttachment>> attachments_; 148 149 // All elements have type TYPE_BROKERABLE_ATTACHMENT. 150 std::vector<scoped_refptr<BrokerableAttachment>> brokerable_attachments_; 151 152 // This contains the index of the next descriptor which should be consumed. 153 // It's used in a couple of ways. Firstly, at destruction we can check that 154 // all the descriptors have been read (with GetNthDescriptor). Secondly, we 155 // can check that they are read in order. 156 mutable unsigned consumed_descriptor_highwater_; 157 158 DISALLOW_COPY_AND_ASSIGN(MessageAttachmentSet); 159 }; 160 161 } // namespace IPC 162 163 #endif // IPC_IPC_MESSAGE_ATTACHMENT_SET_H_ 164
