sdbus-c++ 1.5.0
High-level C++ D-Bus library based on systemd D-Bus implementation
|
Table of contents
sdbus-c++ is a C++ D-Bus library built on top of sd-bus, a lightweight D-Bus client library implemented within systemd project. It provides D-Bus functionality on a higher level of abstraction, trying to employ C++ type system to shift as much work as possible from the developer to the compiler.
Although sdbus-c++ covers most of sd-bus API, it does not (yet) fully cover every sd-bus API detail. The focus is put on the most widely used functionality: D-Bus connections, object, proxies, synchronous and asynchronous method calls, signals, and properties. If you are missing a desired functionality, you are welcome to submit an issue, or, best, to contribute to sdbus-c++ by submitting a pull request.
The library build system is based on CMake. The library provides a config and an export file, so integrating it into your CMake project is sooo simple:
The library also supports pkg-config
, so it easily be integrated into e.g. an Autotools project:
**_Note_:** sdbus-c++ library uses a number of modern C++17 features. Please make certain you have a recent compiler (gcc >= 7, clang >= 6).
If you intend to use xml-to-c++ generator tool (explained later) in your project to generate interface headers from XML, you can integrate that too with CMake or pkg-config
:
sdbus-c++ depends on sd-bus API, which is implemented in libsystemd, a C library that is part of systemd.
Minimum required libsystemd shared library version is 0.20.0 (which corresponds to minimum systemd version 236).
If your target Linux distribution is already based on systemd ecosystem of version 236 and higher, then there is no additional effort, just make sure you have corresponding systemd header files available (provided by libsystemd-dev
package on Debian/Ubuntu, for example), and you may go on building sdbus-c++ seamlessly.
However, sdbus-c++ can perfectly be used in non-systemd environments as well. If libsystemd
is not found in the system when configuring sdbus-c++, then
libelogind
, which is an extracted logind from original systemd containing sd-bus implementation. If not found, thenbasu
, which is just sd-bus implementation extracted from systemd.On systems where neither of these is available, we can build sd-bus as a shared lib manually or we can (conveniently) instruct sdbus-c++ to build and integrate sd-bus into itself for us.
Fortunately, libsystemd is rather self-contained and can be built and used independently of the rest of systemd ecosystem. To build libsystemd shared library for sdbus-c++:
sdbus-c++ provides BUILD_LIBSYSTEMD
configuration option. When turned on, sdbus-c++ will automatically download and build libsystemd as a static library and make it an opaque part of sdbus-c++ shared library for you. This is the most convenient and effective approach to build, distribute and use sdbus-c++ as a self-contained, systemd-independent library in non-systemd environments. Just make sure your build machine has all dependencies needed by libsystemd build process. That includes, among others, meson
, ninja
, git
, gperf
, and – primarily – libraries and library headers for libmount
, libcap
and librt
(part of glibc). Also, when distributing, make sure these dependency libraries are installed on the production machine.
You may additionally set the LIBSYSTEMD_VERSION
configuration flag to fine-tune the version of systemd to be taken in. (The default value is 242).
There are Yocto recipes for sdbus-c++ available in the meta-oe
layer of the meta-openembedded
project. There are two recipes:
**_Tip_:** If you get ‘ERROR: Program or command 'getent’ not found or not executable
when building sdbus-c++ in Yocto, please make sure you've added
getentto
HOSTTOOLS. For example, you can add
HOSTTOOLS_NONFATAL += "getent"` into your local.conf file.
sdbus-c++ recipe is available in ConanCenter repository as sdbus-cpp
.
There is the Buildroot package sdbus-cpp
to build sdbus-c++ library itself without a code generation tool.
Contributors willing to help with bringing sdbus-c++ to other popular package systems are welcome.
You can build and run sdbus-c++ unit and integration tests to verify sdbus-c++ build:
All sdbus-c++ header files reside in the sdbus-c++
subdirectory within the standard include directory. Users can either include individual header files, like so:
or just include the global header file that pulls in everything:
All public types and functions of sdbus-c++ reside in the sdbus
namespace.
sdbus::Error
exception is used to signal errors in sdbus-c++. There are two types of errors:
sdbus::Error
is a carrier for both types of errors, carrying the error name and error message with it.
The following diagram illustrates the major entities in sdbus-c++.
IConnection
represents the concept of a D-Bus connection. You can connect to either the system bus or a session bus. Services can assign unique service names to those connections. An I/O event loop should be run on the bus connection.
IObject
represents the concept of an object that exposes its methods, signals and properties. Its responsibilities are:
IProxy
represents the concept of the proxy, which is a view of the Object
from the client side. Its responsibilities are:
Message
class represents a message, which is the fundamental DBus concept. There are three distinctive types of message that are derived from the Message
class:
MethodCall
(be it synchronous or asynchronous method call, with serialized parameters),MethodReply
(with serialized return values),Signal
(with serialized parameters),PropertySetCall
(with serialized parameter value to be set)PropertyGetReply
(where property value shall be stored)PlainMessage
(for internal purposes).sdbus-c++ is completely thread-aware by design. Though sdbus-c++ is not thread-safe in general, there are situations where sdbus-c++ provides and guarantees API-level thread safety by design. It is safe to do these operations (operations within the bullet points, not across them) from multiple threads at the same time:
Object
/Proxy
instances simultaneously (even on a shared connection that is running an event loop already, see below). Under making here is meant a complete sequence of construction, registration of method/signal/property callbacks and export of the Object
/Proxy
so it is ready to issue/receive messages. This sequence must be completely done within the context of one thread.Object
instance.Object
instance.Proxy
instance. (But it's generally better that our threads use their own exclusive instances of proxy, to minimize shared state and contention.)sdbus-c++ is designed such that all the above operations are thread-safe also on a connection that is running an event loop (usually in a separate thread) at that time. It's an internal thread safety. For example, a signal arrives and is processed by sdbus-c++ even loop at an appropriate Proxy
instance, while the user is going to destroy that instance in their application thread. The user cannot explicitly control these situations (or they could, but that would be very limiting and cumbersome on the API level).
However, other combinations, that the user invokes explicitly from within more threads are NOT thread-safe in sdbus-c++ by design, and the user should make sure by their design that these cases never occur. For example, destroying an Object
instance in one thread while emitting a signal on it in another thread is not thread-safe. In this specific case, the user should make sure in their application that all threads stop working with a specific instance before a thread proceeds with deleting that instance.
sdbus-c++ API comes in two layers:
sdbus-c++ also ships with sdbus-c++-xml2cpp tool that converts D-Bus IDL in XML format into C++ bindings for the adaptor as well as the proxy part. This is the highest level of API provided by sdbus-c++ (the "C++ bindings layer"), which makes it possible for D-Bus RPC calls to completely look like native C++ calls on a local object.
Let's have an object /org/sdbuscpp/concatenator
that implements the org.sdbuscpp.concatenator
interface. The interface exposes the following:
concatenate
method that takes a collection of integers and a separator string and returns a string that is the concatenation of all integers from the collection using given separator,concatenated
signal that is emitted at the end of each successful concatenation.In the following sections, we will elaborate on the ways of implementing such an object on both the server and the client side.
Before running Concatenator example in your system: In order for your service to be allowed to provide a D-Bus API on system bus, a D-Bus security policy file has to be put in place for that service. Otherwise the service will fail to start (you'll get
[org.freedesktop.DBus.Error.AccessDenied] Failed to request bus name (Permission denied)
, for example). To make the Concatenator example work in your system, look in this section of systemd configuration for how to name the file, where to place it, how to populate it. For further information, consult dbus-daemon documentation, sections INTEGRATING SYSTEM SERVICES and CONFIGURATION FILE. As an example used for sdbus-c++ integration tests, you may look at the policy file for sdbus-c++ integration tests.
In the basic API layer, we already have abstractions for D-Bus connections, objects and object proxies, with which we can interact via their interface classes (IConnection
, IObject
, IProxy
), but, analogously to the underlying sd-bus C library, we still work on the level of D-Bus messages. We need to
This is how a simple Concatenator service implemented upon the basic sdbus-c++ API could look like:
We establish a D-Bus system connection and request org.sdbuscpp.concatenator
D-Bus name on it. This name will be used by D-Bus clients to find the service. We then create an object with path /org/sdbuscpp/concatenator
on this connection. We register interfaces, its methods, signals that the object provides, and, through finishRegistration()
, export the object (i.e., make it visible to clients) on the bus. Then we need to make sure to run the event loop upon the connection, which handles all incoming, outgoing and other requests.
The callback for any D-Bus object method on this level is any callable of signature void(sdbus::MethodCall call)
. The call
parameter is the incoming method call message. We need to deserialize our method input arguments from it. Then we can invoke the logic of the method and get the results. Then for the given call
, we create a reply
message, pack results into it and send it back to the caller through send()
. (If we had a void-returning method, we'd just send an empty reply
back.) We also fire a signal with the results. To do this, we need to create a signal message via object's createSignal()
, serialize the results into it, and then send it out to subscribers by invoking object's emitSignal()
.
Please note that we can create and destroy D-Bus objects on a connection dynamically, at any time during runtime, even while there is an active event loop upon the connection. So managing D-Bus objects' lifecycle (creating, exporting and destroying D-Bus objects) is completely thread-safe.
In simple cases, we don't need to create D-Bus connection explicitly for our proxies. Unless a connection is provided to a proxy object explicitly via factory parameter, the proxy will create a connection of his own, and it will be a system bus connection. This is the case in the example above. (This approach is not scalable and resource-saving if we have plenty of proxies; see section Working with D-Bus connections for elaboration.) So, in the example, we create a proxy for object /org/sdbuscpp/concatenator
publicly available at bus org.sdbuscpp.concatenator
. We register signal handlers, if any, and finish the registration, making the proxy ready for use.
The callback for a D-Bus signal handler on this level is any callable of signature void(sdbus::Signal& signal)
. The one and only parameter signal
is the incoming signal message. We need to deserialize arguments from it, and then we can do our business logic with it.
Subsequently, we invoke two RPC calls to object's concatenate()
method. We create a method call message by invoking proxy's createMethodCall()
. We serialize method input arguments into it, and make a synchronous call via proxy's callMethod()
. As a return value we get the reply message as soon as it arrives. We deserialize return values from that message, and further use it in our program. The second concatenate()
RPC call is done with invalid arguments, so we get a D-Bus error reply from the service, which as we can see is manifested via sdbus::Error
exception being thrown.
Please note that we can create and destroy D-Bus object proxies dynamically, at any time during runtime, even when they share a common D-Bus connection and there is an active event loop upon the connection. So managing D-Bus object proxies' lifecycle (creating and destroying D-Bus object proxies) is completely thread-safe.
There are several factory methods to create a bus connection object in sdbus-c++:
createConnection()
- opens a connection to the system buscreateConnection(const std::string& name)
- opens a connection with the given name to the system buscreateDefaultBusConnection()
- opens a connection to the session bus when in a user context, and a connection to the system bus, otherwisecreateDefaultBusConnection(const std::string& name)
- opens a connection with the given name to the session bus when in a user context, and a connection with the given name to the system bus, otherwisecreateSystemBusConnection()
- opens a connection to the system buscreateSystemBusConnection(const std::string& name)
- opens a connection with the given name to the system buscreateSessionBusConnection()
- opens a connection to the session buscreateSessionBusConnection(const std::string& name)
- opens a connection with the given name to the session buscreateSessionBusConnectionWithAddress(const std::string& address)
- opens a connection to the session bus at a custom addresscreateRemoteSystemBusConnection(const std::string& host)
- opens a connection to the system bus on a remote host using sshcreateDirectBusConnection(const std::string& address)
- opens direct D-Bus connection at a custom address (see Using direct (peer-to-peer) D-Bus connections)createDirectBusConnection(int fd)
- opens direct D-Bus connection at the given file descriptor (see Using direct (peer-to-peer) D-Bus connections)createServerBus(int fd)
- opens direct D-Bus connection at the given file descriptor as a server (see Using direct (peer-to-peer) D-Bus connections)createBusConnection(sd_bus *bus)
- creates a connection directly from the underlying sd_bus connection instance (which has been created and set up upfront directly through sd-bus API).For more information, peek into IConnection.h
where these functions are declared and documented.
The design of D-Bus connections in sdbus-c++ allows for certain flexibility and enables users to choose simplicity over scalability or scalability (at a finer granularity of user's choice) at the cost of slightly decreased simplicity.
How shall we use connections in relation to D-Bus objects and object proxies?
A D-Bus connection is represented by a IConnection
instance. Each connection needs an event loop being run upon it. So it needs a thread handling the event loop. This thread serves all incoming and outgoing messages and all communication towards D-Bus daemon. One process can have one but also multiple D-Bus connections (we just have to make certain that the connections with assigned bus names don't share a common name; the name must be unique).
A typical use case for most services is one D-Bus connection in the application. The application runs event loop on that connection. When creating objects or proxies, the application provides reference of that connection to those objects and proxies. This means all these objects and proxies share the same connection. This is nicely scalable, because with whatever number of objects or proxies, there is only one connection and one event loop thread. Yet, services that provide objects at various bus names have to create and maintain multiple D-Bus connections, each with the unique bus name.
The connection is thread-safe and objects and proxies can invoke operations on it from multiple threads simultaneously, but the operations are serialized. This means, for example, that if an object's callback for an incoming remote method call is going to be invoked in an event loop thread, and in another thread we use a proxy to call remote method in another process, the threads are contending and only one can go on while the other must wait and can only proceed after the first one has finished, because both are using a shared resource – the connection.
We should bear that in mind when designing more complex, multi-threaded services with high parallelism. If we have undesired contention on a connection, creating a specific, dedicated connection for a hot spot helps to increase concurrency. sdbus-c++ provides us freedom to create as many connections as we want and assign objects and proxies to those connections at our will. We, as application developers, choose whatever approach is more suitable to us at quite a fine granularity.
So, more technically, how can we use connections from the server and the client perspective?
On the server side, we generally need to create D-Bus objects and publish their APIs. For that we first need a connection with a unique bus name. We need to create the D-Bus connection manually ourselves, request bus name on it, and manually launch its event loop:
enterEventLoop()
,enterEventLoopAsync()
,getEventLoopPollData()
and use that data in our event loop mechanism.The object takes the D-Bus connection as a reference in its constructor. This is the only way to wire connection and object together. We must make sure the connection exists as long as objects using it exist.
Of course, at any time before or after running the event loop on the connection, we can create and "hook", as well as remove, objects and proxies upon that connection.
On the client side we likewise need a connection – just that unlike on the server side, we don't need to request a unique bus name on it. We have more options here when creating a proxy:
Or – and this is typical when we have a simple D-Bus client application – we have another option: we let the proxy maintain its own connection (and potentially an associated event loop thread, see below):
std::move
it to the proxy object factory. The proxy becomes an owner of this connection, and will run the event loop on that connection. This had the advantage that we may choose the type of connection (system, session, remote).It's also possible in this case to instruct the proxy to not spawn an event loop thread for its connection. There are many situations that we want to quickly create a proxy, carry out one or a few (synchronous) D-Bus calls, and let go of proxy. We call them light-weight proxies. For that purpose, spawning a new event loop thread comes with time and resource penalty, for nothing. To create such a light-weight proxy, use the factory/constructor overload with dont_run_event_loop_thread_t
. All in above two bullet sub-points holds; the proxy just won't spawn a thread with an event loop in it. Note that such a proxy can be used only for synchronous D-Bus calls; it may not receive signals or async call replies.
A connection with an asynchronous event loop (i.e. one initiated through enterEventLoopAsync()
) will stop and join its event loop thread automatically in its destructor. An event loop that blocks in the synchronous enterEventLoop()
call can be unblocked through leaveEventLoop()
call on the respective bus connection issued from a different thread or from an OS signal handler.
One of the major sdbus-c++ design goals is to make the sdbus-c++ API easy to use correctly, and hard to use incorrectly.
The convenience API layer abstracts the concept of underlying D-Bus messages away completely. It abstracts away D-Bus signatures. The interface uses small, focused functions, with a few parameters only, to form a chained function statement that reads like a human language sentence. To achieve that, sdbus-c++ utilizes the power of the C++ type system, which deduces and resolves a lot of things at compile time, and the run-time performance cost compared to the basic layer is close to zero.
Thus, in the end of the day, the code written using the convenience API is:
The code written using this layer expresses in a declarative way what it does, rather than how. Let's look at code samples.
When registering methods, calling methods or emitting signals, multiple lines of code have shrunk into simple one-liners. Signatures of provided callbacks are introspected and types of provided arguments are deduced at compile time, so the D-Bus signatures as well as serialization and deserialization of arguments to and from D-Bus messages are generated for us completely by the compiler.
We recommend that sdbus-c++ users prefer the convenience API to the lower level, basic API. When feasible, using generated adaptor and proxy C++ bindings is even better as it provides yet slightly higher abstraction built on top of the convenience API, where remote calls look simply like local, native calls of object methods. They are described in the following section.
**_Note_:** By default, signal callback handlers are not invoked (i.e., the signal is silently dropped) if there is a signal signature mismatch. If clients want to be informed of such situations, they can prepend
const sdbus::Error*
parameter to their signal callback handler's parameter list. This argument will benullptr
in normal cases, and will provide access to the correspondingsdbus::Error
object in case of deserialization failures. An example of a handler with the signature (int
) different from the real signal contents (string
):++{assert(e);assert(e->getMessage() == "Failed to deserialize a int32 value");}Signature mismatch in signal handlers is probably the most common reason why signals are not received in the client, while we can see them on the bus with
dbus-monitor
. Useconst sdbus::Error*
-based callback variant and inspect the error to check if that's the cause of such problems.
**_Tip_:** When registering a D-Bus object, we can additionally provide names of input and output parameters of its methods and names of parameters of its signals. When the object is introspected, these names are listed in the resulting introspection XML, which improves the description of object's interfaces:
++concatenator->registerMethod("concatenate").onInterface(interfaceName).withInputParamNames("numbers", "separator").withOutputParamNames("concatenatedString").implementedAs(&concatenate);concatenator->registerSignal("concatenated").onInterface(interfaceName).withParameters<std::string>("concatenatedString");
The convenience API hides away the level of D-Bus messages. But the messages carry with them additional information that may need in some implementations. For example, a name of a method call sender; or info on credentials. Is there a way to access a corresponding D-Bus message in a high-level callback handler?
Yes, there is – we can access the corresponding D-Bus message in:
Both IObject
and IProxy
provide the getCurrentlyProcessedMessage()
method. This method is meant to be called from within a callback handler. It returns a pointer to the corresponding D-Bus message that caused invocation of the handler. The pointer is only valid (dereferenceable) as long as the flow of execution does not leave the callback handler. When called from other contexts/threads, the pointer may be both zero or non-zero, and its dereferencing is undefined behavior.
An excerpt of the above example of concatenator modified to print out a name of the sender of method call:
sdbus-c++ ships with native C++ binding generator tool called sdbus-c++-xml2cpp
. The tool is very similar to dbusxx-xml2cpp
tool that comes with the dbus-c++ library.
The generator tool takes D-Bus XML IDL description of D-Bus interfaces on its input, and can be instructed to generate one or both of these: an adaptor header file for use on the server side, and a proxy header file for use on the client side. Like this:
The adaptor header file contains classes that can be used to implement interfaces described in the IDL (these classes represent object interfaces). The proxy header file contains classes that can be used to make calls to remote objects (these classes represent remote object interfaces).
As an example, let's look at an XML description of our Concatenator's interfaces.
After running this through the code generator, we get the generated code that is described in the following two subsections.
For each interface in the XML IDL file the generator creates one class that represents it. The class is de facto an interface which shall be implemented by the class inheriting it. The class' constructor takes care of registering all methods, signals and properties. For each D-Bus method there is a pure virtual member function. These pure virtual functions must be implemented in the child class. For each signal, there is a public function member that emits this signal.
Generated adaptor classes support move semantics. They are moveable but not copyable.
Analogously to the adaptor classes described above, there is one proxy class generated for one interface in the XML IDL file. The class is de facto a proxy to the concrete single interface of a remote object. For each D-Bus signal there is a pure virtual member function whose body must be provided in a child class. For each method, there is a public function member that calls the method remotely.
Generated proxy classes support move semantics. They are moveable but not copyable.
To implement a D-Bus object that implements all its D-Bus interfaces, we now need to create a class representing the D-Bus object. This class must inherit from all corresponding *_adaptor
classes (a-ka object interfaces, because these classes are as-if interfaces) and implement all pure virtual member functions.
How do we do that technically? Simply, our object class just needs to inherit from AdaptorInterfaces
variadic template class. We fill its template arguments with a list of all generated interface classes. The AdaptorInterfaces
is a convenience class that hides a few boiler-plate details. For example, in its constructor, it creates an Object
instance, and it takes care of proper initialization of all adaptor superclasses.
In our object class we need to:
registerAdaptor()
in the constructor, which makes the adaptor (the D-Bus object underneath it) available for remote calls,unregisterAdaptor()
, which, conversely, deregisters the adaptor from the bus.Calling registerAdaptor()
and unregisterAdaptor()
was not necessary in previous sdbus-c++ versions, as it was handled by the parent class. This was convenient, but suffered from a potential pure virtual function call issue. Only the class that implements virtual functions can do the registration, hence this slight inconvenience on user's shoulders.
**_Tip_:** By inheriting from
sdbus::AdaptorInterfaces
, we get access to the protectedgetObject()
method. We can call this method inside our adaptor implementation class to access the underlyingIObject
object.
That's it. We now have an implementation of a D-Bus object implementing org.sdbuscpp.Concatenator
interface. Let's now create a service publishing the object.
Now we have a service with a unique bus name and a D-Bus object available on it. Let's write a client.
To implement a proxy for a remote D-Bus object, we shall create a class representing the proxy object. This class must inherit from all corresponding *_proxy
classes (a-ka remote object interfaces, because these classes are as-if interfaces) and – if applicable – implement all pure virtual member functions.
How do we do that technically? Simply, our proxy class just needs to inherit from ProxyInterfaces
variadic template class. We fill its template arguments with a list of all generated interface classes. The ProxyInterfaces
is a convenience class that hides a few boiler-plate details. For example, in its constructor, it can create a Proxy
instance for us, and it takes care of proper initialization of all generated interface superclasses.
In our proxy class we need to:
registerProxy()
in the constructor, which makes the proxy (the D-Bus proxy object underneath it) ready to receive signals and async call replies,unregisterProxy()
, which, conversely, deregisters the proxy from the bus.Calling registerProxy()
and unregisterProxy()
was not necessary in previous versions of sdbus-c++, as it was handled by the parent class. This was convenient, but suffered from a potential pure virtual function call issue. Only the class that implements virtual functions can do the registration, hence this slight inconvenience on user's shoulders.
**_Tip_:** By inheriting from
sdbus::ProxyInterfaces
, we get access to the protectedgetProxy()
method. We can call this method inside our proxy implementation class to access the underlyingIProxy
object.
In the above example, a proxy is created that creates and maintains its own system bus connection. However, there are ProxyInterfaces
class template constructor overloads that also take the connection from the user as the first parameter, and pass that connection over to the underlying proxy. The connection instance is used by all interfaces listed in the ProxyInterfaces
template parameter list.
Note however that there are multiple ProxyInterfaces
constructor overloads, and they differ in how the proxy behaves towards the D-Bus connection. These overloads precisely map the sdbus::createProxy
overloads, as they are actually implemented on top of them. See Proxy and D-Bus connection for more info. We can even create a IProxy
instance on our own, and inject it into our proxy class – there is a constructor overload for it in ProxyInterfaces
. This can help if we need to provide mocked implementations in our unit tests.
Now let's use this proxy to make remote calls and listen to signals in a real application.
Simply combine getObject()
/getProxy()
and getCurrentlyProcessedMessage()
methods. Both were already discussed above. An example:
So far in our tutorial, we have only considered simple server methods that are executed in a synchronous way. Sometimes the method call may take longer, however, and we don't want to block (potentially starve) other clients (whose requests may take relative short time). The solution is to execute the D-Bus methods asynchronously, and return the control quickly back to the D-Bus dispatching thread. sdbus-c++ provides API supporting async methods, and gives users the freedom to come up with their own concrete implementation mechanics (one worker thread? thread pool? ...).
This is how the concatenate method would look like if wrote it as an asynchronous D-Bus method using the basic, lower-level API of sdbus-c++:
There are a few slight differences compared to the synchronous version. Notice that we std::move
the call
message to the worker thread (btw we might also do input arguments deserialization in the worker thread, we don't have to do it in the current thread and then move input arguments to the worker thread...). We need the call
message there to create the reply message once we have the (normal or error) result. Creating and sending replies, as well as creating and emitting signals is thread-safe by design. Also notice that, unlike in sync methods, sending back errors cannot be done by throwing Error
, since we are now in the context of the worker thread, not that of the D-Bus dispatcher thread. Instead, we pass the Error
object to the createErrorReply()
method of the call message (this way of sending back errors, in addition to throwing, we can actually use also in classic synchronous D-Bus methods).
Method callback signature is the same in sync and async version. That means sdbus-c++ doesn't care how we execute our D-Bus method. We might very well in run-time decide whether we execute it synchronously, or whether (perhaps in case of longer, more complex calculations) we move the execution to a worker thread.
Callbacks of async methods based on convenience sdbus-c++ API have slightly different signature. They take a result object parameter in addition to other input parameters. The requirements are:
Result<Types...>&&
, where Types...
is a list of method output argument types.Result
class template is move-only.std::move
them to the worker thread. Moving is usually a lot cheaper than copying, and it's idiomatic. For non-movable types, this falls back to copying.So the concatenate callback signature would change from std::string concatenate(const std::vector<int32_t>& numbers, const std::string& separator)
to void concatenate(sdbus::Result<std::string>&& result, std::vector<int32_t> numbers, std::string separator)
:
The Result
is a convenience class that represents a future method result, and it is where we write the results (returnResults()
) or an error (returnError()
) which we want to send back to the client.
Registration (implementedAs()
) doesn't change. Nothing else needs to change.
sdbus-c++-xml2cpp tool can generate C++ code for server-side async methods. We just need to annotate the method with org.freedesktop.DBus.Method.Async
. The annotation element value must be either server
(async method on server-side only) or client-server
(async method on both client- and server-side):
For a real example of a server-side asynchronous D-Bus method, please look at sdbus-c++ stress tests.
sdbus-c++ also supports asynchronous approach at the client (the proxy) side. With this approach, we can issue a D-Bus method call without blocking current thread's execution while waiting for the reply. We go on doing other things, and when the reply comes, either a given callback handler will be invoked within the context of the event loop thread, or a future object returned by the async call will be set the returned value.6
Considering the Concatenator example based on lower-level API, if we wanted to call concatenate
in an async way, we have two options: We either pass a callback to the proxy when issuing the call, and that callback gets invoked when the reply arrives:
The callback is a void-returning function taking two arguments: a reference to the reply message, and a pointer to the prospective sdbus::Error
instance. Zero Error
pointer means that no D-Bus error occurred while making the call, and the reply message contains valid reply. Non-zero Error
pointer, however, points to the valid Error
instance, meaning that an error occurred. Error name and message can then be read out by the client from that instance.
There is also an overload of this IProxy::callMethod()
function taking method call timeout argument.
Another option is to use std::future
-based overload of the IProxy::callMethod()
function. A future object will be returned which will later, when the reply arrives, be set to contain the returned reply message. Or if the call returns an error, sdbus::Error
will be thrown by std::future::get()
.
On the convenience API level, the call statement starts with callMethodAsync()
, and one option is to finish the statement with uponReplyInvoke()
that takes a callback handler. The callback is a void-returning function that takes at least one argument: pointer to the sdbus::Error
instance. All subsequent arguments shall exactly reflect the D-Bus method output arguments. A concatenator example:
When the Error
pointer is zero, it means that no D-Bus error occurred while making the call, and subsequent arguments are valid D-Bus method return values. Non-zero Error
pointer, however, points to the valid Error
instance, meaning that an error occurred during the call (and subsequent arguments are simply default-constructed). Error name and message can then be read out by the client from Error
instance.
Another option is to finish the async call statement with getResultAsFuture()
, which is a template function which takes the list of types returned by the D-Bus method (empty list in case of void
-returning method) which returns a std::future
object, which will later, when the reply arrives, be set to contain the return value(s). Or if the call returns an error, sdbus::Error
will be thrown by std::future::get()
.
The future object will contain void for a void-returning D-Bus method, a single type for a single value returning D-Bus method, and a std::tuple
to hold multiple return values of a D-Bus method.
sdbus-c++-xml2cpp can generate C++ code for client-side async methods. We just need to annotate the method with org.freedesktop.DBus.Method.Async
. The annotation element value must be either client
(async on the client-side only) or client-server
(async method on both client- and server-side):
An asynchronous method can be generated as a callback-based method or std::future
-based method. This can optionally be customized through an additional org.freedesktop.DBus.Method.Async.ClientImpl
annotation. Its supported values are callback
and std::future
. The default behavior is callback-based method.
For each client-side async method, a corresponding on<MethodName>Reply
pure virtual function, where <MethodName>
is the capitalized D-Bus method name, is generated in the generated proxy class. This function is the callback invoked when the D-Bus method reply arrives, and must be provided a body by overriding it in the implementation class.
So in the specific example above, the tool will generate a Concatenator_proxy
class similar to one shown in a dedicated section above, with the difference that it will also generate an additional virtual void onConcatenateReply(const sdbus::Error* error, const std::string& concatenatedString);
method, which we shall override in derived ConcatenatorProxy
.
In this case, a std::future
is returned by the method, which will later, when the reply arrives, get set to contain the return value. Or if the call returns an error, sdbus::Error
will be thrown by std::future::get()
.
For a real example of a client-side asynchronous D-Bus methods, please look at sdbus-c++ stress tests.
Annotate the element with org.freedesktop.DBus.Method.Timeout
in order to specify the timeout value for the method call. The value should be a number of microseconds or number with duration literal (us
/ms
/s
/min
). Optionally combine it with org.freedesktop.DBus.Method.Async
.
sdbus-c++ provides functionality for convenient working with D-Bus properties, on both convenience and generated code API level.
Let's say a remote D-Bus object provides property status
of type u
under interface org.sdbuscpp.Concatenator
.
We read property value easily through IProxy::getProperty()
method:
Getting a property in asynchronous manner is also possible, in both callback-based and future-based way, by calling IProxy::getPropertyAsync()
method:
More information on error
callback handler parameter, on behavior of future
in erroneous situations, can be found in section Asynchronous client-side methods.
Writing a property is equally simple, through IProxy::setProperty()
:
Setting a property in asynchronous manner is also possible, in both callback-based and future-based way, by calling IProxy::setPropertyAsync()
method:
More information on error
callback handler parameter, on behavior of future
in erroneous situations, can be found in section Asynchronous client-side methods.
In a very analogous way, with both synchronous and asynchronous options, it's possible to read all properties of an object under given interface at once. IProxy::getAllProperties()
is what you're looking for.
Defining and working with D-Bus properties using XML description is quite easy.
A property element has no arg child element. It just has the attributes name, type and access, which are all mandatory. The access attribute allows the values ‘readwrite’, ‘read’, and ‘write’.
An example of a read-write property status
:
The property may also have annotations. In addition to standard annotations defined in D-Bus specification, there are sdbus-c++-specific ones, discussed further below.
This is how generated adaptor and proxy classes would look like with the read-write status
property. The adaptor:
The proxy:
When implementing the adaptor, we simply need to provide the body for the status
getter and setter methods by overriding them. Then in the proxy, we just call them.
We can mark the property so that the generator generates either asynchronous variant of getter method, or asynchronous variant of setter method, or both. Annotations names are org.freedesktop.DBus.Property.Get.Async
, or org.freedesktop.DBus.Property.Set.Async
, respectively. Their values must be set to client
.
In addition, we can choose through annotations org.freedesktop.DBus.Property.Get.Async.ClientImpl
, or org.freedesktop.DBus.Property.Set.Async.ClientImpl
, respectively, whether a callback-based or future-based variant will be generated. The concept is analogous to the one for asynchronous D-Bus methods described above in this document.
The callback-based method will generate a pure virtual function On<PropertyName>Property[Get|Set]Reply()
, which must be overridden by the derived class.
For example, this description:
will get generated into this C++ code on client side:
In addition to custom generated code for getting/setting properties, org.freedesktop.DBus.Properties
standard D-Bus interface, implemented through pre-defined sdbus::Properties_proxy
in sdbus-c++/StandardInterfaces.h
, can also be used for reading/writing properties. See next section.
sdbus-c++ provides support for standard D-Bus interfaces. These are:
org.freedesktop.DBus.Peer
org.freedesktop.DBus.Introspectable
org.freedesktop.DBus.Properties
org.freedesktop.DBus.ObjectManager
The implementation of methods that these interfaces define is provided by the library. Peer
, Introspectable
and Properties
are automatically part of interfaces of every D-Bus object. ObjectManager
is not automatically present and has to be enabled by the client when using IObject
API. When using generated ObjectManager_adaptor
, ObjectManager
is enabled automatically in its constructor.
Pre-generated *_proxy
and *_adaptor
convenience classes for these standard interfaces are located in sdbus-c++/StandardInterfaces.h
. To use them, we simply have to add them as additional parameters of sdbus::ProxyInterfaces
or sdbus::AdaptorInterfaces
class template, and our proxy or adaptor class inherits convenience functions from those interface classes.
For example, for our Concatenator
example above in this tutorial, we may want to conveniently emit a PropertyChanged
signal under org.freedesktop.DBus.Properties
interface. First, we must augment our Concatenator
class to also inherit from org.freedesktop.DBus.Properties
interface: class Concatenator : public sdbus::AdaptorInterfaces<org::sdbuscpp::Concatenator_adaptor, sdbus::Properties_adaptor> {...};
, and then we just issue emitPropertiesChangedSignal
function of our adaptor object.
Note that signals of afore-mentioned standard D-Bus interfaces are not emitted by the library automatically. It's clients who are supposed to emit them.
Working examples of using standard D-Bus interfaces can be found in sdbus-c++ integration tests or the examples directory.
sdbus-c++ provides many default, pre-defined C++ type representations for D-Bus types. The table below shows which C++ type corresponds to which D-Bus type.
Category | Code | Code ASCII | Conventional Name | C++ Type |
---|---|---|---|---|
reserved | 0 | NUL | INVALID | - |
fixed, basic | 121 | y | BYTE | uint8_t |
fixed, basic | 98 | b | BOOLEAN | bool |
fixed, basic | 110 | n | INT16 | int16_t |
fixed, basic | 113 | q | UINT16 | uint16_t |
fixed, basic | 105 | i | INT32 | int32_t |
fixed, basic | 117 | u | UINT32 | uint32_t |
fixed, basic | 120 | x | INT64 | int64_t |
fixed, basic | 116 | t | UINT64 | uint64_t |
fixed, basic | 100 | d | DOUBLE | double |
string-like, basic | 115 | s | STRING | const char* , std::string |
string-like, basic | 111 | o | OBJECT_PATH | sdbus::ObjectPath |
string-like, basic | 103 | g | SIGNATURE | sdbus::Signature |
container | 97 | a | ARRAY | std::vector<T> , std::array<T> , std::span<T> - if used as an array followed by a single complete type T std::map<T1, T2> , std::unordered_map<T1, T2> - if used as an array of dict entries |
container | 114,40,41 | r() | STRUCT | sdbus::Struct<T1, T2, ...> variadic class template |
container | 118 | v | VARIANT | sdbus::Variant |
container | 101,123,125 | e{} | DICT_ENTRY | - |
fixed, basic | 104 | h | UNIX_FD | sdbus::UnixFd |
reserved | 109 | m | (reserved) | - |
reserved | 42 | * | (reserved) | - |
reserved | 63 | ? | (reserved) | - |
reserved | 64,38,94 | &^ | (reserved) | - |
A few examples:
GetManagedObjects()
on standard interface org.freedesktop.DBus.ObjectManager
is a{oa{sa{sv}}}
. For this the corresponding C++ method return type is: std::map<sdbus::ObjectPath, std::map<std::string, std::map<std::string, sdbus::Variant>>>
.InterfacesRemoved
on that interface has signature as
. Ths corresponds to the C++ parameter of type std::vector<std::string>
.a(bdh)
corresponds to the array of D-Bus structures: std::vector<sdbus::Struct<bool, double, sdbus::UnixFd>>
.To see how C++ types are mapped to D-Bus types (including container types) in sdbus-c++, have a look at individual specializations of sdbus::signature_of
class template in TypeTraits.h header file. For more examples of type mappings, look into TypeTraits unit tests.
For more information on basic D-Bus types, D-Bus container types, and D-Bus type system in general, make sure to consult the D-Bus specification.
The above mapping between D-Bus and C++ types is what sdbus-c++ provides by default. However, the mapping can be extended. Clients can implement additional mapping between a D-Bus type and their custom type.
We need two things to do that:
sdbus::Message
insertion (serialization) and extraction (deserialization) operators, so sdbus-c++ knows how to serialize/deserialize our custom type,sdbus::signature_of
template for our custom type, so sdbus-c++ knows the mapping to D-Bus type and other necessary information about our type.Say, we would like to represent D-Bus arrays as std::list
s in our application. Since sdbus-c++ comes with pre-defined support for std::vector
s, std::array
s and std::span
s as D-Bus array representations, we have to provide an extension. To implement message serialization and deserialization functions for std::list
, we can simply copy the sdbus-c++ implementation of these functions for std::vector
, and simply adjust for std::list
. Then we provide signature_of
specialization, again written on terms of one specialized for std::vector
:
Then we can simply use std::list
s, serialize/deserialize them in a D-Bus message, in D-Bus method calls or return values... and they will be simply transmitted as D-Bus arrays.
As another example, say we have our custom type my::Struct
which we'd like to use as a D-Bus structure representation (sdbus-c++ provides sdbus::Struct
type for that, but we don't want to use it because using our custom type directly is more convenient). Again, we have to provide type traits and message serialization/deserialization functions for our custom type. We build our functions and specializations on top of sdbus::Struct
, so we don't have to copy and write a lot of boiler-plate. Serialization/deserialization functions can be placed in the same namespace as our custom type, and will be found thanks to the ADR lookup. The signature_of
specialization must always be in either sdbus
namespace or in a global namespace:
**_Note_:** One of
my::Struct
members isstd::list
. Thanks to the above custom support forstd::list
, it's now automatically accepted by sdbus-c++ as a D-Bus array representation.
Live examples of extending sdbus-c++ types can be found in Message unit tests.
IConnection
class provides addMatch
and addMatchAsync
family of methods that you can use to install match rules on that bus connection. An associated callback handler will be called when an incoming D-Bus message matches the given match rule. Clients can decide whether they own and control the match rule lifetime, or whether the match rule lifetime is bound the connection object lifetime (so-called floating match rule). Consult IConnection
header or sdbus-c++ doxygen documentation for more information.
sdbus-c++ provides an API to establish a direct connection between two peers – between a client and a server, without going via the D-Bus daemon. The methods of interest, which will create a D-Bus server bus, and a client connection to it, respectively, are:
sdbus::createServerBus()
creates and returns a new, custom bus object in server mode, out of provided file descriptor parameter.sdbus::createDirectBusConnection()
opens and returns direct D-Bus connection at the provided custom address(es), or at the provided file descriptor.Here is an example, extracted from the analogous test case in sdbus-c++ integration tests suite:
**_Note_:** The example above explicitly stops the event loops on both sides, before the connection objects are destroyed. This avoids potential
Connection reset by peer
errors caused when one side closes its socket while the other side is still working on the counterpart socket. This is a recommended workflow for closing direct D-Bus connections.
There is no conclusion. Happy journeys by D-Bus with sdbus-c++!