chromium/dbus/message.h

// Copyright 2012 The Chromium Authors
// 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/containers/span.h"
#include "base/files/scoped_file.h"
#include "base/memory/raw_ptr.h"
#include "dbus/dbus_export.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 …
#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 { … };

// MessageCall is a type of message used for calling a method via D-Bus.
class CHROME_DBUS_EXPORT MethodCall : public Message { … };

// Signal is a type of message used to send a signal.
class CHROME_DBUS_EXPORT Signal : public Message { … };

// Response is a type of message used for receiving a response from a
// method via D-Bus.
class CHROME_DBUS_EXPORT Response : public Message { … };

// ErrorResponse is a type of message used to return an error to the
// caller of a method.
class CHROME_DBUS_EXPORT ErrorResponse : public Response { … };

// 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 { … };

// 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 { … };

}  // namespace dbus

#endif  // DBUS_MESSAGE_H_