message.h revision 5821806d5e7f356e8fa4b058a389a808ea183019
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 DBUS_MESSAGE_H_ 6#define DBUS_MESSAGE_H_ 7 8#include <string> 9#include <vector> 10#include <dbus/dbus.h> 11 12#include "base/basictypes.h" 13#include "dbus/dbus_export.h" 14#include "dbus/file_descriptor.h" 15#include "dbus/object_path.h" 16 17namespace google { 18namespace protobuf { 19 20class MessageLite; 21 22} // namespace protobuf 23} // namespace google 24 25 26namespace dbus { 27 28class MessageWriter; 29class MessageReader; 30 31// DBUS_TYPE_UNIX_FD was added in D-Bus version 1.4 32#if !defined(DBUS_TYPE_UNIX_FD) 33#define DBUS_TYPE_UNIX_FD ((int) 'h') 34#endif 35 36// Returns true if Unix FD passing is supported in libdbus. 37// The check is done runtime rather than compile time as the libdbus 38// version used at runtime may be different from the one used at compile time. 39CHROME_DBUS_EXPORT bool IsDBusTypeUnixFdSupported(); 40 41// Message is the base class of D-Bus message types. Client code must use 42// sub classes such as MethodCall and Response instead. 43// 44// The class name Message is very generic, but there should be no problem 45// as the class is inside 'dbus' namespace. We chose to name this way, as 46// libdbus defines lots of types starting with DBus, such as 47// DBusMessage. We should avoid confusion and conflict with these types. 48class CHROME_DBUS_EXPORT Message { 49 public: 50 // The message type used in D-Bus. Redefined here so client code 51 // doesn't need to use raw D-Bus macros. DBUS_MESSAGE_TYPE_INVALID 52 // etc. are #define macros. Having an enum type here makes code a bit 53 // more type-safe. 54 enum MessageType { 55 MESSAGE_INVALID = DBUS_MESSAGE_TYPE_INVALID, 56 MESSAGE_METHOD_CALL = DBUS_MESSAGE_TYPE_METHOD_CALL, 57 MESSAGE_METHOD_RETURN = DBUS_MESSAGE_TYPE_METHOD_RETURN, 58 MESSAGE_SIGNAL = DBUS_MESSAGE_TYPE_SIGNAL, 59 MESSAGE_ERROR = DBUS_MESSAGE_TYPE_ERROR, 60 }; 61 62 // The data type used in the D-Bus type system. See the comment at 63 // MessageType for why we are redefining data types here. 64 enum DataType { 65 INVALID_DATA = DBUS_TYPE_INVALID, 66 BYTE = DBUS_TYPE_BYTE, 67 BOOL = DBUS_TYPE_BOOLEAN, 68 INT16 = DBUS_TYPE_INT16, 69 UINT16 = DBUS_TYPE_UINT16, 70 INT32 = DBUS_TYPE_INT32, 71 UINT32 = DBUS_TYPE_UINT32, 72 INT64 = DBUS_TYPE_INT64, 73 UINT64 = DBUS_TYPE_UINT64, 74 DOUBLE = DBUS_TYPE_DOUBLE, 75 STRING = DBUS_TYPE_STRING, 76 OBJECT_PATH = DBUS_TYPE_OBJECT_PATH, 77 ARRAY = DBUS_TYPE_ARRAY, 78 STRUCT = DBUS_TYPE_STRUCT, 79 DICT_ENTRY = DBUS_TYPE_DICT_ENTRY, 80 VARIANT = DBUS_TYPE_VARIANT, 81 UNIX_FD = DBUS_TYPE_UNIX_FD, 82 }; 83 84 // Returns the type of the message. Returns MESSAGE_INVALID if 85 // raw_message_ is NULL. 86 MessageType GetMessageType(); 87 88 // Returns the type of the message as string like "MESSAGE_METHOD_CALL" 89 // for instance. 90 std::string GetMessageTypeAsString(); 91 92 DBusMessage* raw_message() { return raw_message_; } 93 94 // Sets the destination, the path, the interface, the member, etc. 95 bool SetDestination(const std::string& destination); 96 bool SetPath(const ObjectPath& path); 97 bool SetInterface(const std::string& interface); 98 bool SetMember(const std::string& member); 99 bool SetErrorName(const std::string& error_name); 100 bool SetSender(const std::string& sender); 101 void SetSerial(uint32 serial); 102 void SetReplySerial(uint32 reply_serial); 103 // SetSignature() does not exist as we cannot do it. 104 105 // Gets the destination, the path, the interface, the member, etc. 106 // If not set, an empty string is returned. 107 std::string GetDestination(); 108 ObjectPath GetPath(); 109 std::string GetInterface(); 110 std::string GetMember(); 111 std::string GetErrorName(); 112 std::string GetSender(); 113 std::string GetSignature(); 114 // Gets the serial and reply serial numbers. Returns 0 if not set. 115 uint32 GetSerial(); 116 uint32 GetReplySerial(); 117 118 // Returns the string representation of this message. Useful for 119 // debugging. The output is truncated as needed (ex. strings are truncated 120 // if longer than a certain limit defined in the .cc file). 121 std::string ToString(); 122 123 protected: 124 // This class cannot be instantiated. Use sub classes instead. 125 Message(); 126 virtual ~Message(); 127 128 // Initializes the message with the given raw message. 129 void Init(DBusMessage* raw_message); 130 131 private: 132 // Helper function used in ToString(). 133 std::string ToStringInternal(const std::string& indent, 134 MessageReader* reader); 135 136 DBusMessage* raw_message_; 137 DISALLOW_COPY_AND_ASSIGN(Message); 138}; 139 140// MessageCall is a type of message used for calling a method via D-Bus. 141class CHROME_DBUS_EXPORT MethodCall : public Message { 142 public: 143 // Creates a method call message for the specified interface name and 144 // the method name. 145 // 146 // For instance, to call "Get" method of DBUS_INTERFACE_INTROSPECTABLE 147 // interface ("org.freedesktop.DBus.Introspectable"), create a method 148 // call like this: 149 // 150 // MethodCall method_call(DBUS_INTERFACE_INTROSPECTABLE, "Get"); 151 // 152 // The constructor creates the internal raw message. 153 MethodCall(const std::string& interface_name, 154 const std::string& method_name); 155 156 // Returns a newly created MethodCall from the given raw message of the 157 // type DBUS_MESSAGE_TYPE_METHOD_CALL. The caller must delete the 158 // returned object. Takes the ownership of |raw_message|. 159 static MethodCall* FromRawMessage(DBusMessage* raw_message); 160 161 private: 162 // Creates a method call message. The internal raw message is NULL. 163 // Only used internally. 164 MethodCall(); 165 166 DISALLOW_COPY_AND_ASSIGN(MethodCall); 167}; 168 169// Signal is a type of message used to send a signal. 170class CHROME_DBUS_EXPORT Signal : public Message { 171 public: 172 // Creates a signal message for the specified interface name and the 173 // method name. 174 // 175 // For instance, to send "PropertiesChanged" signal of 176 // DBUS_INTERFACE_INTROSPECTABLE interface 177 // ("org.freedesktop.DBus.Introspectable"), create a signal like this: 178 // 179 // Signal signal(DBUS_INTERFACE_INTROSPECTABLE, "PropertiesChanged"); 180 // 181 // The constructor creates the internal raw_message_. 182 Signal(const std::string& interface_name, 183 const std::string& method_name); 184 185 // Returns a newly created SIGNAL from the given raw message of the type 186 // DBUS_MESSAGE_TYPE_SIGNAL. The caller must delete the returned 187 // object. Takes the ownership of |raw_message|. 188 static Signal* FromRawMessage(DBusMessage* raw_message); 189 190 private: 191 // Creates a signal message. The internal raw message is NULL. 192 // Only used internally. 193 Signal(); 194 195 DISALLOW_COPY_AND_ASSIGN(Signal); 196}; 197 198// Response is a type of message used for receiving a response from a 199// method via D-Bus. 200class CHROME_DBUS_EXPORT Response : public Message { 201 public: 202 // Returns a newly created Response from the given raw message of the 203 // type DBUS_MESSAGE_TYPE_METHOD_RETURN. The caller must delete the 204 // returned object. Takes the ownership of |raw_message|. 205 static Response* FromRawMessage(DBusMessage* raw_message); 206 207 // Returns a newly created Response from the given method call. The 208 // caller must delete the returned object. Used for implementing 209 // exported methods. 210 static Response* FromMethodCall(MethodCall* method_call); 211 212 // Returns a newly created Response with an empty payload. The caller 213 // must delete the returned object. Useful for testing. 214 static Response* CreateEmpty(); 215 216 protected: 217 // Creates a Response message. The internal raw message is NULL. 218 Response(); 219 220 private: 221 DISALLOW_COPY_AND_ASSIGN(Response); 222}; 223 224// ErrorResponse is a type of message used to return an error to the 225// caller of a method. 226class CHROME_DBUS_EXPORT ErrorResponse: public Response { 227 public: 228 // Returns a newly created Response from the given raw message of the 229 // type DBUS_MESSAGE_TYPE_METHOD_RETURN. The caller must delete the 230 // returned object. Takes the ownership of |raw_message|. 231 static ErrorResponse* FromRawMessage(DBusMessage* raw_message); 232 233 // Returns a newly created ErrorResponse from the given method call, the 234 // error name, and the error message. The error name looks like 235 // "org.freedesktop.DBus.Error.Failed". Used for returning an error to a 236 // failed method call. 237 static ErrorResponse* FromMethodCall(MethodCall* method_call, 238 const std::string& error_name, 239 const std::string& error_message); 240 241 private: 242 // Creates an ErrorResponse message. The internal raw message is NULL. 243 ErrorResponse(); 244 245 DISALLOW_COPY_AND_ASSIGN(ErrorResponse); 246}; 247 248// MessageWriter is used to write outgoing messages for calling methods 249// and sending signals. 250// 251// The main design goal of MessageReader and MessageWriter classes is to 252// provide a type safe API. In the past, there was a Chrome OS blocker 253// bug, that took days to fix, that would have been prevented if the API 254// was type-safe. 255// 256// For instance, instead of doing something like: 257// 258// // We shouldn't add '&' to str here, but it compiles with '&' added. 259// dbus_g_proxy_call(..., G_TYPE_STRING, str, G_TYPE_INVALID, ...) 260// 261// We want to do something like: 262// 263// writer.AppendString(str); 264// 265class CHROME_DBUS_EXPORT MessageWriter { 266 public: 267 // Data added with Append* will be written to |message|, which may be NULL 268 // to create a sub-writer for passing to OpenArray, etc. 269 explicit MessageWriter(Message* message); 270 ~MessageWriter(); 271 272 // Appends a byte to the message. 273 void AppendByte(uint8 value); 274 void AppendBool(bool value); 275 void AppendInt16(int16 value); 276 void AppendUint16(uint16 value); 277 void AppendInt32(int32 value); 278 void AppendUint32(uint32 value); 279 void AppendInt64(int64 value); 280 void AppendUint64(uint64 value); 281 void AppendDouble(double value); 282 void AppendString(const std::string& value); 283 void AppendObjectPath(const ObjectPath& value); 284 void AppendFileDescriptor(const FileDescriptor& value); 285 286 // Opens an array. The array contents can be added to the array with 287 // |sub_writer|. The client code must close the array with 288 // CloseContainer(), once all contents are added. 289 // 290 // |signature| parameter is used to supply the D-Bus type signature of 291 // the array contents. For instance, if you want an array of strings, 292 // then you pass "s" as the signature. 293 // 294 // See the spec for details about the type signatures. 295 // http://dbus.freedesktop.org/doc/dbus-specification.html 296 // #message-protocol-signatures 297 // 298 void OpenArray(const std::string& signature, MessageWriter* sub_writer); 299 // Do the same for a variant. 300 void OpenVariant(const std::string& signature, MessageWriter* sub_writer); 301 // Do the same for Struct and dict entry. They don't need the signature. 302 void OpenStruct(MessageWriter* sub_writer); 303 void OpenDictEntry(MessageWriter* sub_writer); 304 305 // Close the container for a array/variant/struct/dict entry. 306 void CloseContainer(MessageWriter* sub_writer); 307 308 // Appends the array of bytes. Arrays of bytes are often used for 309 // exchanging binary blobs hence it's worth having a specialized 310 // function. 311 void AppendArrayOfBytes(const uint8* values, size_t length); 312 313 // Appends the array of strings. Arrays of strings are often used for 314 // exchanging lists of names hence it's worth having a specialized 315 // function. 316 void AppendArrayOfStrings(const std::vector<std::string>& strings); 317 318 // Appends the array of object paths. Arrays of object paths are often 319 // used when exchanging object paths, hence it's worth having a 320 // specialized function. 321 void AppendArrayOfObjectPaths(const std::vector<ObjectPath>& object_paths); 322 323 // Appends the protocol buffer as an array of bytes. The buffer is serialized 324 // into an array of bytes before communication, since protocol buffers are not 325 // a native dbus type. On the receiving size the array of bytes needs to be 326 // read and deserialized into a protocol buffer of the correct type. There are 327 // methods in MessageReader to assist in this. Return true on succes and fail 328 // when serialization is not successful. 329 bool AppendProtoAsArrayOfBytes(const google::protobuf::MessageLite& protobuf); 330 331 // Appends the byte wrapped in a variant data container. Variants are 332 // widely used in D-Bus services so it's worth having a specialized 333 // function. For instance, The third parameter of 334 // "org.freedesktop.DBus.Properties.Set" is a variant. 335 void AppendVariantOfByte(uint8 value); 336 void AppendVariantOfBool(bool value); 337 void AppendVariantOfInt16(int16 value); 338 void AppendVariantOfUint16(uint16 value); 339 void AppendVariantOfInt32(int32 value); 340 void AppendVariantOfUint32(uint32 value); 341 void AppendVariantOfInt64(int64 value); 342 void AppendVariantOfUint64(uint64 value); 343 void AppendVariantOfDouble(double value); 344 void AppendVariantOfString(const std::string& value); 345 void AppendVariantOfObjectPath(const ObjectPath& value); 346 347 private: 348 // Helper function used to implement AppendByte etc. 349 void AppendBasic(int dbus_type, const void* value); 350 351 // Helper function used to implement AppendVariantOfByte() etc. 352 void AppendVariantOfBasic(int dbus_type, const void* value); 353 354 Message* message_; 355 DBusMessageIter raw_message_iter_; 356 bool container_is_open_; 357 358 DISALLOW_COPY_AND_ASSIGN(MessageWriter); 359}; 360 361// MessageReader is used to read incoming messages such as responses for 362// method calls. 363// 364// MessageReader manages an internal iterator to read data. All functions 365// starting with Pop advance the iterator on success. 366class CHROME_DBUS_EXPORT MessageReader { 367 public: 368 // The data will be read from the given |message|, which may be NULL to 369 // create a sub-reader for passing to PopArray, etc. 370 explicit MessageReader(Message* message); 371 ~MessageReader(); 372 373 // Returns true if the reader has more data to read. The function is 374 // used to iterate contents in a container like: 375 // 376 // while (reader.HasMoreData()) 377 // reader.PopString(&value); 378 bool HasMoreData(); 379 380 // Gets the byte at the current iterator position. 381 // Returns true and advances the iterator on success. 382 // Returns false if the data type is not a byte. 383 bool PopByte(uint8* value); 384 bool PopBool(bool* value); 385 bool PopInt16(int16* value); 386 bool PopUint16(uint16* value); 387 bool PopInt32(int32* value); 388 bool PopUint32(uint32* value); 389 bool PopInt64(int64* value); 390 bool PopUint64(uint64* value); 391 bool PopDouble(double* value); 392 bool PopString(std::string* value); 393 bool PopObjectPath(ObjectPath* value); 394 bool PopFileDescriptor(FileDescriptor* value); 395 396 // Sets up the given message reader to read an array at the current 397 // iterator position. 398 // Returns true and advances the iterator on success. 399 // Returns false if the data type is not an array 400 bool PopArray(MessageReader* sub_reader); 401 bool PopStruct(MessageReader* sub_reader); 402 bool PopDictEntry(MessageReader* sub_reader); 403 bool PopVariant(MessageReader* sub_reader); 404 405 // Gets the array of bytes at the current iterator position. 406 // Returns true and advances the iterator on success. 407 // 408 // Arrays of bytes are often used for exchanging binary blobs hence it's 409 // worth having a specialized function. 410 // 411 // |bytes| must be copied if the contents will be referenced after the 412 // MessageReader is destroyed. 413 bool PopArrayOfBytes(uint8** bytes, size_t* length); 414 415 // Gets the array of strings at the current iterator position. 416 // Returns true and advances the iterator on success. 417 // 418 // Arrays of strings are often used to communicate with D-Bus 419 // services like KWallet, hence it's worth having a specialized 420 // function. 421 bool PopArrayOfStrings(std::vector<std::string>* strings); 422 423 // Gets the array of object paths at the current iterator position. 424 // Returns true and advances the iterator on success. 425 // 426 // Arrays of object paths are often used to communicate with D-Bus 427 // services like NetworkManager, hence it's worth having a specialized 428 // function. 429 bool PopArrayOfObjectPaths(std::vector<ObjectPath>* object_paths); 430 431 // Gets the array of bytes at the current iterator position. It then parses 432 // this binary blob into the protocol buffer supplied. 433 // Returns true and advances the iterator on success. On failure returns false 434 // and emits an error message on the source of the failure. The two most 435 // common errors come from the iterator not currently being at a byte array or 436 // the wrong type of protocol buffer is passed in and the parse fails. 437 bool PopArrayOfBytesAsProto(google::protobuf::MessageLite* protobuf); 438 439 // Gets the byte from the variant data container at the current iterator 440 // position. 441 // Returns true and advances the iterator on success. 442 // 443 // Variants are widely used in D-Bus services so it's worth having a 444 // specialized function. For instance, The return value type of 445 // "org.freedesktop.DBus.Properties.Get" is a variant. 446 bool PopVariantOfByte(uint8* value); 447 bool PopVariantOfBool(bool* value); 448 bool PopVariantOfInt16(int16* value); 449 bool PopVariantOfUint16(uint16* value); 450 bool PopVariantOfInt32(int32* value); 451 bool PopVariantOfUint32(uint32* value); 452 bool PopVariantOfInt64(int64* value); 453 bool PopVariantOfUint64(uint64* value); 454 bool PopVariantOfDouble(double* value); 455 bool PopVariantOfString(std::string* value); 456 bool PopVariantOfObjectPath(ObjectPath* value); 457 458 // Get the data type of the value at the current iterator 459 // position. INVALID_DATA will be returned if the iterator points to the 460 // end of the message. 461 Message::DataType GetDataType(); 462 463 private: 464 // Returns true if the data type at the current iterator position 465 // matches the given D-Bus type, such as DBUS_TYPE_BYTE. 466 bool CheckDataType(int dbus_type); 467 468 // Helper function used to implement PopByte() etc. 469 bool PopBasic(int dbus_type, void *value); 470 471 // Helper function used to implement PopArray() etc. 472 bool PopContainer(int dbus_type, MessageReader* sub_reader); 473 474 // Helper function used to implement PopVariantOfByte() etc. 475 bool PopVariantOfBasic(int dbus_type, void* value); 476 477 Message* message_; 478 DBusMessageIter raw_message_iter_; 479 480 DISALLOW_COPY_AND_ASSIGN(MessageReader); 481}; 482 483} // namespace dbus 484 485#endif // DBUS_MESSAGE_H_ 486