In order to properly utilize the dbus-cxx library, we need to talk about two concepts: local and remote objects.
Before we can talk about local and remote objects, we first need to talk about how bus names, paths, and interfaces are related.
When an application connects to the DBus, it is always assigned a unique name. This unique name will look like :1.20. This unique name can be used to send messages to a particular application, but since this may change between startups it is not useful for most purposes. In general, we want to request a well-known bus name in the form of com.example.MyProgram. Some well-known bus names include org.freedesktop.Notifications (which displays notifications to the user), and org.freedesktop.DBus, which is the actual DBus Daemon control interface.
Bus names must consist of at least two dotted sections with at least one character each in them.
With dbus-cxx, you request a bus name using DBus::Connection.request_name().
Bus names are analagous to top-level domain names(e.g. example.com), or TLDs.
A Path, represented in dbus-cxx by the DBus::Path class, can be thought of as a subdirectory of our domain name.
Paths are always separated by slashes, e.g. /org/freedesktop/DBus. An application may export multiple paths on the same bus name. For example, GNOME 3.30.2 exports at least the following paths on the well-known bus name org.gnome.Panel:
Interfaces are represented by the DBus::Interface class or the DBus::InterfaceProxy class depending on if it is an interface on a local object that we are exporting, or an interface on a remote object that we are calling.
Interfaces are similar to Java interfaces, in that they define a well-known set of functions that can be performed on an object at the given path.
By default, each path must contain an interface for org.freedesktop.DBus.Instrospectable, and may contain any number of other interfaces. This interface defines only one method, Introspect, which returns an XML document that defines the interfaces, methods, and signals on this object on this path.
Pulling all of this together into a tree-like structure, we come up with something that looks like the following(albeit very simplified):
Local objects, sometimes called adaptee classes, are objects that contain methods that may be called from other applications. When the interfaces for these objects are generated automatically by dbus-cxx-xml2cpp, they will be called 'adaptee' classes.
These adaptee classes can then be exported onto the DBus at a specific path.
Mapping this to classes in dbus-cxx, the following diagram shows how this looks:
Remote objects are objects that represent methods and signals that a remote application exports. These classes are called 'proxy' classes, as they forward the request to the remote application and return the result from the remote application, as if the methods that were called are in our application.
These classes can also be generated by dbus-cxx-xml2cpp.
Mapping this to classes in dbus-cxx, the following diagram shows how this looks:
1.9.1