ipc/ipc_message.h

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