Long live Qt for S60!

1 files changed, 212 insertions, 0 deletions

diff --git a/doc/src/introtodbus.qdoc b/doc/src/introtodbus.qdoc
new file mode 100644
index 0000000..71c65d5
--- /dev/null
+++ b/doc/src/introtodbus.qdoc
@@ -0,0 +1,212 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page intro-to-dbus.html
+    \title Introduction to D-Bus
+
+    \keyword QtDBus
+    \ingroup architecture
+    \brief An introduction to Inter-Process Communication and Remote Procedure Calling with D-Bus.
+
+    \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
+
+    \section2 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
+*/