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