ipc/ipc_message.h

   1 // Copyright (c) 2012 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_H_
   6 #define IPC_IPC_MESSAGE_H_
   7
   8 #include <string>
   9
  10 #include "base/basictypes.h"
  11 #include "base/memory/ref_counted.h"
  12 #include "base/pickle.h"
  13 #include "base/trace_event/trace_event.h"
  14 #include "ipc/attachment_broker.h"
  15 #include "ipc/brokerable_attachment.h"
  16 #include "ipc/ipc_export.h"
  17
  18 #if !defined(NDEBUG)
  19 #define IPC_MESSAGE_LOG_ENABLED
  20 #endif
  21
  22 namespace IPC {
  23
  24 namespace internal {
  25 class ChannelReader;
  26 }  // namespace internal
  27
  28 //------------------------------------------------------------------------------
  29
  30 struct LogData;
  31 class MessageAttachment;
  32 class MessageAttachmentSet;
  33
  34 class IPC_EXPORT Message : public base::Pickle {
  35  public:
  36   enum PriorityValue {
  37     PRIORITY_LOW = 1,
  38     PRIORITY_NORMAL,
  39     PRIORITY_HIGH
  40   };
  41
  42   // Bit values used in the flags field.
  43   // Upper 24 bits of flags store a reference number, so this enum is limited to
  44   // 8 bits.
  45   enum {
  46     PRIORITY_MASK     = 0x03,  // Low 2 bits of store the priority value.
  47     SYNC_BIT          = 0x04,
  48     REPLY_BIT         = 0x08,
  49     REPLY_ERROR_BIT   = 0x10,
  50     UNBLOCK_BIT       = 0x20,
  51     PUMPING_MSGS_BIT  = 0x40,
  52     HAS_SENT_TIME_BIT = 0x80,
  53   };
  54
  55   ~Message() override;
  56
  57   Message();
  58
  59   // Initialize a message with a user-defined type, priority value, and
  60   // destination WebView ID.
  61   Message(int32 routing_id, uint32 type, PriorityValue priority);
  62
  63   // Initializes a message from a const block of data.  The data is not copied;
  64   // instead the data is merely referenced by this message.  Only const methods
  65   // should be used on the message when initialized this way.
  66   Message(const char* data, int data_len);
  67
  68   Message(const Message& other);
  69   Message& operator=(const Message& other);
  70
  71   PriorityValue priority() const {
  72     return static_cast<PriorityValue>(header()->flags & PRIORITY_MASK);
  73   }
  74
  75   // True if this is a synchronous message.
  76   void set_sync() {
  77     header()->flags |= SYNC_BIT;
  78   }
  79   bool is_sync() const {
  80     return (header()->flags & SYNC_BIT) != 0;
  81   }
  82
  83   // Set this on a reply to a synchronous message.
  84   void set_reply() {
  85     header()->flags |= REPLY_BIT;
  86   }
  87
  88   bool is_reply() const {
  89     return (header()->flags & REPLY_BIT) != 0;
  90   }
  91
  92   // Set this on a reply to a synchronous message to indicate that no receiver
  93   // was found.
  94   void set_reply_error() {
  95     header()->flags |= REPLY_ERROR_BIT;
  96   }
  97
  98   bool is_reply_error() const {
  99     return (header()->flags & REPLY_ERROR_BIT) != 0;
 100   }
 101
 102   // Normally when a receiver gets a message and they're blocked on a
 103   // synchronous message Send, they buffer a message.  Setting this flag causes
 104   // the receiver to be unblocked and the message to be dispatched immediately.
 105   void set_unblock(bool unblock) {
 106     if (unblock) {
 107       header()->flags |= UNBLOCK_BIT;
 108     } else {
 109       header()->flags &= ~UNBLOCK_BIT;
 110     }
 111   }
 112
 113   bool should_unblock() const {
 114     return (header()->flags & UNBLOCK_BIT) != 0;
 115   }
 116
 117   // Tells the receiver that the caller is pumping messages while waiting
 118   // for the result.
 119   bool is_caller_pumping_messages() const {
 120     return (header()->flags & PUMPING_MSGS_BIT) != 0;
 121   }
 122
 123   void set_dispatch_error() const {
 124     dispatch_error_ = true;
 125   }
 126
 127   bool dispatch_error() const {
 128     return dispatch_error_;
 129   }
 130
 131   uint32 type() const {
 132     return header()->type;
 133   }
 134
 135   int32 routing_id() const {
 136     return header()->routing;
 137   }
 138
 139   void set_routing_id(int32 new_id) {
 140     header()->routing = new_id;
 141   }
 142
 143   uint32 flags() const {
 144     return header()->flags;
 145   }
 146
 147   // Sets all the given header values. The message should be empty at this
 148   // call.
 149   void SetHeaderValues(int32 routing, uint32 type, uint32 flags);
 150
 151   template<class T, class S, class P>
 152   static bool Dispatch(const Message* msg, T* obj, S* sender, P* parameter,
 153                        void (T::*func)()) {
 154     (obj->*func)();
 155     return true;
 156   }
 157
 158   template<class T, class S, class P>
 159   static bool Dispatch(const Message* msg, T* obj, S* sender, P* parameter,
 160                        void (T::*func)(P*)) {
 161     (obj->*func)(parameter);
 162     return true;
 163   }
 164
 165   // Used for async messages with no parameters.
 166   static void Log(std::string* name, const Message* msg, std::string* l) {
 167   }
 168
 169   // The static method FindNext() returns several pieces of information, which
 170   // are aggregated into an instance of this struct.
 171   struct NextMessageInfo {
 172     NextMessageInfo();
 173     ~NextMessageInfo();
 174     // Whether an entire message was found in the given memory range. If this is
 175     // false, the other fields are left uninitialized.
 176     bool message_found;
 177     // The start address is passed into FindNext() by the caller, so isn't
 178     // repeated in this struct. The end address of the pickle should be used to
 179     // construct a base::Pickle.
 180     const char* pickle_end;
 181     // The end address of the message should be used to determine the start
 182     // address of the next message.
 183     const char* message_end;
 184     // If the message has brokerable attachments, this vector will contain the
 185     // ids of the brokerable attachments. The caller of FindNext() is
 186     // responsible for adding the attachments to the message.
 187     std::vector<BrokerableAttachment::AttachmentId> attachment_ids;
 188   };
 189
 190   static NextMessageInfo FindNext(const char* range_start,
 191                                   const char* range_end);
 192
 193   struct SerializedAttachmentIds {
 194     void* buffer;
 195     size_t size;
 196   };
 197   // Creates a buffer that contains a serialization of the ids of the brokerable
 198   // attachments of the message. This buffer is intended to be sent over the IPC
 199   // channel immediately after the pickled message. The caller takes ownership
 200   // of the buffer.
 201   // This method should only be called if the message has brokerable
 202   // attachments.
 203   SerializedAttachmentIds SerializedIdsOfBrokerableAttachments();
 204
 205   // Adds a placeholder brokerable attachment that must be replaced before the
 206   // message can be dispatched.
 207   bool AddPlaceholderBrokerableAttachmentWithId(
 208       BrokerableAttachment::AttachmentId id);
 209
 210   // WriteAttachment appends |attachment| to the end of the set. It returns
 211   // false iff the set is full.
 212   bool WriteAttachment(scoped_refptr<MessageAttachment> attachment);
 213   // ReadAttachment parses an attachment given the parsing state |iter| and
 214   // writes it to |*attachment|. It returns true on success.
 215   bool ReadAttachment(base::PickleIterator* iter,
 216                       scoped_refptr<MessageAttachment>* attachment) const;
 217   // Returns true if there are any attachment in this message.
 218   bool HasAttachments() const;
 219   // Returns true if there are any MojoHandleAttachments in this message.
 220   bool HasMojoHandles() const;
 221   // Whether the message has any brokerable attachments.
 222   bool HasBrokerableAttachments() const;
 223
 224   void set_sender_pid(base::ProcessId id) { sender_pid_ = id; }
 225   base::ProcessId get_sender_pid() const { return sender_pid_; }
 226
 227 #ifdef IPC_MESSAGE_LOG_ENABLED
 228   // Adds the outgoing time from Time::Now() at the end of the message and sets
 229   // a bit to indicate that it's been added.
 230   void set_sent_time(int64 time);
 231   int64 sent_time() const;
 232
 233   void set_received_time(int64 time) const;
 234   int64 received_time() const { return received_time_; }
 235   void set_output_params(const std::string& op) const { output_params_ = op; }
 236   const std::string& output_params() const { return output_params_; }
 237   // The following four functions are needed so we can log sync messages with
 238   // delayed replies.  We stick the log data from the sent message into the
 239   // reply message, so that when it's sent and we have the output parameters
 240   // we can log it.  As such, we set a flag on the sent message to not log it.
 241   void set_sync_log_data(LogData* data) const { log_data_ = data; }
 242   LogData* sync_log_data() const { return log_data_; }
 243   void set_dont_log() const { dont_log_ = true; }
 244   bool dont_log() const { return dont_log_; }
 245 #endif
 246
 247  protected:
 248   friend class Channel;
 249   friend class ChannelMojo;
 250   friend class ChannelNacl;
 251   friend class ChannelPosix;
 252   friend class ChannelWin;
 253   friend class internal::ChannelReader;
 254   friend class MessageReplyDeserializer;
 255   friend class SyncMessage;
 256
 257 #pragma pack(push, 4)
 258   struct Header : base::Pickle::Header {
 259     int32 routing;  // ID of the view that this message is destined for
 260     uint32 type;    // specifies the user-defined message type
 261     uint32 flags;   // specifies control flags for the message
 262 #if USE_ATTACHMENT_BROKER
 263     // The number of brokered attachments included with this message. The
 264     // ids of the brokered attachment ids are sent immediately after the pickled
 265     // message, before the next pickled message is sent.
 266     uint32 num_brokered_attachments;
 267 #endif
 268 #if defined(OS_POSIX)
 269     uint16 num_fds; // the number of descriptors included with this message
 270     uint16 pad;     // explicitly initialize this to appease valgrind
 271 #endif
 272   };
 273 #pragma pack(pop)
 274
 275   Header* header() {
 276     return headerT<Header>();
 277   }
 278   const Header* header() const {
 279     return headerT<Header>();
 280   }
 281
 282   void Init();
 283
 284   // Used internally to support IPC::Listener::OnBadMessageReceived.
 285   mutable bool dispatch_error_;
 286
 287   // The set of file descriptors associated with this message.
 288   scoped_refptr<MessageAttachmentSet> attachment_set_;
 289
 290   // Ensure that a MessageAttachmentSet is allocated
 291   void EnsureMessageAttachmentSet();
 292
 293   MessageAttachmentSet* attachment_set() {
 294     EnsureMessageAttachmentSet();
 295     return attachment_set_.get();
 296   }
 297   const MessageAttachmentSet* attachment_set() const {
 298     return attachment_set_.get();
 299   }
 300
 301   // The process id of the sender of the message. This member is populated with
 302   // a valid value for every message dispatched to listeners.
 303   base::ProcessId sender_pid_;
 304
 305 #ifdef IPC_MESSAGE_LOG_ENABLED
 306   // Used for logging.
 307   mutable int64 received_time_;
 308   mutable std::string output_params_;
 309   mutable LogData* log_data_;
 310   mutable bool dont_log_;
 311 #endif
 312 };
 313
 314 //------------------------------------------------------------------------------
 315
 316 }  // namespace IPC
 317
 318 enum SpecialRoutingIDs {
 319   // indicates that we don't have a routing ID yet.
 320   MSG_ROUTING_NONE = -2,
 321
 322   // indicates a general message not sent to a particular tab.
 323   MSG_ROUTING_CONTROL = kint32max,
 324 };
 325
 326 #define IPC_REPLY_ID 0xFFFFFFF0  // Special message id for replies
 327 #define IPC_LOGGING_ID 0xFFFFFFF1  // Special message id for logging
 328
 329 #endif  // IPC_IPC_MESSAGE_H_