1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
|
An introduction to Inter-Process Communication and Remote Procedure
Calling with D-Bus.
Introduction
^^^^^^^^^^^^
D-Bus is an Inter-Process Communication (IPC) and Remote Procedure
Calling (RPC) mechanism originally developed for Linux to replace
existing and competing IPC solutions with one unified protocol. It has
also been designed to allow communication between system-level
processes (such as printer and hardware driver services) and normal
user processes.
It uses a fast, binary message-passing protocol, which is suitable for
same-machine communication due to its low latency and low overhead.
Its specification is currently defined by the ``freedesktop.org``
project, and is available to all parties.
Communication in general happens through a central server application,
called the "bus" (hence the name), but direct
application-to-application communication is also possible. When
communicating on a bus, applications can query which other
applications and services are available, as well as activate one on
demand.
The Buses
^^^^^^^^^
D-Bus buses are used when many-to-many communication is desired. In
order to achieve that, a central server is launched before any
applications can connect to the bus: this server is responsible for
keeping track of the applications that are connected and for properly
routing messages from their source to their destination.
In addition, D-Bus defines two well-known buses, called the system bus
and the session bus. These buses are special in the sense that they
have well-defined semantics: some services are defined to be found in
one or both of these buses.
For example, an application wishing to query the list of hardware
devices attached to the computer will probably communicate to a
service available on the system bus, while the service providing
opening of the user's web browser will probably be found on the
session bus.
On the system bus, one can also expect to find restrictions on what
services each application is allowed to offer. Therefore, one can be
reasonably certain that, if a certain service is present, it is being
offered by a trusted application.
Messages
^^^^^^^^
On the low level, applications communicate over D-Bus by sending
messages to one another. Messages are used to relay the remote
procedure calls as well as the replies and errors associated with
them. When used over a bus, messages have a destination, which means
they are routed only to the interested parties, avoiding congestion
due to "swarming" or broadcasting.
A special kind of message called a "signal message" (a concept based
on Qt's :ref:`Signals and Slots<Signals---Slots>` mechanism), however,
does not have a pre-defined destination. Since its purpose is to be
used in a one-to-many context, signal messages are designed to work
over an "opt-in" mechanism.
The Qt D-Bus module fully encapsulates the low-level concept of
messages into a simpler, object-oriented approach familiar to Qt
developers. In most cases, the developer need not worry about sending
or receiving messages.
Service Names
^^^^^^^^^^^^^
When communicating over a bus, applications obtain what is called a
"service name": it is how that application chooses to be known by
other applications on the same bus. The service names are brokered by
the D-Bus bus daemon and are used to route messages from one
application to another. An analogous concept to service names are IP
addresses and hostnames: a computer normally has one IP address and
may have one or more hostnames associated with it, according to the
services that it provides to the network.
On the other hand, if a bus is not used, service names are also not
used. If we compare this to a computer network again, this would
equate to a point-to-point network: since the peer is known, there is
no need to use hostnames to find it or its IP address.
The format of a D-Bus service name is in fact very similar to a host
name: it is a dot-separated sequence of letters and digits. The common
practice is even to name one's service name according to the domain
name of the organization that defined that service.
For example, the D-Bus service is defined by ``freedesktop.org`` and
can be found on the bus under the service name:
::
org.freedesktop.DBus
Object Paths
^^^^^^^^^^^^
Like network hosts, applications provide specific services to other
applications by exporting objects. Those objects are hierarchically
organized, much like the parent-child relationship that classes
derived from :class:`QObject<PySide6.QtCore.QObject>` possess. One
difference, however, is that there is the concept of "root object",
which all objects have as the ultimate parent.
If we continue our analogy with Web services, object paths equate to
the path part of a URL.
Like them, object paths in D-Bus are formed resembling path names on
the filesystem: they are slash-separated labels, each consisting of
letters, digits and the underscore character ("\_"). They must always
start with a slash and must not end with one.
Interfaces
^^^^^^^^^^
Interfaces are similar to C++ abstract classes and Java's
``interface`` keyword and declare the "contract" that is established
between caller and callee. That is, they establish the names of the
methods, signals, and properties that are available as well as the
behavior that is expected from either side when communication is
established.
Qt uses a very similar mechanism in its Plugin system: Base classes in
C++ are associated with a unique identifier by way of the
:meth:`Q\_DECLARE\_INTERFACE()<~QtDBus.Q_DECLARE_INTERFACE>` macro.
D-Bus interface names are, in fact, named in a manner similar to what
is suggested by the Qt Plugin System: an identifier usually
constructed from the domain name of the entity that defined that
interface.
Cheat Sheet
^^^^^^^^^^^
To facilitate remembering of the naming formats and their purposes,
the following table can be used:
+-------------+------------------+---------------------------------------+
|D-Bus Concept|Analogy |Name format |
+-------------+------------------+---------------------------------------+
|Service name |Network hostnames |Dot-separated ("looks like a hostname")|
+-------------+------------------+---------------------------------------+
|Object path |URL path component|Slash-separated ("looks like a path") |
+-------------+------------------+---------------------------------------+
|Interface |Plugin identifier |Dot-separated |
+-------------+------------------+---------------------------------------+
Debugging
^^^^^^^^^
When developing applications that use D-Bus, it is sometimes useful to
be able to see information about the messages that are sent and
received across the bus by each application.
This feature can be enabled on a per-application basis by setting the
``QDBUS_DEBUG`` environment variable before running each application.
For example, we can enable debugging only for the car in the
:ref:`D-Bus Remote Controlled Car
Example<D-Bus-Remote-Controlled-Car-Example>` by running the
controller and the car in the following way:
::
QDBUS_DEBUG=1 python examples/dbus/pingpong/pong.py
Information about the messages will be written to the console the
application was launched from.
Using the Module
^^^^^^^^^^^^^^^^
To include the definitions of modules classes, use the following
directive:
::
import PySide6.QtDBus
Further Reading
^^^^^^^^^^^^^^^
The following documents contain information about Qt's D-Bus integration features, and provide details about the mechanisms used to send and receive type information over the bus:
* `Using Qt D-Bus Adaptors <https://doc.qt.io/qt-6/usingadaptors.html>`_
* `The Qt D-Bus Type System <https://doc.qt.io/qt-6/qdbustypesystem.html>`_
* `Qt D-Bus XML compiler (qdbusxml2cpp) <https://doc.qt.io/qt-6/qdbusxml2cpp.html>`_
* `D-Bus Viewer <https://doc.qt.io/qt-6/qdbusviewer.html>`_
|
