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