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/debug/trace_event.h"
  12 #include "base/pickle.h"
  13 #include "ipc/ipc_export.h"
  14
  15 #if !defined(NDEBUG)
  16 #define IPC_MESSAGE_LOG_ENABLED
  17 #endif
  18
  19 #if defined(OS_POSIX)
  20 #include "base/memory/ref_counted.h"
  21 #endif
  22
  23 namespace base {
  24 struct FileDescriptor;
  25 }
  26
  27 class FileDescriptorSet;
  28
  29 namespace IPC {
  30
  31 //------------------------------------------------------------------------------
  32
  33 struct LogData;
  34
  35 class IPC_EXPORT Message : public Pickle {
  36  public:
  37   enum PriorityValue {
  38     PRIORITY_LOW = 1,
  39     PRIORITY_NORMAL,
  40     PRIORITY_HIGH
  41   };
  42
  43   // Bit values used in the flags field.
  44   // Upper 24 bits of flags store a reference number, so this enum is limited to
  45   // 8 bits.
  46   enum {
  47     PRIORITY_MASK     = 0x03,  // Low 2 bits of store the priority value.
  48     SYNC_BIT          = 0x04,
  49     REPLY_BIT         = 0x08,
  50     REPLY_ERROR_BIT   = 0x10,
  51     UNBLOCK_BIT       = 0x20,
  52     PUMPING_MSGS_BIT  = 0x40,
  53     HAS_SENT_TIME_BIT = 0x80,
  54   };
  55
  56   virtual ~Message();
  57
  58   Message();
  59
  60   // Initialize a message with a user-defined type, priority value, and
  61   // destination WebView ID.
  62   Message(int32 routing_id, uint32 type, PriorityValue priority);
  63
  64   // Initializes a message from a const block of data.  The data is not copied;
  65   // instead the data is merely referenced by this message.  Only const methods
  66   // should be used on the message when initialized this way.
  67   Message(const char* data, int data_len);
  68
  69   Message(const Message& other);
  70   Message& operator=(const Message& other);
  71
  72   PriorityValue priority() const {
  73     return static_cast<PriorityValue>(header()->flags & PRIORITY_MASK);
  74   }
  75
  76   // True if this is a synchronous message.
  77   void set_sync() {
  78     header()->flags |= SYNC_BIT;
  79   }
  80   bool is_sync() const {
  81     return (header()->flags & SYNC_BIT) != 0;
  82   }
  83
  84   // Set this on a reply to a synchronous message.
  85   void set_reply() {
  86     header()->flags |= REPLY_BIT;
  87   }
  88
  89   bool is_reply() const {
  90     return (header()->flags & REPLY_BIT) != 0;
  91   }
  92
  93   // Set this on a reply to a synchronous message to indicate that no receiver
  94   // was found.
  95   void set_reply_error() {
  96     header()->flags |= REPLY_ERROR_BIT;
  97   }
  98
  99   bool is_reply_error() const {
 100     return (header()->flags & REPLY_ERROR_BIT) != 0;
 101   }
 102
 103   // Normally when a receiver gets a message and they're blocked on a
 104   // synchronous message Send, they buffer a message.  Setting this flag causes
 105   // the receiver to be unblocked and the message to be dispatched immediately.
 106   void set_unblock(bool unblock) {
 107     if (unblock) {
 108       header()->flags |= UNBLOCK_BIT;
 109     } else {
 110       header()->flags &= ~UNBLOCK_BIT;
 111     }
 112   }
 113
 114   bool should_unblock() const {
 115     return (header()->flags & UNBLOCK_BIT) != 0;
 116   }
 117
 118   // Tells the receiver that the caller is pumping messages while waiting
 119   // for the result.
 120   bool is_caller_pumping_messages() const {
 121     return (header()->flags & PUMPING_MSGS_BIT) != 0;
 122   }
 123
 124   uint32 type() const {
 125     return header()->type;
 126   }
 127
 128   int32 routing_id() const {
 129     return header()->routing;
 130   }
 131
 132   void set_routing_id(int32 new_id) {
 133     header()->routing = new_id;
 134   }
 135
 136   uint32 flags() const {
 137     return header()->flags;
 138   }
 139
 140   // Sets all the given header values. The message should be empty at this
 141   // call.
 142   void SetHeaderValues(int32 routing, uint32 type, uint32 flags);
 143
 144   template<class T, class S>
 145   static bool Dispatch(const Message* msg, T* obj, S* sender,
 146                        void (T::*func)()) {
 147     (obj->*func)();
 148     return true;
 149   }
 150
 151   template<class T, class S>
 152   static bool Dispatch(const Message* msg, T* obj, S* sender,
 153                        void (T::*func)() const) {
 154     (obj->*func)();
 155     return true;
 156   }
 157
 158   template<class T, class S>
 159   static bool Dispatch(const Message* msg, T* obj, S* sender,
 160                        void (T::*func)(const Message&)) {
 161     (obj->*func)(*msg);
 162     return true;
 163   }
 164
 165   template<class T, class S>
 166   static bool Dispatch(const Message* msg, T* obj, S* sender,
 167                        void (T::*func)(const Message&) const) {
 168     (obj->*func)(*msg);
 169     return true;
 170   }
 171
 172   // Used for async messages with no parameters.
 173   static void Log(std::string* name, const Message* msg, std::string* l) {
 174   }
 175
 176   // Find the end of the message data that starts at range_start.  Returns NULL
 177   // if the entire message is not found in the given data range.
 178   static const char* FindNext(const char* range_start, const char* range_end) {
 179     return Pickle::FindNext(sizeof(Header), range_start, range_end);
 180   }
 181
 182 #if defined(OS_POSIX)
 183   // On POSIX, a message supports reading / writing FileDescriptor objects.
 184   // This is used to pass a file descriptor to the peer of an IPC channel.
 185
 186   // Add a descriptor to the end of the set. Returns false if the set is full.
 187   bool WriteFileDescriptor(const base::FileDescriptor& descriptor);
 188
 189   // Get a file descriptor from the message. Returns false on error.
 190   //   iter: a Pickle iterator to the current location in the message.
 191   bool ReadFileDescriptor(PickleIterator* iter,
 192                           base::FileDescriptor* descriptor) const;
 193
 194   // Returns true if there are any file descriptors in this message.
 195   bool HasFileDescriptors() const;
 196 #endif
 197
 198 #ifdef IPC_MESSAGE_LOG_ENABLED
 199   // Adds the outgoing time from Time::Now() at the end of the message and sets
 200   // a bit to indicate that it's been added.
 201   void set_sent_time(int64 time);
 202   int64 sent_time() const;
 203
 204   void set_received_time(int64 time) const;
 205   int64 received_time() const { return received_time_; }
 206   void set_output_params(const std::string& op) const { output_params_ = op; }
 207   const std::string& output_params() const { return output_params_; }
 208   // The following four functions are needed so we can log sync messages with
 209   // delayed replies.  We stick the log data from the sent message into the
 210   // reply message, so that when it's sent and we have the output parameters
 211   // we can log it.  As such, we set a flag on the sent message to not log it.
 212   void set_sync_log_data(LogData* data) const { log_data_ = data; }
 213   LogData* sync_log_data() const { return log_data_; }
 214   void set_dont_log() const { dont_log_ = true; }
 215   bool dont_log() const { return dont_log_; }
 216 #endif
 217
 218   // Called to trace when message is sent.
 219   void TraceMessageBegin() {
 220     TRACE_EVENT_FLOW_BEGIN0(TRACE_DISABLED_BY_DEFAULT("toplevel.flow"), "IPC",
 221         header()->flags);
 222   }
 223   // Called to trace when message is received.
 224   void TraceMessageEnd() {
 225     TRACE_EVENT_FLOW_END0(TRACE_DISABLED_BY_DEFAULT("toplevel.flow"), "IPC",
 226         header()->flags);
 227   }
 228
 229  protected:
 230   friend class Channel;
 231   friend class MessageReplyDeserializer;
 232   friend class SyncMessage;
 233
 234 #pragma pack(push, 4)
 235   struct Header : Pickle::Header {
 236     int32 routing;  // ID of the view that this message is destined for
 237     uint32 type;    // specifies the user-defined message type
 238     uint32 flags;   // specifies control flags for the message
 239 #if defined(OS_POSIX)
 240     uint16 num_fds; // the number of descriptors included with this message
 241     uint16 pad;     // explicitly initialize this to appease valgrind
 242 #endif
 243   };
 244 #pragma pack(pop)
 245
 246   Header* header() {
 247     return headerT<Header>();
 248   }
 249   const Header* header() const {
 250     return headerT<Header>();
 251   }
 252
 253   void InitLoggingVariables();
 254
 255 #if defined(OS_POSIX)
 256   // The set of file descriptors associated with this message.
 257   scoped_refptr<FileDescriptorSet> file_descriptor_set_;
 258
 259   // Ensure that a FileDescriptorSet is allocated
 260   void EnsureFileDescriptorSet();
 261
 262   FileDescriptorSet* file_descriptor_set() {
 263     EnsureFileDescriptorSet();
 264     return file_descriptor_set_.get();
 265   }
 266   const FileDescriptorSet* file_descriptor_set() const {
 267     return file_descriptor_set_.get();
 268   }
 269 #endif
 270
 271 #ifdef IPC_MESSAGE_LOG_ENABLED
 272   // Used for logging.
 273   mutable int64 received_time_;
 274   mutable std::string output_params_;
 275   mutable LogData* log_data_;
 276   mutable bool dont_log_;
 277 #endif
 278 };
 279
 280 //------------------------------------------------------------------------------
 281
 282 }  // namespace IPC
 283
 284 enum SpecialRoutingIDs {
 285   // indicates that we don't have a routing ID yet.
 286   MSG_ROUTING_NONE = -2,
 287
 288   // indicates a general message not sent to a particular tab.
 289   MSG_ROUTING_CONTROL = kint32max,
 290 };
 291
 292 #define IPC_REPLY_ID 0xFFFFFFF0  // Special message id for replies
 293 #define IPC_LOGGING_ID 0xFFFFFFF1  // Special message id for logging
 294
 295 #endif  // IPC_IPC_MESSAGE_H_