/**************************************************************************** ** ** Copyright (C) 2018 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-index.html \title Qt D-Bus \brief An introduction to Inter-Process Communication and Remote Procedure Calling with D-Bus. \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 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 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 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. \section1 Licenses The Qt D-Bus module is available under commercial licenses from \l{The Qt Company}. In addition, it is available under free software licenses. Since Qt 5.4, these free software licenses are \l{GNU Lesser General Public License, version 3}, or the \l{GNU General Public License, version 2}. See \l{Qt Licensing} for further details. \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 */ /*! \page qdbusviewer.html \title D-Bus Viewer \keyword qdbusviewer The Qt D-Bus Viewer is a tool that lets you introspect D-Bus objects and messages. You can choose between the system bus and the session bus. Click on any service on the list on the left side to see all the exported objects. You can invoke methods by double-clicking on them. If a method takes one or more IN parameters, a property editor opens. Right-click on a signal to connect to it. All emitted signals including their parameters are output in the message view on the lower side of the window. */