dbus/message.h

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