1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Revise Qt dbus module landing page

Browse Source 
Move some of the detailed information into its own overview page and
reorganize the contents structure. Also, escape the _ character.

Task-number: QTBUG-100369
Pick-to: 6.3
Change-Id: I396877912bed66537e4a97ee3d109ff92e15d843
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
This commit is contained in:
Andreas Eliasson 2022-03-07 11:23:51 +01:00
parent b365186860
commit b57e023b3b
2 changed files with 229 additions and 172 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

202
src/dbus/doc/src/qtdbus-index.qdoc
View File

@ -32,188 +32,62 @@
\keyword QtDBus
\section1 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
was also 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
\tt{freedesktop.org} project, and is available to all parties.
\tt{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
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.
\section1 The Buses
\section1 Using the Module
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.
\include {module-use.qdocinc} {using the c++ api}
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.
\include {module-use.qdocinc} {building with cmake} {DBus}
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.
\section1 Articles and Guides
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.
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:
\section1 Concepts
\list
\li \l {Qt D-Bus Overview}
\li \l {Using Qt D-Bus Adaptors}
\li \l {The Qt D-Bus Type System}
\li \l {Qt D-Bus XML compiler (qdbusxml2cpp)}
\li \l{D-Bus Viewer}
\endlist
\section2 Messages
\section1 Examples
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.
\list
\li \l{Qt D-Bus Examples}
\endlist
A special kind of message called a "signal message"
(a concept based on Qt's \l {Signals and 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.
\section2 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
\tt{freedesktop.org} and can be found on the bus under the
service name:
\snippet code/doc_src_introtodbus.qdoc 0
\section2 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 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:
\image qurl-ftppath.png
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.
\section2 Interfaces
Interfaces are similar to C++ abstract classes and Java's
\c 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 \l {How to Create Qt
Plugins}{Plugin system}: Base classes in C++ are associated
with a unique identifier by way of the 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.
\section2 Cheat Sheet
To facilitate remembering of the naming formats and their
purposes, the following table can be used:
\table 90%
\header \li D-Bus Concept \li Analogy \li Name format
\row \li Service name \li Network hostnames \li Dot-separated
("looks like a hostname")
\row \li Object path \li URL path component \li Slash-separated
("looks like a path")
\row \li Interface \li Plugin identifier \li Dot-separated
\endtable
\section1 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
\c QDBUS_DEBUG environment variable before running each application.
For example, we can enable debugging only for the car in the
\l{D-Bus Remote Controlled Car Example} by running the controller and the
car in the following way:
\snippet code/doc_src_introtodbus.qdoc QDBUS_DEBUG
Information about the messages will be written to the console the application
was launched from.
\include module-use.qdocinc using qt module
\snippet snippets/CMakeLists.txt cmake_use
See also the \l {Build with CMake} overview.
\include module-use.qdocinc building with qmake
\snippet snippets/snippets.pro qmake_use
\section1 Reference
\list
\li \l{Qt D-Bus C++ Classes}
\li \l{CMake Commands in Qt6 DBus}
\endlist
\section1 Module Evolution
\l{Changes to Qt D-Bus} lists important changes in the module API
and functionality that were done for the Qt 6 series of Qt.
and functionality that were made for the Qt 6 series of Qt.
\section1 Licenses and Attributions
@ -224,25 +98,9 @@
See \l{Qt Licensing} for further details.
Furthermore, Qt D-Bus in Qt \QtVersion may contain third party
modules under following permissive licenses:
modules under the following permissive licenses:
\generatelist{groupsbymodule attributions-qtdbus}
\section1 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:
\list
\li \l{Using Qt D-Bus Adaptors}
\li \l{The Qt D-Bus Type System}
\li \l{Qt D-Bus XML compiler (qdbusxml2cpp)}
\li \l{Qt D-Bus C++ Classes}
\li \l{CMake Commands in Qt6 DBus}
\li \l{Qt D-Bus Examples}
\li \l{D-Bus Viewer}
\endlist
*/
/*!

199
src/dbus/doc/src/qtdbus-overview.qdoc Normal file
View File

@ -0,0 +1,199 @@
/****************************************************************************
**
** Copyright (C) 2022 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtdbus-overview.html
\title Qt D-Bus Overview
\brief Provides insight into the Qt Qt D-Bus module.
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
was also 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
\tt{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.
\section1 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 application 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, you can also expect to find restrictions on
what services each application is allowed to offer. Therefore, you
can be reasonably certain that if a certain service is present,
it's being offered by a trusted application.
\section1 Concepts
\section2 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 \l {Signals and 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.
\section2 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 your service name
according to the domain name of the organization that defined
that service.
For example, the D-Bus service is defined by
\tt{freedesktop.org} and can be found on the bus under the
service name:
\snippet code/doc_src_introtodbus.qdoc 0
\section2 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 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:
\image qurl-ftppath.png
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.
\section2 Interfaces
Interfaces are similar to C++ abstract classes and Java's
\c 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 \l {How to Create Qt
Plugins}{Plugin system}: Base classes in C++ are associated
with a unique identifier by way of the 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.
\section2 Cheat Sheet
To facilitate remembering of the naming formats and their
purposes, the following table can be used:
\table 90%
\header \li D-Bus Concept \li Analogy \li Name format
\row \li Service name \li Network hostnames \li Dot-separated
("looks like a hostname")
\row \li Object path \li URL path component \li Slash-separated
("looks like a path")
\row \li Interface \li Plugin identifier \li Dot-separated
\endtable
\section1 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
\c QDBUS_DEBUG environment variable before running each application.
For example, we can enable debugging only for the car in the
\l{D-Bus Remote Controlled Car Example} by running the controller and the
car in the following way:
\snippet code/doc_src_introtodbus.qdoc QDBUS_DEBUG
Information about the messages will be written to the console the application
was launched from.
*/