From b57e023b3b3bd4a81a0f55c238cb893f9c5caa30 Mon Sep 17 00:00:00 2001 From: Andreas Eliasson Date: Mon, 7 Mar 2022 11:23:51 +0100 Subject: Doc: Revise Qt dbus module landing page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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ö --- src/dbus/doc/src/qtdbus-index.qdoc | 202 +++++----------------------------- src/dbus/doc/src/qtdbus-overview.qdoc | 199 +++++++++++++++++++++++++++++++++ 2 files changed, 229 insertions(+), 172 deletions(-) create mode 100644 src/dbus/doc/src/qtdbus-overview.qdoc (limited to 'src/dbus/doc/src') diff --git a/src/dbus/doc/src/qtdbus-index.qdoc b/src/dbus/doc/src/qtdbus-index.qdoc index c2963690f9..ace0c8c338 100644 --- a/src/dbus/doc/src/qtdbus-index.qdoc +++ b/src/dbus/doc/src/qtdbus-index.qdoc @@ -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 - - 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. - - \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 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 + \section1 Using the Module - 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. + \include {module-use.qdocinc} {using the c++ api} - 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. + \include {module-use.qdocinc} {building with cmake} {DBus} - 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. + \section1 Articles and Guides - \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. + 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 {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 - \include module-use.qdocinc using qt module - \snippet snippets/CMakeLists.txt cmake_use + \section1 Examples - See also the \l {Build with CMake} overview. + \list + \li \l{Qt D-Bus Examples} + \endlist - \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 */ /*! diff --git a/src/dbus/doc/src/qtdbus-overview.qdoc b/src/dbus/doc/src/qtdbus-overview.qdoc new file mode 100644 index 0000000000..2b37b33527 --- /dev/null +++ b/src/dbus/doc/src/qtdbus-overview.qdoc @@ -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. + +*/ -- cgit v1.2.3