diff options
Diffstat (limited to 'src/dbus/doc/src/qtdbus-index.qdoc')
| -rw-r--r-- | src/dbus/doc/src/qtdbus-index.qdoc | 229 |
1 files changed, 32 insertions, 197 deletions
diff --git a/src/dbus/doc/src/qtdbus-index.qdoc b/src/dbus/doc/src/qtdbus-index.qdoc index afd70c2f7c..05ca38a207 100644 --- a/src/dbus/doc/src/qtdbus-index.qdoc +++ b/src/dbus/doc/src/qtdbus-index.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2020 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$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtdbus-index.html @@ -32,188 +8,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 to 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 be probably 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 organised, much like the parent-child - relationship that classes derived from QObject possess. One - difference, however, is that there is the concept of "root - object", that all objects have as 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,24 +74,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{Qt D-Bus Examples} - \li \l{D-Bus Viewer} - \endlist */ /*! |