source: trunk/doc/src/frameworks-technologies/dbus-intro.qdoc@ 846

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page intro-to-dbus.html
    \title D-Bus
    \brief An introduction to Inter-Process Communication and Remote Procedure Calling with D-Bus.

    \keyword QtDBus
    \ingroup technology-apis

    \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.