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