Home | History | Annotate | Download | only in dbus
      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 "base/memory/scoped_ptr.h"
     14 #include "dbus/dbus_export.h"
     15 #include "dbus/file_descriptor.h"
     16 #include "dbus/object_path.h"
     17 
     18 namespace google {
     19 namespace protobuf {
     20 
     21 class MessageLite;
     22 
     23 }  // namespace protobuf
     24 }  // namespace google
     25 
     26 
     27 namespace dbus {
     28 
     29 class MessageWriter;
     30 class MessageReader;
     31 
     32 // DBUS_TYPE_UNIX_FD was added in D-Bus version 1.4
     33 #if !defined(DBUS_TYPE_UNIX_FD)
     34 #define DBUS_TYPE_UNIX_FD      ((int) 'h')
     35 #endif
     36 
     37 // Returns true if Unix FD passing is supported in libdbus.
     38 // The check is done runtime rather than compile time as the libdbus
     39 // version used at runtime may be different from the one used at compile time.
     40 CHROME_DBUS_EXPORT bool IsDBusTypeUnixFdSupported();
     41 
     42 // Message is the base class of D-Bus message types. Client code must use
     43 // sub classes such as MethodCall and Response instead.
     44 //
     45 // The class name Message is very generic, but there should be no problem
     46 // as the class is inside 'dbus' namespace. We chose to name this way, as
     47 // libdbus defines lots of types starting with DBus, such as
     48 // DBusMessage. We should avoid confusion and conflict with these types.
     49 class CHROME_DBUS_EXPORT Message {
     50  public:
     51   // The message type used in D-Bus.  Redefined here so client code
     52   // doesn't need to use raw D-Bus macros. DBUS_MESSAGE_TYPE_INVALID
     53   // etc. are #define macros. Having an enum type here makes code a bit
     54   // more type-safe.
     55   enum MessageType {
     56     MESSAGE_INVALID = DBUS_MESSAGE_TYPE_INVALID,
     57     MESSAGE_METHOD_CALL = DBUS_MESSAGE_TYPE_METHOD_CALL,
     58     MESSAGE_METHOD_RETURN = DBUS_MESSAGE_TYPE_METHOD_RETURN,
     59     MESSAGE_SIGNAL = DBUS_MESSAGE_TYPE_SIGNAL,
     60     MESSAGE_ERROR = DBUS_MESSAGE_TYPE_ERROR,
     61  };
     62 
     63   // The data type used in the D-Bus type system.  See the comment at
     64   // MessageType for why we are redefining data types here.
     65   enum DataType {
     66     INVALID_DATA = DBUS_TYPE_INVALID,
     67     BYTE = DBUS_TYPE_BYTE,
     68     BOOL = DBUS_TYPE_BOOLEAN,
     69     INT16 = DBUS_TYPE_INT16,
     70     UINT16 = DBUS_TYPE_UINT16,
     71     INT32 = DBUS_TYPE_INT32,
     72     UINT32 = DBUS_TYPE_UINT32,
     73     INT64 = DBUS_TYPE_INT64,
     74     UINT64 = DBUS_TYPE_UINT64,
     75     DOUBLE = DBUS_TYPE_DOUBLE,
     76     STRING = DBUS_TYPE_STRING,
     77     OBJECT_PATH = DBUS_TYPE_OBJECT_PATH,
     78     ARRAY = DBUS_TYPE_ARRAY,
     79     STRUCT = DBUS_TYPE_STRUCT,
     80     DICT_ENTRY = DBUS_TYPE_DICT_ENTRY,
     81     VARIANT = DBUS_TYPE_VARIANT,
     82     UNIX_FD = DBUS_TYPE_UNIX_FD,
     83   };
     84 
     85   // Returns the type of the message. Returns MESSAGE_INVALID if
     86   // raw_message_ is NULL.
     87   MessageType GetMessageType();
     88 
     89   // Returns the type of the message as string like "MESSAGE_METHOD_CALL"
     90   // for instance.
     91   std::string GetMessageTypeAsString();
     92 
     93   DBusMessage* raw_message() { return raw_message_; }
     94 
     95   // Sets the destination, the path, the interface, the member, etc.
     96   bool SetDestination(const std::string& destination);
     97   bool SetPath(const ObjectPath& path);
     98   bool SetInterface(const std::string& interface);
     99   bool SetMember(const std::string& member);
    100   bool SetErrorName(const std::string& error_name);
    101   bool SetSender(const std::string& sender);
    102   void SetSerial(uint32 serial);
    103   void SetReplySerial(uint32 reply_serial);
    104   // SetSignature() does not exist as we cannot do it.
    105 
    106   // Gets the destination, the path, the interface, the member, etc.
    107   // If not set, an empty string is returned.
    108   std::string GetDestination();
    109   ObjectPath GetPath();
    110   std::string GetInterface();
    111   std::string GetMember();
    112   std::string GetErrorName();
    113   std::string GetSender();
    114   std::string GetSignature();
    115   // Gets the serial and reply serial numbers. Returns 0 if not set.
    116   uint32 GetSerial();
    117   uint32 GetReplySerial();
    118 
    119   // Returns the string representation of this message. Useful for
    120   // debugging. The output is truncated as needed (ex. strings are truncated
    121   // if longer than a certain limit defined in the .cc file).
    122   std::string ToString();
    123 
    124  protected:
    125   // This class cannot be instantiated. Use sub classes instead.
    126   Message();
    127   virtual ~Message();
    128 
    129   // Initializes the message with the given raw message.
    130   void Init(DBusMessage* raw_message);
    131 
    132  private:
    133   // Helper function used in ToString().
    134   std::string ToStringInternal(const std::string& indent,
    135                                MessageReader* reader);
    136 
    137   DBusMessage* raw_message_;
    138   DISALLOW_COPY_AND_ASSIGN(Message);
    139 };
    140 
    141 // MessageCall is a type of message used for calling a method via D-Bus.
    142 class CHROME_DBUS_EXPORT MethodCall : public Message {
    143  public:
    144   // Creates a method call message for the specified interface name and
    145   // the method name.
    146   //
    147   // For instance, to call "Get" method of DBUS_INTERFACE_INTROSPECTABLE
    148   // interface ("org.freedesktop.DBus.Introspectable"), create a method
    149   // call like this:
    150   //
    151   //   MethodCall method_call(DBUS_INTERFACE_INTROSPECTABLE, "Get");
    152   //
    153   // The constructor creates the internal raw message.
    154   MethodCall(const std::string& interface_name,
    155              const std::string& method_name);
    156 
    157   // Returns a newly created MethodCall from the given raw message of the
    158   // type DBUS_MESSAGE_TYPE_METHOD_CALL. The caller must delete the
    159   // returned object. Takes the ownership of |raw_message|.
    160   static MethodCall* FromRawMessage(DBusMessage* raw_message);
    161 
    162  private:
    163   // Creates a method call message. The internal raw message is NULL.
    164   // Only used internally.
    165   MethodCall();
    166 
    167   DISALLOW_COPY_AND_ASSIGN(MethodCall);
    168 };
    169 
    170 // Signal is a type of message used to send a signal.
    171 class CHROME_DBUS_EXPORT Signal : public Message {
    172  public:
    173   // Creates a signal message for the specified interface name and the
    174   // method name.
    175   //
    176   // For instance, to send "PropertiesChanged" signal of
    177   // DBUS_INTERFACE_INTROSPECTABLE interface
    178   // ("org.freedesktop.DBus.Introspectable"), create a signal like this:
    179   //
    180   //   Signal signal(DBUS_INTERFACE_INTROSPECTABLE, "PropertiesChanged");
    181   //
    182   // The constructor creates the internal raw_message_.
    183   Signal(const std::string& interface_name,
    184          const std::string& method_name);
    185 
    186   // Returns a newly created SIGNAL from the given raw message of the type
    187   // DBUS_MESSAGE_TYPE_SIGNAL. The caller must delete the returned
    188   // object. Takes the ownership of |raw_message|.
    189   static Signal* FromRawMessage(DBusMessage* raw_message);
    190 
    191  private:
    192   // Creates a signal message. The internal raw message is NULL.
    193   // Only used internally.
    194   Signal();
    195 
    196   DISALLOW_COPY_AND_ASSIGN(Signal);
    197 };
    198 
    199 // Response is a type of message used for receiving a response from a
    200 // method via D-Bus.
    201 class CHROME_DBUS_EXPORT Response : public Message {
    202  public:
    203   // Returns a newly created Response from the given raw message of the
    204   // type DBUS_MESSAGE_TYPE_METHOD_RETURN. Takes the ownership of |raw_message|.
    205   static scoped_ptr<Response> FromRawMessage(DBusMessage* raw_message);
    206 
    207   // Returns a newly created Response from the given method call.
    208   // Used for implementing exported methods. Does NOT take the ownership of
    209   // |method_call|.
    210   static scoped_ptr<Response> FromMethodCall(MethodCall* method_call);
    211 
    212   // Returns a newly created Response with an empty payload.
    213   // Useful for testing.
    214   static scoped_ptr<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.
    226 class 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. Takes the ownership of |raw_message|.
    230   static scoped_ptr<ErrorResponse> FromRawMessage(DBusMessage* raw_message);
    231 
    232   // Returns a newly created ErrorResponse from the given method call, the
    233   // error name, and the error message.  The error name looks like
    234   // "org.freedesktop.DBus.Error.Failed". Used for returning an error to a
    235   // failed method call. Does NOT take the ownership of |method_call|.
    236   static scoped_ptr<ErrorResponse> FromMethodCall(
    237       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 //
    265 class 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.
    366 class 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