diff options
Diffstat (limited to 'doc/src/frameworks-technologies/dbus-intro.qdoc')
| -rw-r--r-- | doc/src/frameworks-technologies/dbus-intro.qdoc | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/doc/src/frameworks-technologies/dbus-intro.qdoc b/doc/src/frameworks-technologies/dbus-intro.qdoc new file mode 100644 index 0000000000..b1fcc441ae --- /dev/null +++ b/doc/src/frameworks-technologies/dbus-intro.qdoc @@ -0,0 +1,229 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page intro-to-dbus.html + \title Introduction to D-Bus + \brief An introduction to Inter-Process Communication and Remote Procedure Calling with D-Bus. + + \keyword QtDBus + \ingroup frameworks-technologies + + \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 QtDBus 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 doc/src/snippets/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: + + \img 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 \o D-Bus Concept \o Analogy \o Name format + \row \o Service name \o Network hostnames \o Dot-separated + ("looks like a hostname") + \row \o Object path \o URL path component \o Slash-separated + ("looks like a path") + \row \o Interface \o Plugin identifier \o 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 doc/src/snippets/code/doc_src_introtodbus.qdoc QDBUS_DEBUG + + Information about the messages will be written to the console the application + was launched from. + + \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 + \o \l{Using QtDBus Adaptors} + \o \l{The QtDBus Type System} + \o \l{QtDBus XML compiler (qdbusxml2cpp)} + \endlist +*/ |