dbus/message.h

// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef DBUS_MESSAGE_H_
#define DBUS_MESSAGE_H_

#include <dbus/dbus.h>
#include <stddef.h>
#include <stdint.h>

#include <memory>
#include <string>
#include <vector>

#include "base/macros.h"
#include "dbus/dbus_export.h"
#include "dbus/file_descriptor.h"
#include "dbus/object_path.h"

namespace google {
namespace protobuf {

class MessageLite;

}  // namespace protobuf
}  // namespace google


namespace dbus {

class MessageWriter;
class MessageReader;

// DBUS_TYPE_UNIX_FD was added in D-Bus version 1.4
#if !defined(DBUS_TYPE_UNIX_FD)
#define DBUS_TYPE_UNIX_FD      ((int) 'h')
#endif

// Returns true if Unix FD passing is supported in libdbus.
// The check is done runtime rather than compile time as the libdbus
// version used at runtime may be different from the one used at compile time.
CHROME_DBUS_EXPORT bool IsDBusTypeUnixFdSupported();

// Message is the base class of D-Bus message types. Client code must use
// sub classes such as MethodCall and Response instead.
//
// The class name Message is very generic, but there should be no problem
// as the class is inside 'dbus' namespace. We chose to name this way, as
// libdbus defines lots of types starting with DBus, such as
// DBusMessage. We should avoid confusion and conflict with these types.
class CHROME_DBUS_EXPORT Message {
 public:
  // The message type used in D-Bus.  Redefined here so client code
  // doesn't need to use raw D-Bus macros. DBUS_MESSAGE_TYPE_INVALID
  // etc. are #define macros. Having an enum type here makes code a bit
  // more type-safe.
  enum MessageType {
    MESSAGE_INVALID = DBUS_MESSAGE_TYPE_INVALID,
    MESSAGE_METHOD_CALL = DBUS_MESSAGE_TYPE_METHOD_CALL,
    MESSAGE_METHOD_RETURN = DBUS_MESSAGE_TYPE_METHOD_RETURN,
    MESSAGE_SIGNAL = DBUS_MESSAGE_TYPE_SIGNAL,
    MESSAGE_ERROR = DBUS_MESSAGE_TYPE_ERROR,
 };

  // The data type used in the D-Bus type system.  See the comment at
  // MessageType for why we are redefining data types here.
  enum DataType {
    INVALID_DATA = DBUS_TYPE_INVALID,
    BYTE = DBUS_TYPE_BYTE,
    BOOL = DBUS_TYPE_BOOLEAN,
    INT16 = DBUS_TYPE_INT16,
    UINT16 = DBUS_TYPE_UINT16,
    INT32 = DBUS_TYPE_INT32,
    UINT32 = DBUS_TYPE_UINT32,
    INT64 = DBUS_TYPE_INT64,
    UINT64 = DBUS_TYPE_UINT64,
    DOUBLE = DBUS_TYPE_DOUBLE,
    STRING = DBUS_TYPE_STRING,
    OBJECT_PATH = DBUS_TYPE_OBJECT_PATH,
    ARRAY = DBUS_TYPE_ARRAY,
    STRUCT = DBUS_TYPE_STRUCT,
    DICT_ENTRY = DBUS_TYPE_DICT_ENTRY,
    VARIANT = DBUS_TYPE_VARIANT,
    UNIX_FD = DBUS_TYPE_UNIX_FD,
  };

  // Returns the type of the message. Returns MESSAGE_INVALID if
  // raw_message_ is NULL.
  MessageType GetMessageType();

  // Returns the type of the message as string like "MESSAGE_METHOD_CALL"
  // for instance.
  std::string GetMessageTypeAsString();

  DBusMessage* raw_message() { return raw_message_; }

  // Sets the destination, the path, the interface, the member, etc.
  bool SetDestination(const std::string& destination);
  bool SetPath(const ObjectPath& path);
  bool SetInterface(const std::string& interface);
  bool SetMember(const std::string& member);
  bool SetErrorName(const std::string& error_name);
  bool SetSender(const std::string& sender);
  void SetSerial(uint32_t serial);
  void SetReplySerial(uint32_t reply_serial);
  // SetSignature() does not exist as we cannot do it.

  // Gets the destination, the path, the interface, the member, etc.
  // If not set, an empty string is returned.
  std::string GetDestination();
  ObjectPath GetPath();
  std::string GetInterface();
  std::string GetMember();
  std::string GetErrorName();
  std::string GetSender();
  std::string GetSignature();
  // Gets the serial and reply serial numbers. Returns 0 if not set.
  uint32_t GetSerial();
  uint32_t GetReplySerial();

  // Returns the string representation of this message. Useful for
  // debugging. The output is truncated as needed (ex. strings are truncated
  // if longer than a certain limit defined in the .cc file).
  std::string ToString();

 protected:
  // This class cannot be instantiated. Use sub classes instead.
  Message();
  virtual ~Message();

  // Initializes the message with the given raw message.
  void Init(DBusMessage* raw_message);

 private:
  // Helper function used in ToString().
  std::string ToStringInternal(const std::string& indent,
                               MessageReader* reader);

  DBusMessage* raw_message_;
  DISALLOW_COPY_AND_ASSIGN(Message);
};

// MessageCall is a type of message used for calling a method via D-Bus.
class CHROME_DBUS_EXPORT MethodCall : public Message {
 public:
  // Creates a method call message for the specified interface name and
  // the method name.
  //
  // For instance, to call "Get" method of DBUS_INTERFACE_INTROSPECTABLE
  // interface ("org.freedesktop.DBus.Introspectable"), create a method
  // call like this:
  //
  //   MethodCall method_call(DBUS_INTERFACE_INTROSPECTABLE, "Get");
  //
  // The constructor creates the internal raw message.
  MethodCall(const std::string& interface_name,
             const std::string& method_name);

  // Returns a newly created MethodCall from the given raw message of the
  // type DBUS_MESSAGE_TYPE_METHOD_CALL. The caller must delete the
  // returned object. Takes the ownership of |raw_message|.
  static MethodCall* FromRawMessage(DBusMessage* raw_message);

 private:
  // Creates a method call message. The internal raw message is NULL.
  // Only used internally.
  MethodCall();

  DISALLOW_COPY_AND_ASSIGN(MethodCall);
};

// Signal is a type of message used to send a signal.
class CHROME_DBUS_EXPORT Signal : public Message {
 public:
  // Creates a signal message for the specified interface name and the
  // method name.
  //
  // For instance, to send "PropertiesChanged" signal of
  // DBUS_INTERFACE_INTROSPECTABLE interface
  // ("org.freedesktop.DBus.Introspectable"), create a signal like this:
  //
  //   Signal signal(DBUS_INTERFACE_INTROSPECTABLE, "PropertiesChanged");
  //
  // The constructor creates the internal raw_message_.
  Signal(const std::string& interface_name,
         const std::string& method_name);

  // Returns a newly created SIGNAL from the given raw message of the type
  // DBUS_MESSAGE_TYPE_SIGNAL. The caller must delete the returned
  // object. Takes the ownership of |raw_message|.
  static Signal* FromRawMessage(DBusMessage* raw_message);

 private:
  // Creates a signal message. The internal raw message is NULL.
  // Only used internally.
  Signal();

  DISALLOW_COPY_AND_ASSIGN(Signal);
};

// Response is a type of message used for receiving a response from a
// method via D-Bus.
class CHROME_DBUS_EXPORT Response : public Message {
 public:
  // Returns a newly created Response from the given raw message of the
  // type DBUS_MESSAGE_TYPE_METHOD_RETURN. Takes the ownership of |raw_message|.
  static std::unique_ptr<Response> FromRawMessage(DBusMessage* raw_message);

  // Returns a newly created Response from the given method call.
  // Used for implementing exported methods. Does NOT take the ownership of
  // |method_call|.
  static std::unique_ptr<Response> FromMethodCall(MethodCall* method_call);

  // Returns a newly created Response with an empty payload.
  // Useful for testing.
  static std::unique_ptr<Response> CreateEmpty();

 protected:
  // Creates a Response message. The internal raw message is NULL.
  Response();

 private:
  DISALLOW_COPY_AND_ASSIGN(Response);
};

// ErrorResponse is a type of message used to return an error to the
// caller of a method.
class CHROME_DBUS_EXPORT ErrorResponse: public Response {
 public:
  // Returns a newly created Response from the given raw message of the
  // type DBUS_MESSAGE_TYPE_METHOD_RETURN. Takes the ownership of |raw_message|.
  static std::unique_ptr<ErrorResponse> FromRawMessage(
      DBusMessage* raw_message);

  // Returns a newly created ErrorResponse from the given method call, the
  // error name, and the error message.  The error name looks like
  // "org.freedesktop.DBus.Error.Failed". Used for returning an error to a
  // failed method call. Does NOT take the ownership of |method_call|.
  static std::unique_ptr<ErrorResponse> FromMethodCall(
      MethodCall* method_call,
      const std::string& error_name,
      const std::string& error_message);

 private:
  // Creates an ErrorResponse message. The internal raw message is NULL.
  ErrorResponse();

  DISALLOW_COPY_AND_ASSIGN(ErrorResponse);
};

// MessageWriter is used to write outgoing messages for calling methods
// and sending signals.
//
// The main design goal of MessageReader and MessageWriter classes is to
// provide a type safe API. In the past, there was a Chrome OS blocker
// bug, that took days to fix, that would have been prevented if the API
// was type-safe.
//
// For instance, instead of doing something like:
//
//   // We shouldn't add '&' to str here, but it compiles with '&' added.
//   dbus_g_proxy_call(..., G_TYPE_STRING, str, G_TYPE_INVALID, ...)
//
// We want to do something like:
//
//   writer.AppendString(str);
//
class CHROME_DBUS_EXPORT MessageWriter {
 public:
  // Data added with Append* will be written to |message|, which may be NULL
  // to create a sub-writer for passing to OpenArray, etc.
  explicit MessageWriter(Message* message);
  ~MessageWriter();

  // Appends a byte to the message.
  void AppendByte(uint8_t value);
  void AppendBool(bool value);
  void AppendInt16(int16_t value);
  void AppendUint16(uint16_t value);
  void AppendInt32(int32_t value);
  void AppendUint32(uint32_t value);
  void AppendInt64(int64_t value);
  void AppendUint64(uint64_t value);
  void AppendDouble(double value);
  void AppendString(const std::string& value);
  void AppendObjectPath(const ObjectPath& value);
  void AppendFileDescriptor(const FileDescriptor& value);

  // Opens an array. The array contents can be added to the array with
  // |sub_writer|. The client code must close the array with
  // CloseContainer(), once all contents are added.
  //
  // |signature| parameter is used to supply the D-Bus type signature of
  // the array contents. For instance, if you want an array of strings,
  // then you pass "s" as the signature.
  //
  // See the spec for details about the type signatures.
  // http://dbus.freedesktop.org/doc/dbus-specification.html
  // #message-protocol-signatures
  //
  void OpenArray(const std::string& signature, MessageWriter* sub_writer);
  // Do the same for a variant.
  void OpenVariant(const std::string& signature, MessageWriter* sub_writer);
  // Do the same for Struct and dict entry. They don't need the signature.
  void OpenStruct(MessageWriter* sub_writer);
  void OpenDictEntry(MessageWriter* sub_writer);

  // Close the container for a array/variant/struct/dict entry.
  void CloseContainer(MessageWriter* sub_writer);

  // Appends the array of bytes. Arrays of bytes are often used for
  // exchanging binary blobs hence it's worth having a specialized
  // function.
  void AppendArrayOfBytes(const uint8_t* values, size_t length);

  // Appends the array of doubles. Used for audio mixer matrix doubles.
  void AppendArrayOfDoubles(const double* values, size_t length);

  // Appends the array of strings. Arrays of strings are often used for
  // exchanging lists of names hence it's worth having a specialized
  // function.
  void AppendArrayOfStrings(const std::vector<std::string>& strings);

  // Appends the array of object paths. Arrays of object paths are often
  // used when exchanging object paths, hence it's worth having a
  // specialized function.
  void AppendArrayOfObjectPaths(const std::vector<ObjectPath>& object_paths);

  // Appends the protocol buffer as an array of bytes. The buffer is serialized
  // into an array of bytes before communication, since protocol buffers are not
  // a native dbus type. On the receiving size the array of bytes needs to be
  // read and deserialized into a protocol buffer of the correct type. There are
  // methods in MessageReader to assist in this.  Return true on succes and fail
  // when serialization is not successful.
  bool AppendProtoAsArrayOfBytes(const google::protobuf::MessageLite& protobuf);

  // Appends the byte wrapped in a variant data container. Variants are
  // widely used in D-Bus services so it's worth having a specialized
  // function. For instance, The third parameter of
  // "org.freedesktop.DBus.Properties.Set" is a variant.
  void AppendVariantOfByte(uint8_t value);
  void AppendVariantOfBool(bool value);
  void AppendVariantOfInt16(int16_t value);
  void AppendVariantOfUint16(uint16_t value);
  void AppendVariantOfInt32(int32_t value);
  void AppendVariantOfUint32(uint32_t value);
  void AppendVariantOfInt64(int64_t value);
  void AppendVariantOfUint64(uint64_t value);
  void AppendVariantOfDouble(double value);
  void AppendVariantOfString(const std::string& value);
  void AppendVariantOfObjectPath(const ObjectPath& value);

 private:
  // Helper function used to implement AppendByte etc.
  void AppendBasic(int dbus_type, const void* value);

  // Helper function used to implement AppendVariantOfByte() etc.
  void AppendVariantOfBasic(int dbus_type, const void* value);

  Message* message_;
  DBusMessageIter raw_message_iter_;
  bool container_is_open_;

  DISALLOW_COPY_AND_ASSIGN(MessageWriter);
};

// MessageReader is used to read incoming messages such as responses for
// method calls.
//
// MessageReader manages an internal iterator to read data. All functions
// starting with Pop advance the iterator on success.
class CHROME_DBUS_EXPORT MessageReader {
 public:
  // The data will be read from the given |message|, which may be NULL to
  // create a sub-reader for passing to PopArray, etc.
  explicit MessageReader(Message* message);
  ~MessageReader();

  // Returns true if the reader has more data to read. The function is
  // used to iterate contents in a container like:
  //
  //   while (reader.HasMoreData())
  //     reader.PopString(&value);
  bool HasMoreData();

  // Gets the byte at the current iterator position.
  // Returns true and advances the iterator on success.
  // Returns false if the data type is not a byte.
  bool PopByte(uint8_t* value);
  bool PopBool(bool* value);
  bool PopInt16(int16_t* value);
  bool PopUint16(uint16_t* value);
  bool PopInt32(int32_t* value);
  bool PopUint32(uint32_t* value);
  bool PopInt64(int64_t* value);
  bool PopUint64(uint64_t* value);
  bool PopDouble(double* value);
  bool PopString(std::string* value);
  bool PopObjectPath(ObjectPath* value);
  bool PopFileDescriptor(FileDescriptor* value);

  // Sets up the given message reader to read an array at the current
  // iterator position.
  // Returns true and advances the iterator on success.
  // Returns false if the data type is not an array
  bool PopArray(MessageReader* sub_reader);
  bool PopStruct(MessageReader* sub_reader);
  bool PopDictEntry(MessageReader* sub_reader);
  bool PopVariant(MessageReader* sub_reader);

  // Gets the array of bytes at the current iterator position.
  // Returns true and advances the iterator on success.
  //
  // Arrays of bytes are often used for exchanging binary blobs hence it's
  // worth having a specialized function.
  //
  // Ownership of the memory pointed to by |bytes| remains with the
  // MessageReader; |bytes| must be copied if the contents will be referenced
  // after the MessageReader is destroyed.
  bool PopArrayOfBytes(const uint8_t** bytes, size_t* length);

  // Gets the array of doubles at the current iterator position.
  bool PopArrayOfDoubles(const double** doubles, size_t* length);

  // Gets the array of strings at the current iterator position. |strings| is
  // cleared before being modified. Returns true and advances the iterator on
  // success.
  //
  // Arrays of strings are often used to communicate with D-Bus
  // services like KWallet, hence it's worth having a specialized
  // function.
  bool PopArrayOfStrings(std::vector<std::string>* strings);

  // Gets the array of object paths at the current iterator position.
  // |object_paths| is cleared before being modified. Returns true and advances
  // the iterator on success.
  //
  // Arrays of object paths are often used to communicate with D-Bus
  // services like NetworkManager, hence it's worth having a specialized
  // function.
  bool PopArrayOfObjectPaths(std::vector<ObjectPath>* object_paths);

  // Gets the array of bytes at the current iterator position. It then parses
  // this binary blob into the protocol buffer supplied.
  // Returns true and advances the iterator on success. On failure returns false
  // and emits an error message on the source of the failure. The two most
  // common errors come from the iterator not currently being at a byte array or
  // the wrong type of protocol buffer is passed in and the parse fails.
  bool PopArrayOfBytesAsProto(google::protobuf::MessageLite* protobuf);

  // Gets the byte from the variant data container at the current iterator
  // position.
  // Returns true and advances the iterator on success.
  //
  // Variants are widely used in D-Bus services so it's worth having a
  // specialized function. For instance, The return value type of
  // "org.freedesktop.DBus.Properties.Get" is a variant.
  bool PopVariantOfByte(uint8_t* value);
  bool PopVariantOfBool(bool* value);
  bool PopVariantOfInt16(int16_t* value);
  bool PopVariantOfUint16(uint16_t* value);
  bool PopVariantOfInt32(int32_t* value);
  bool PopVariantOfUint32(uint32_t* value);
  bool PopVariantOfInt64(int64_t* value);
  bool PopVariantOfUint64(uint64_t* value);
  bool PopVariantOfDouble(double* value);
  bool PopVariantOfString(std::string* value);
  bool PopVariantOfObjectPath(ObjectPath* value);

  // Get the data type of the value at the current iterator
  // position. INVALID_DATA will be returned if the iterator points to the
  // end of the message.
  Message::DataType GetDataType();

  // Get the DBus signature of the value at the current iterator position.
  // An empty string will be returned if the iterator points to the end of
  // the message.
  std::string GetDataSignature();

 private:
  // Returns true if the data type at the current iterator position
  // matches the given D-Bus type, such as DBUS_TYPE_BYTE.
  bool CheckDataType(int dbus_type);

  // Helper function used to implement PopByte() etc.
  bool PopBasic(int dbus_type, void *value);

  // Helper function used to implement PopArray() etc.
  bool PopContainer(int dbus_type, MessageReader* sub_reader);

  // Helper function used to implement PopVariantOfByte() etc.
  bool PopVariantOfBasic(int dbus_type, void* value);

  Message* message_;
  DBusMessageIter raw_message_iter_;

  DISALLOW_COPY_AND_ASSIGN(MessageReader);
};

}  // namespace dbus

#endif  // DBUS_MESSAGE_H_