summaryrefslogtreecommitdiffstats
path: root/src/dbus
diff options
context:
space:
mode:
Diffstat (limited to 'src/dbus')
-rw-r--r--src/dbus/dbus.pro3
-rw-r--r--src/dbus/doc/qtdbus.qdocconf92
-rw-r--r--src/dbus/doc/snippets/code/doc_src_introtodbus.qdoc48
-rw-r--r--src/dbus/doc/snippets/code/doc_src_qdbusadaptors.cpp293
-rw-r--r--src/dbus/doc/snippets/code/doc_src_qtdbus.cpp43
-rw-r--r--src/dbus/doc/snippets/code/doc_src_qtdbus.pro3
-rw-r--r--src/dbus/doc/snippets/code/src_qdbus_qdbusabstractinterface.cpp60
-rw-r--r--src/dbus/doc/snippets/code/src_qdbus_qdbusargument.cpp191
-rw-r--r--src/dbus/doc/snippets/code/src_qdbus_qdbuscontext.cpp72
-rw-r--r--src/dbus/doc/snippets/code/src_qdbus_qdbusinterface.cpp51
-rw-r--r--src/dbus/doc/snippets/code/src_qdbus_qdbusmetatype.cpp44
-rw-r--r--src/dbus/doc/snippets/code/src_qdbus_qdbuspendingcall.cpp65
-rw-r--r--src/dbus/doc/snippets/code/src_qdbus_qdbuspendingreply.cpp63
-rw-r--r--src/dbus/doc/snippets/code/src_qdbus_qdbusreply.cpp54
-rw-r--r--src/dbus/doc/snippets/qdbusextratypes/qdbusextratypes.cpp66
-rw-r--r--src/dbus/doc/src/dbus-adaptors.qdoc481
-rw-r--r--src/dbus/doc/src/dbus-intro.qdoc215
-rw-r--r--src/dbus/doc/src/qdbusxml2cpp.qdoc49
-rw-r--r--src/dbus/doc/src/qtdbus.qdoc65
-rw-r--r--src/dbus/qdbusabstractinterface.cpp4
-rw-r--r--src/dbus/qdbusargument.cpp22
-rw-r--r--src/dbus/qdbuscontext.cpp2
-rw-r--r--src/dbus/qdbusextratypes.cpp4
-rw-r--r--src/dbus/qdbusinterface.cpp2
-rw-r--r--src/dbus/qdbusmetatype.cpp2
-rw-r--r--src/dbus/qdbuspendingcall.cpp4
-rw-r--r--src/dbus/qdbuspendingreply.cpp8
-rw-r--r--src/dbus/qdbusreply.cpp4
28 files changed, 1984 insertions, 26 deletions
diff --git a/src/dbus/dbus.pro b/src/dbus/dbus.pro
index 100736252e..b1a3e12e1f 100644
--- a/src/dbus/dbus.pro
+++ b/src/dbus/dbus.pro
@@ -35,6 +35,9 @@ load(qt_module_config)
HEADERS += $$QT_SOURCE_TREE/src/dbus/qtdbusversion.h
+QMAKE_DOCS = $$PWD/doc/qtdbus.qdocconf
+QMAKE_DOCS_INDEX = ../../doc
+
PUB_HEADERS = qdbusargument.h \
qdbusconnectioninterface.h \
qdbusmacros.h \
diff --git a/src/dbus/doc/qtdbus.qdocconf b/src/dbus/doc/qtdbus.qdocconf
new file mode 100644
index 0000000000..d33c4370a3
--- /dev/null
+++ b/src/dbus/doc/qtdbus.qdocconf
@@ -0,0 +1,92 @@
+include(../../../doc/global/qt-cpp-ignore.qdocconf)
+
+project = QtDBus
+description = Qt DBus Reference Documentation
+url = http://qt-project.org/doc/qt-5.0/qtdbus
+version = 5.0.0
+
+sourceencoding = UTF-8
+outputencoding = UTF-8
+naturallanguage = en_US
+qhp.projects = QtDBus
+
+qhp.QtDBus.file = qtdbus.qhp
+qhp.QtDBus.namespace = org.qt-project.qtdbus.500
+qhp.QtDBus.virtualFolder = qdoc
+qhp.QtDBus.indexTitle = Qt DBus Reference Documentation
+qhp.QtDBus.indexRoot =
+
+qhp.QtDBus.filterAttributes = qtdbus 5.0.0 qtrefdoc
+qhp.QtDBus.customFilters.Qt.name = QtDBus 5.0.0
+qhp.QtDBus.customFilters.Qt.filterAttributes = qtdbus 5.0.0
+qhp.QtDBus.subprojects = classes overviews examples
+qhp.QtDBus.subprojects.classes.title = Classes
+qhp.QtDBus.subprojects.classes.indexTitle = Qt DBus' Classes
+qhp.QtDBus.subprojects.classes.selectors = class fake:headerfile
+qhp.QtDBus.subprojects.classes.sortPages = true
+qhp.QtDBus.subprojects.overviews.title = Overviews
+qhp.QtDBus.subprojects.overviews.indexTitle = All Overviews and HOWTOs
+qhp.QtDBus.subprojects.overviews.selectors = fake:page,group,module
+qhp.QtDBus.subprojects.examples.title = Qt DBus Examples
+qhp.QtDBus.subprojects.examples.indexTitle = Qt DBus Examples
+qhp.QtDBus.subprojects.examples.selectors = fake:example
+
+dita.metadata.default.author = Qt Project
+dita.metadata.default.permissions = all
+dita.metadata.default.publisher = Qt Project
+dita.metadata.default.copyryear = 2012
+dita.metadata.default.copyrholder = Nokia
+dita.metadata.default.audience = programmer
+
+sources.fileextensions = "*.c++ *.cc *.cpp *.cxx *.mm *.qml *.qdoc"
+headers.fileextensions = "*.ch *.h *.h++ *.hh *.hpp *.hxx"
+
+examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css"
+examples.imageextensions = "*.png"
+
+outputdir = ../../../doc/qtdbus
+tagfile = ../../../doc/qtdbus/qtdbus.tags
+
+HTML.generatemacrefs = "true"
+HTML.nobreadcrumbs = "true"
+
+HTML.templatedir = .
+
+HTML.stylesheets = ../../../doc/global/style/offline.css
+
+HTML.headerstyles = \
+ " <link rel=\"stylesheet\" type=\"text/css\" href=\"style/offline.css\" />\n"
+
+HTML.endheader = \
+ "</head>\n" \
+
+defines = Q_QDOC \
+ QT_.*_SUPPORT \
+ QT_.*_LIB \
+ QT_COMPAT \
+ QT_KEYPAD_NAVIGATION \
+ QT_NO_EGL \
+ Q_WS_.* \
+ Q_OS_.* \
+ Q_BYTE_ORDER \
+ QT_DEPRECATED \
+ QT_DEPRECATED_* \
+ Q_NO_USING_KEYWORD \
+ __cplusplus \
+ Q_COMPILER_INITIALIZER_LISTS
+
+versionsym = QT_VERSION_STR
+
+codeindent = 1
+
+depends += qtcore
+
+headerdirs += ..
+
+sourcedirs += ..
+
+exampledirs += ../../../examples \
+ ../ \
+ snippets
+
+imagedirs += images
diff --git a/src/dbus/doc/snippets/code/doc_src_introtodbus.qdoc b/src/dbus/doc/snippets/code/doc_src_introtodbus.qdoc
new file mode 100644
index 0000000000..5d8833cb16
--- /dev/null
+++ b/src/dbus/doc/snippets/code/doc_src_introtodbus.qdoc
@@ -0,0 +1,48 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+org.freedesktop.DBus
+//! [0]
+
+//! [QDBUS_DEBUG]
+examples/dbus/remotecontrolledcar/controller/controller &
+QDBUS_DEBUG=1 examples/dbus/remotecontrolledcar/car/car &
+//! [QDBUS_DEBUG]
diff --git a/src/dbus/doc/snippets/code/doc_src_qdbusadaptors.cpp b/src/dbus/doc/snippets/code/doc_src_qdbusadaptors.cpp
new file mode 100644
index 0000000000..279c10f1e6
--- /dev/null
+++ b/src/dbus/doc/snippets/code/doc_src_qdbusadaptors.cpp
@@ -0,0 +1,293 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+class MainApplicationAdaptor: public QDBusAbstractAdaptor
+{
+ Q_OBJECT
+ Q_CLASSINFO("D-Bus Interface", "org.kde.DBus.MainApplication")
+ Q_PROPERTY(QString caption READ caption WRITE setCaption)
+ Q_PROPERTY(QString organizationName READ organizationName)
+ Q_PROPERTY(QString organizationDomain READ organizationDomain)
+
+private:
+ QApplication *app;
+
+public:
+ MainApplicationAdaptor(QApplication *application)
+ : QDBusAbstractAdaptor(application), app(application)
+ {
+ connect(application, SIGNAL(aboutToQuit()), SIGNAL(aboutToQuit()));
+ connect(application, SIGNAL(focusChanged(QWidget*, QWidget*)),
+ SLOT(focusChangedSlot(QWidget*, QWidget*)));
+ }
+
+ QString caption()
+ {
+ if (app->hasMainWindow())
+ return app->mainWindow()->caption();
+ return QString(""); // must not return a null QString
+ }
+
+ void setCaption(const QString &newCaption)
+ {
+ if (app->hasMainWindow())
+ app->mainWindow()->setCaption(newCaption);
+ }
+
+ QString organizationName()
+ {
+ return app->organizationName();
+ }
+
+ QString organizationDomain()
+ {
+ return app->organizationDomain();
+ }
+
+public slots:
+ Q_NOREPLY void quit()
+ { app->quit(); }
+
+ void reparseConfiguration()
+ { app->reparseConfiguration(); }
+
+ QString mainWindowObject()
+ {
+ if (app->hasMainWindow())
+ return QString("/%1/mainwindow").arg(app->applicationName());
+ return QString();
+ }
+
+ void setSessionManagement(bool enable)
+ {
+ if (enable)
+ app->enableSessionManagement();
+ else
+ app->disableSessionManagement();
+ }
+
+private slots:
+ void focusChangedSlot(QWidget *, QWidget *now)
+ {
+ if (now == app->mainWindow())
+ emit mainWindowHasFocus();
+ }
+
+signals:
+ void aboutToQuit();
+ void mainWindowHasFocus();
+};
+//! [0]
+
+
+//! [1]
+interface org.kde.DBus.MainApplication
+{
+ property readwrite STRING caption
+ property read STRING organizationName
+ property read STRING organizationDomain
+
+ method quit() annotation("org.freedesktop.DBus.Method.NoReply", "true")
+ method reparseConfiguration()
+ method mainWindowObject(out STRING)
+ method disableSessionManagement(in BOOLEAN enable)
+
+ signal aboutToQuit()
+ signal mainWindowHasFocus()
+}
+//! [1]
+
+
+//! [2]
+int main(int argc, char **argv)
+{
+ // create the QApplication object
+ QApplication app(argc, argv);
+
+ // create the MainApplication adaptor:
+ new MainApplicationAdaptor(app);
+
+ // connect to D-Bus and register as an object:
+ QDBusConnection::sessionBus().registerObject("/MainApplication", app);
+
+ // add main window, etc.
+ [...]
+
+ app.exec();
+}
+//! [2]
+
+
+//! [3]
+class MainApplicationAdaptor: public QDBusAbstractAdaptor
+{
+ Q_OBJECT
+ Q_CLASSINFO("D-Bus Interface", "org.kde.DBus.MainApplication")
+//! [3]
+
+
+//! [4]
+ Q_PROPERTY(QString caption READ caption WRITE setCaption)
+ Q_PROPERTY(QString organizationName READ organizationName)
+ Q_PROPERTY(QString organizationDomain READ organizationDomain)
+//! [4]
+
+
+//! [5]
+QString caption()
+{
+ if (app->hasMainWindow())
+ return app->mainWindow()->caption();
+ return QString();
+}
+
+void setCaption(const QString &newCaption)
+{
+ if (app->hasMainWindow())
+ app->mainWindow()->setCaption(newCaption);
+}
+
+QString organizationName()
+{
+ return app->organizationName();
+}
+
+QString organizationDomain()
+{
+ return app->organizationDomain();
+}
+//! [5]
+
+
+//! [6]
+MyInterfaceAdaptor(QApplication *application)
+ : QDBusAbstractAdaptor(application), app(application)
+{
+ connect(application, SIGNAL(aboutToQuit()), SIGNAL(aboutToQuit());
+ connect(application, SIGNAL(focusChanged(QWidget*, QWidget*)),
+ SLOT(focusChangedSlot(QWidget*, QWidget*)));
+}
+//! [6]
+
+
+//! [7]
+public slots:
+ Q_NOREPLY void quit()
+ { app->quit(); }
+
+ void reparseConfiguration()
+ { app->reparseConfiguration(); }
+
+ QString mainWindowObject()
+ {
+ if (app->hasMainWindow())
+ return QString("/%1/mainwindow").arg(app->applicationName());
+ return QString();
+ }
+
+ void setSessionManagement(bool enable)
+ {
+ if (enable)
+ app->enableSessionManagement();
+ else
+ app->disableSessionManagement();
+ }
+//! [7]
+
+
+//! [8]
+signals:
+ void aboutToQuit();
+ void mainWindowHasFocus();
+//! [8]
+
+
+//! [9]
+private slots:
+ void focusChangedSlot(QWidget *, QWidget *now)
+ {
+ if (now == app->mainWindow())
+ emit mainWindowHasFocus();
+ }
+//! [9]
+
+
+//! [10]
+struct RequestData
+{
+ QString request;
+ QString processedData;
+ QDBusMessage reply;
+};
+
+QString processRequest(const QString &request, const QDBusMessage &message)
+{
+ RequestData *data = new RequestData;
+ data->request = request;
+ message.setDelayedReply(true);
+ data->reply = message.createReply();
+ QDBusConnection::sessionBus().send(data->reply);
+
+ appendRequest(data);
+ return QString();
+}
+//! [10]
+
+
+//! [11]
+void sendReply(RequestData *data)
+{
+ // data->processedData has been initialized with the request's reply
+ QDBusMessage &reply = &data->reply;
+
+ // send the reply over D-Bus:
+ reply << data->processedData;
+ QDBusConnection::sessionBus().send(reply);
+
+ // dispose of the transaction data
+ delete data;
+}
+//! [11]
+
+
+//! [12]
+Q_NOREPLY void myMethod();
+//! [12]
diff --git a/src/dbus/doc/snippets/code/doc_src_qtdbus.cpp b/src/dbus/doc/snippets/code/doc_src_qtdbus.cpp
new file mode 100644
index 0000000000..65fc2e716b
--- /dev/null
+++ b/src/dbus/doc/snippets/code/doc_src_qtdbus.cpp
@@ -0,0 +1,43 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+#include <QtDBus>
+//! [0]
diff --git a/src/dbus/doc/snippets/code/doc_src_qtdbus.pro b/src/dbus/doc/snippets/code/doc_src_qtdbus.pro
new file mode 100644
index 0000000000..a1ba138a85
--- /dev/null
+++ b/src/dbus/doc/snippets/code/doc_src_qtdbus.pro
@@ -0,0 +1,3 @@
+#! [1]
+QT += dbus
+#! [1]
diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbusabstractinterface.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbusabstractinterface.cpp
new file mode 100644
index 0000000000..c16380f569
--- /dev/null
+++ b/src/dbus/doc/snippets/code/src_qdbus_qdbusabstractinterface.cpp
@@ -0,0 +1,60 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+QString value = retrieveValue();
+QDBusMessage reply;
+
+QDBusReply<int> api = interface->call(QLatin1String("GetAPIVersion"));
+if (api >= 14)
+ reply = interface->call(QLatin1String("ProcessWorkUnicode"), value);
+else
+ reply = interface->call(QLatin1String("ProcessWork"), QLatin1String("UTF-8"), value.toUtf8());
+//! [0]
+
+//! [1]
+QString value = retrieveValue();
+QDBusPendingCall pcall = interface->asyncCall(QLatin1String("Process"), value);
+
+QDBusPendingCallWatcher *watcher = new QDBusPendingCallWatcher(pcall, this);
+
+QObject::connect(watcher, SIGNAL(finished(QDBusPendingCallWatcher*)),
+ this, SLOT(callFinishedSlot(QDBusPendingCallWatcher*)));
+//! [1]
diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbusargument.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbusargument.cpp
new file mode 100644
index 0000000000..6fa0ec5fa3
--- /dev/null
+++ b/src/dbus/doc/snippets/code/src_qdbus_qdbusargument.cpp
@@ -0,0 +1,191 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+struct MyStructure
+{
+ int count;
+ QString name;
+};
+Q_DECLARE_METATYPE(MyStructure)
+
+// Marshall the MyStructure data into a D-Bus argument
+QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &mystruct)
+{
+ argument.beginStructure();
+ argument << mystruct.count << mystruct.name;
+ argument.endStructure();
+ return argument;
+}
+
+// Retrieve the MyStructure data from the D-Bus argument
+const QDBusArgument &operator>>(const QDBusArgument &argument, MyStructure &mystruct)
+{
+ argument.beginStructure();
+ argument >> mystruct.count >> mystruct.name;
+ argument.endStructure();
+ return argument;
+}
+//! [0]
+
+
+//! [1]
+qDBusRegisterMetaType<MyStructure>();
+//! [1]
+
+
+//! [2]
+MyType item = qdbus_cast<Type>(argument);
+//! [2]
+
+
+//! [3]
+MyType item;
+argument >> item;
+//! [3]
+
+
+//! [4]
+QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &mystruct)
+{
+ argument.beginStructure();
+ argument << mystruct.member1 << mystruct.member2 << ... ;
+ argument.endStructure();
+ return argument;
+}
+//! [4]
+
+
+//! [5]
+QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &mystruct)
+{
+ argument.beginStructure();
+ argument << mystruct.member1 << mystruct.member2;
+
+ argument.beginStructure();
+ argument << mystruct.member3.subMember1 << mystruct.member3.subMember2;
+ argument.endStructure();
+
+ argument << mystruct.member4;
+ argument.endStructure();
+ return argument;
+}
+//! [5]
+
+
+//! [6]
+// append an array of MyElement types
+QDBusArgument &operator<<(QDBusArgument &argument, const MyArray &myarray)
+{
+ argument.beginArray( qMetaTypeId<MyElement>() );
+ for ( int i = 0; i < myarray.length; ++i )
+ argument << myarray.elements[i];
+ argument.endArray();
+ return argument;
+}
+//! [6]
+
+
+//! [7]
+// append a dictionary that associates ints to MyValue types
+QDBusArgument &operator<<(QDBusArgument &argument, const MyDictionary &mydict)
+{
+ argument.beginMap( QVariant::Int, qMetaTypeId<MyValue>() );
+ for ( int i = 0; i < mydict.length; ++i ) {
+ argument.beginMapEntry();
+ argument << mydict.data[i].key << mydict.data[i].value;
+ argument.endMapEntry();
+ }
+ argument.endMap();
+ return argument;
+}
+//! [7]
+
+
+//! [8]
+const QDBusArgument &operator>>(const QDBusArgument &argument, MyStructure &mystruct)
+{
+ argument.beginStructure()
+ argument >> mystruct.member1 >> mystruct.member2 >> mystruct.member3 >> ...;
+ argument.endStructure();
+ return argument;
+}
+//! [8]
+
+
+//! [9]
+// extract a MyArray array of MyElement elements
+const QDBusArgument &operator>>(const QDBusArgument &argument, MyArray &myarray)
+{
+ argument.beginArray();
+ myarray.clear();
+
+ while ( !argument.atEnd() ) {
+ MyElement element;
+ argument >> element;
+ myarray.append( element );
+ }
+
+ argument.endArray();
+ return argument;
+}
+//! [9]
+
+
+//! [10]
+// extract a MyDictionary map that associates ints to MyValue elements
+const QDBusArgument &operator>>(const QDBusArgument &argument, MyDictionary &mydict)
+{
+ argument.beginMap();
+ mydict.clear();
+
+ while ( !argMap.atEnd() ) {
+ int key;
+ MyValue value;
+ argument.beginMapEntry();
+ argument >> key >> value;
+ argument.endMapEntry();
+ mydict.append( key, value );
+ }
+
+ argument.endMap();
+ return argument;
+}
+//! [10]
diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbuscontext.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbuscontext.cpp
new file mode 100644
index 0000000000..9ea2038aab
--- /dev/null
+++ b/src/dbus/doc/snippets/code/src_qdbus_qdbuscontext.cpp
@@ -0,0 +1,72 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+class MyObject: public QObject,
+ protected QDBusContext
+{
+ Q_OBJECT
+ QDBusConnection conn;
+ QDBusMessage msg;
+
+...
+
+protected slots:
+ void process();
+public slots:
+ void methodWithError();
+ QString methodWithDelayedReply();
+};
+
+void MyObject::methodWithError()
+{
+ sendErrorReply(QDBusError::NotSupported,
+ "The method call 'methodWithError()' is not supported");
+}
+
+QString MyObject::methodWithDelayedReply()
+{
+ conn = connection();
+ msg = message();
+ setDelayedReply(true);
+ QMetaObject::invokeMethod(this, "process", Qt::QueuedConnection);
+ return QString();
+}
+//! [0]
diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbusinterface.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbusinterface.cpp
new file mode 100644
index 0000000000..0bcc3deff3
--- /dev/null
+++ b/src/dbus/doc/snippets/code/src_qdbus_qdbusinterface.cpp
@@ -0,0 +1,51 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+QDBusInterface remoteApp( "com.example.Calculator", "/Calculator/Operations",
+ "org.mathematics.RPNCalculator" );
+remoteApp.call( "PushOperand", 2 );
+remoteApp.call( "PushOperand", 2 );
+remoteApp.call( "ExecuteOperation", "+" );
+QDBusReply<int> reply = remoteApp.call( "PopOperand" );
+
+if ( reply.isValid() )
+ printf( "%d", reply.value() ); // prints 4
+//! [0]
diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbusmetatype.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbusmetatype.cpp
new file mode 100644
index 0000000000..6c12464b78
--- /dev/null
+++ b/src/dbus/doc/snippets/code/src_qdbus_qdbusmetatype.cpp
@@ -0,0 +1,44 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+#include <QDBusMetaType>
+qDBusRegisterMetaType<MyClass>();
+//! [0]
diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingcall.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingcall.cpp
new file mode 100644
index 0000000000..a5d46dccfe
--- /dev/null
+++ b/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingcall.cpp
@@ -0,0 +1,65 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+{
+//! [0]
+ QDBusPendingCall async = iface->asyncCall("RemoteMethod", value1, value2);
+ QDBusPendingCallWatcher *watcher = new QDBusPendingCallWatcher(async, this);
+
+ QObject::connect(watcher, SIGNAL(finished(QDBusPendingCallWatcher*)),
+ this, SLOT(callFinishedSlot(QDBusPendingCallWatcher*)));
+//! [0]
+
+}
+
+//! [1]
+void MyClass::callFinishedSlot(QDBusPendingCallWatcher *call)
+{
+ QDBusPendingReply<QString, QByteArray> reply = *call;
+ if (reply.isError()) {
+ showError();
+ } else {
+ QString text = reply.argumentAt<0>();
+ QByteArray data = reply.argumentAt<1>();
+ showReply(text, data);
+ }
+ call->deleteLater();
+}
+//! [1]
diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingreply.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingreply.cpp
new file mode 100644
index 0000000000..eac955a798
--- /dev/null
+++ b/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingreply.cpp
@@ -0,0 +1,63 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+{
+//! [0]
+ QDBusPendingReply<QString> reply = interface->asyncCall("RemoteMethod");
+ reply.waitForFinished();
+ if (reply.isError())
+ // call failed. Show an error condition.
+ showError(reply.error());
+ else
+ // use the returned value
+ useValue(reply.value());
+//! [0]
+
+//! [2]
+ QDBusPendingReply<bool, QString> reply = interface->asyncCall("RemoteMethod");
+ reply.waitForFinished();
+ if (!reply.isError()) {
+ if (reply.argumentAt<0>())
+ showSuccess(reply.argumentAt<1>());
+ else
+ showFailure(reply.argumentAt<1>());
+ }
+//! [2]
+}
diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbusreply.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbusreply.cpp
new file mode 100644
index 0000000000..326f395058
--- /dev/null
+++ b/src/dbus/doc/snippets/code/src_qdbus_qdbusreply.cpp
@@ -0,0 +1,54 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+QDBusReply<QString> reply = interface->call("RemoteMethod");
+if (reply.isValid())
+ // use the returned value
+ useValue(reply.value());
+else
+ // call failed. Show an error condition.
+ showError(reply.error());
+//! [0]
+
+
+//! [1]
+QString reply = interface->call("RemoteMethod");
+//! [1]
diff --git a/src/dbus/doc/snippets/qdbusextratypes/qdbusextratypes.cpp b/src/dbus/doc/snippets/qdbusextratypes/qdbusextratypes.cpp
new file mode 100644
index 0000000000..69c1d05cd5
--- /dev/null
+++ b/src/dbus/doc/snippets/qdbusextratypes/qdbusextratypes.cpp
@@ -0,0 +1,66 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+** * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+** * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include <QtCore>
+#include <QtDBus>
+
+static QVariant callMyDBusFunction() { return QVariant(); }
+
+int main()
+{
+ QDBusMessage myDBusMessage;
+
+//! [0]
+ QList<QVariant> arguments;
+ arguments << QVariant(42) << QVariant::fromValue(QDBusVariant(43)) << QVariant("hello");
+ myDBusMessage.setArguments(arguments);
+//! [0]
+
+//! [1]
+ // call a D-Bus function that returns a D-Bus variant
+ QVariant v = callMyDBusFunction();
+ // retrieve the D-Bus variant
+ QDBusVariant dbusVariant = qvariant_cast<QDBusVariant>(v);
+ // retrieve the actual value stored in the D-Bus variant
+ QVariant result = dbusVariant.variant();
+//! [1]
+
+ return 0;
+}
diff --git a/src/dbus/doc/src/dbus-adaptors.qdoc b/src/dbus/doc/src/dbus-adaptors.qdoc
new file mode 100644
index 0000000000..a41c874c8c
--- /dev/null
+++ b/src/dbus/doc/src/dbus-adaptors.qdoc
@@ -0,0 +1,481 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page usingadaptors.html
+ \title Using QtDBus Adaptors
+ \brief How to create and use DBus adaptors in Qt.
+
+ \ingroup best-practices
+
+ Adaptors are special classes that are attached to any QObject-derived class
+ and provide the interface to the external world using D-Bus. Adaptors are
+ intended to be lightweight classes whose main purpose is to relay calls to
+ and from the real object, possibly validating or converting the input from
+ the external world and, thus, protecting the real object.
+
+ Unlike multiple inheritance, adaptors can be added at any time to any object
+ (but not removed), which allows for greater flexibility when exporting
+ existing classes. Another advantage of adaptors is to provide similar but not
+ identical functionality in methods of the same name in different interfaces,
+ a case which can be quite common when adding a new version of a standard
+ interface to an object.
+
+ In order to use an adaptor, one must create a class which inherits
+ QDBusAbstractAdaptor. Since that is a standard QObject-derived class, the
+ Q_OBJECT macro must appear in the declaration and the source file must be
+ processed with the \l {moc} tool. The class must also contain one
+ Q_CLASSINFO entry with the \c {"D-Bus Interface"} name, declaring which
+ interface it is exporting. Only one entry per class is supported.
+
+ Any public slot in the class will be accessible through the bus over messages
+ of the MethodCall type. (See \l {Declaring Slots in D-Bus Adaptors} for more
+ information). Signals in the class will be automatically relayed over D-Bus.
+ However, not all types are allowed signals or slots' parameter lists: see
+ \l {The QtDBus Type System} for more information.
+
+ Also, any property declared with Q_PROPERTY will be automatically exposed
+ over the Properties interface on D-Bus. Since the QObject property system
+ does not allow for non-readable properties, it is not possible to declare
+ write-only properties using adaptors.
+
+ More information:
+ \list
+ \li \l{Declaring Slots in D-Bus Adaptors}
+ \li \l{Declaring Signals in D-Bus Adaptors}
+ \li \l{The QtDBus Type System}
+ \li \l{D-Bus Adaptor Example}
+ \endlist
+
+ \sa QDBusAbstractAdaptor
+*/
+
+/*!
+ \page qdbusadaptorexample.html
+ \title D-Bus Adaptor Example
+
+ \previouspage The QtDBus Type System
+ \contentspage Using QtDBus Adaptors
+
+ The following example code shows how a D-Bus interface can be implemented
+ using an adaptor.
+
+ A sample usage of QDBusAbstractAdaptor is as follows:
+ \snippet code/doc_src_qdbusadaptors.cpp 0
+
+ The code above would create an interface that could be represented more or less in the following
+ canonical representation:
+ \snippet code/doc_src_qdbusadaptors.cpp 1
+
+ This adaptor could be used in the application's main function as follows
+ \snippet code/doc_src_qdbusadaptors.cpp 2
+
+ Break-down analysis:
+ \tableofcontents
+
+ \section1 The header
+
+ The header of the example is:
+ \snippet code/doc_src_qdbusadaptors.cpp 3
+
+ The code does the following:
+ \list
+ \li it declares the adaptor MainApplicationAdaptor, which descends from QDBusAbstractAdaptor
+ \li it declares the Qt meta-object data using the Q_OBJECT macro
+ \li it declares the name of the D-Bus interface it implements.
+ \endlist
+
+ \section1 The properties
+
+ The properties are declared as follows:
+ \snippet code/doc_src_qdbusadaptors.cpp 4
+
+ And are implemented as follows:
+ \snippet code/doc_src_qdbusadaptors.cpp 5
+
+ The code declares three properties: one of them is a read-write property called "caption" of
+ string type. The other two are read-only, also of the string type.
+
+ The properties organizationName and organizationDomain are simple relays of the app object's
+ organizationName and organizationDomain properties. However, the caption property requires
+ verifying if the application has a main window associated with it: if there isn't any, the
+ caption property is empty. Note how it is possible to access data defined in other objects
+ through the getter/setter functions.
+
+ \section1 The constructor
+
+ The constructor:
+ \snippet code/doc_src_qdbusadaptors.cpp 6
+
+ The constructor does the following:
+ \list
+ \li it initialises its base class (QDBusAbstractAdaptor) with the parent object it is related to.
+ \li it stores the app pointer in a member variable. Note that it would be possible to access the
+ same object using the QDBusAbstractAdaptor::object() function, but it would be necessary to
+ use \a static_cast<> to properly access the methods in QApplication that are not part of
+ QObject.
+ \li it connects the application's signal \a aboutToQuit to its own signal \a aboutToQuit.
+ \li it connects the application's signal \a focusChanged to a private slot to do some further
+ processing before emitting a D-Bus signal.
+ \endlist
+
+ Note that there is no destructor in the example. An eventual destructor could be used to emit
+ one last signal before the object is destroyed, for instance.
+
+ \section1 Slots/methods
+
+ The public slots in the example (which will be exported as D-Bus methods) are the following:
+ \snippet code/doc_src_qdbusadaptors.cpp 7
+
+ This snippet of code defines 4 methods with different properties each:
+ \list 1
+ \li \c quit: this method takes no parameters and is defined to be asynchronous. That is, callers
+ are expected to use "fire-and-forget" mechanism when calling this method, since it provides no
+ useful reply. This is represented in D-Bus by the use of the
+ org.freedesktop.DBus.Method.NoReply annotation. See \l Q_NOREPLY for more information on
+ asynchronous methods
+
+ \li \c reparseConfiguration: this simple method, with no input or output arguments simply relays
+ the call to the application's reparseConfiguration member function.
+
+ \li \c mainWindowObject: this method takes no input parameter, but returns one string output
+ argument, containing the path to the main window object (if the application has a main
+ window), or an empty string if it has no main window. Note that this method could have also
+ been written: void mainWindowObject(QString &path).
+
+ \li \c setSessionManagement: this method takes one input argument (a boolean) and, depending on
+ its value, it calls one function or another in the application.
+ \endlist
+
+ See also: \l Q_NOREPLY.
+
+ \section1 Signals
+
+ The signals in this example are defined as follows:
+ \snippet code/doc_src_qdbusadaptors.cpp 8
+
+ However, signal definition isn't enough: signals have to be emitted. One simple way of emitting
+ signals is to connect another signal to them, so that Qt's signal handling system chains them
+ automatically. This is what is done for the \a aboutToQuit signal.
+
+ When this is the case, one can use the QDBusAbstractAdaptor::setAutoRelaySignals to
+ automatically connect every signal from the real object to the adaptor.
+
+ When simple signal-to-signal connection isn't enough, one can use a private slot do do some
+ work. This is what was done for the mainWindowHasFocus signal:
+ \snippet code/doc_src_qdbusadaptors.cpp 9
+
+ This private slot (which will not be exported as a method via D-Bus) was connected to the
+ \c focusChanged signal in the adaptor's constructor. It is therefore able to shape the
+ application's signal into what the interface expects it to be.
+*/
+
+/*!
+ \page qdbusdeclaringslots.html
+ \title Declaring Slots in D-Bus Adaptors
+
+ \contentspage Using QtDBus Adaptors
+ \nextpage Declaring Signals in D-Bus Adaptors
+
+ Slots in D-Bus adaptors are declared just like normal, public slots, but their
+ parameters must follow certain rules (see \l{The QtDBus Type System} for more
+ information). Slots whose parameters do not follow those rules or that are not
+ public will not be accessible via D-Bus.
+
+ Slots can have one parameter of type \c{const QDBusMessage &}, which must
+ appear at the end of the input parameter list, before any output parameters.
+ This parameter, if present, will be initialized with a copy of the
+ current message being processed, which allows the callee to obtain
+ information about the caller, such as its connection name.
+
+ Slots can be of three kinds:
+ \list 1
+ \li Asynchronous
+ \li Input-only
+ \li Input-and-output
+ \endlist
+
+ \section1 Asynchronous Slots
+ Asynchronous slots are those that do not normally return any reply to the
+ caller. For that reason, they cannot take any output parameters. In most
+ cases, by the time the first line of the slot is run, the caller function
+ has already resumed working.
+
+ However, slots must not rely on that behavior. Scheduling and message-dispatching
+ issues could change the order in which the slot is run. Code intending to
+ synchronize with the caller should provide its own method of synchronization.
+
+ Asynchronous slots are marked by the keyword \l Q_NOREPLY in the method
+ signature, before the \c void return type and the slot name. (See the
+ \c quit() slot in the \l{D-Bus Adaptor Example}).
+
+ \section1 Input-Only Slots
+
+ Input-only slots are normal slots that take parameters passed by value or
+ by constant reference. However, unlike asynchronous slots, the caller is
+ usually waiting for completion of the callee before resuming operation.
+ Therefore, non-asynchronous slots should not block or should state it its
+ documentation that they may do so.
+
+ Input-only slots have no special marking in their signature, except that
+ they take only parameters passed by value or by constant reference.
+ Optionally, slots can take a QDBusMessage parameter as a last parameter,
+ which can be used to perform additional analysis of the method call message.
+
+ \section1 Input and Output Slots
+
+ Like input-only slots, input-and-output slots are those that the caller is
+ waiting for a reply. Unlike input-only ones, though, this reply will contain
+ data. Slots that output data may contain non-constant references and may
+ return a value as well. However, the output parameters must all appear at
+ the end of the argument list and may not have input arguments interleaved.
+ Optionally, a QDBusMessage argument may appear between the input and the
+ output arguments.
+
+ \section1 Automatic Replies
+
+ Method replies are generated automatically with the contents of the output
+ parameters (if there were any) by the QtDBus implementation. Slots need not
+ worry about constructing proper QDBusMessage objects and sending them over
+ the connection.
+
+ However, the possibility of doing so remains there. Should the slot find out
+ it needs to send a special reply or even an error, it can do so by using
+ QDBusMessage::createReply() or QDBusMessage::createErrorReply() on the
+ QDBusMessage parameter and send it with QDBusConnection::send(). The
+ QtDBus implementation will not generate any reply if the slot did so.
+
+ \warning When a caller places a method call and waits for a reply, it will
+ only wait for a limited amount of time. Slots intending to take a long time
+ to complete should make that fact clear in documentation so that callers
+ properly set higher timeouts.
+
+ \section1 Delayed Replies
+
+ In some circumstances, the called slot may not be able to process
+ the request immediately. This is frequently the case when the
+ request involves an I/O or networking operation which may block.
+
+ If this is the case, the slot should return control to the
+ application's main loop to avoid freezing the user interface, and
+ resume the process later. To accomplish this, it should make use
+ of the extra \c QDBusMessage parameter at the end of the input
+ parameter list and request a delayed reply.
+
+ We do this by writing a slot that stores the request data in a
+ persistent structure, indicating to the caller using
+ \l{QDBusMessage::setDelayedReply()}{QDBusMessage::setDelayedReply(true)}
+ that the response will be sent later.
+
+ \snippet code/doc_src_qdbusadaptors.cpp 10
+
+ The use of
+ \l{QDBusConnection::send()}{QDBusConnection::sessionBus().send(data->reply)}
+ is needed to explicitly inform the caller that the response will be delayed.
+ In this case, the return value is unimportant; we return an arbitrary value
+ to satisfy the compiler.
+
+ When the request is processed and a reply is available, it should be sent
+ using the \c QDBusMessage object that was obtained. In our example, the
+ reply code could be something as follows:
+
+ \snippet code/doc_src_qdbusadaptors.cpp 11
+
+ As can be seen in the example, when a delayed reply is in place,
+ the return value(s) from the slot will be ignored by QtDBus. They
+ are used only to determine the slot's signature when communicating
+ the adaptor's description to remote applications, or in case the
+ code in the slot decides not to use a delayed reply.
+
+ The delayed reply itself is requested from QtDBus by calling
+ QDBusMessage::reply() on the original message. It then becomes the
+ resposibility of the called code to eventually send a reply to the
+ caller.
+
+ \warning When a caller places a method call and waits for a reply, it will
+ only wait for a limited amount of time. Slots intending to take a long time
+ to complete should make that fact clear in documentation so that callers
+ properly set higher timeouts.
+
+ \sa {Using QtDBus Adaptors}, {Declaring Signals in D-Bus Adaptors},
+ {The QtDBus Type System}, QDBusConnection, QDBusMessage
+*/
+
+/*!
+ \page qdbusdeclaringsignals.html
+ \title Declaring Signals in D-Bus Adaptors
+
+ \previouspage Declaring Slots in D-Bus Adaptors
+ \contentspage Using QtDBus Adaptors
+ \nextpage The QtDBus Type System
+
+ Any signal in a class derived from QDBusAbstractAdaptor will be automatically
+ relayed into D-Bus, provided that the signal's parameters conform to certain
+ rules (see \l{The QtDBus Type System} for more information). No special code
+ is necessary to make this relay.
+
+ However, signals must still be emitted. The easiest way to emit an adaptor
+ signal is to connect another signal to it, so that Qt's signals and slots
+ mechanism automatically emits the adaptor signal, too. This can be done in
+ the adaptor's constructor, as has been done in the
+ \l{D-Bus Adaptor Example}{D-Bus Adaptor example}.
+
+ The QDBusAbstractAdaptor::setAutoRelaySignals() convenience function can also
+ be used to make and break connections between signals in the real object and
+ the corresponding signals in the adaptor. It will inspect the list of signals
+ in both classes and connect those whose parameters match exactly.
+
+ \sa {Using QtDBus Adaptors},
+ {Declaring Slots in D-Bus Adaptors},
+ {The QtDBus Type System}, QDBusAbstractAdaptor
+*/
+
+/*!
+ \page qdbustypesystem.html
+ \title The QtDBus Type System
+
+ \previouspage Declaring Signals in D-Bus Adaptors
+ \contentspage Using QtDBus Adaptors
+ \nextpage D-Bus Adaptor Example
+
+ D-Bus has an extensible type system based on a few primitives and
+ composition of the primitives in arrays and structures. QtDBus
+ implements the interface to that type system through the
+ QDBusArgument class, allowing user programs to send and receive
+ practically every C++ type over the bus.
+
+ \section1 Primitive Types
+
+ The primitive types are supported natively by QDBusArgument and
+ need no special customization to be sent or received. They are
+ listed below, along with the C++ class they relate to:
+
+ \table
+ \header
+ \li Qt type
+ \li D-Bus equivalent type
+ \row
+ \li uchar
+ \li BYTE
+ \row
+ \li bool
+ \li BOOLEAN
+ \row
+ \li short
+ \li INT16
+ \row
+ \li ushort
+ \li UINT16
+ \row
+ \li int
+ \li INT32
+ \row
+ \li uint
+ \li UINT32
+ \row
+ \li qlonglong
+ \li INT64
+ \row
+ \li qulonglong
+ \li UINT64
+ \row
+ \li double
+ \li DOUBLE
+ \row
+ \li QString
+ \li STRING
+ \row
+ \li QDBusVariant
+ \li VARIANT
+ \row
+ \li QDBusObjectPath
+ \li OBJECT_PATH
+ \row
+ \li QDBusSignature
+ \li SIGNATURE
+ \endtable
+
+ Aside from the primitive types, QDBusArgument also supports two
+ non-primitive types natively, due to their widespread use in Qt
+ applications: QStringList and QByteArray.
+
+ \section1 Compound Types
+
+ D-Bus specifies three types of aggregations of primitive types
+ that allow one to create compound types. They are \c ARRAY, \c
+ STRUCT and maps/dictionaries.
+
+ Arrays are sets of zero or more elements of the same type, while
+ structures are a set of a fixed number of elements, each of any
+ type. Maps or dictionaries are implemented as arrays of a pair of
+ elements, so there can be zero or more elements in one map.
+
+ \section1 Extending the Type System
+
+ In order to use one's own type with QtDBus, the type has to be
+ declared as a Qt meta-type with the Q_DECLARE_METATYPE() macro and
+ registered with the qDBusRegisterMetaType() function. The
+ streaming operators \c{operator>>} and \c{operator<<} will be
+ automatically found by the registration system.
+
+ QtDBus provides template specializations for arrays and maps for
+ use with Qt's \l{Container classes}{container classes}, such as
+ QMap and QList, so it is not necessary to write the streaming
+ operator functions for those. For other types, and specially for
+ types implementing structures, the operators have to be explicitly
+ implemented.
+
+ See the documentation for QDBusArgument for examples for
+ structures, arrays and maps.
+
+ \section1 The Type System in Use
+
+ All of the QtDBus types (primitives and user-defined alike) can be
+ used to send and receive messages of all types over the bus.
+
+ \warning You may not use any type that is not on the list above,
+ including \a typedefs to the types listed. This also includes
+ QList<QVariant> and QMap<QString,QVariant>.
+*/
+
+/*!
+ \macro Q_NOREPLY
+ \relates QDBusAbstractAdaptor
+ \since 4.2
+
+ The Q_NOREPLY macro can be used to mark a method to be called and not wait for it to finish
+ processing before returning from QDBusInterface::call(). The called method cannot return any
+ output arguments and, if it does, any such arguments will be discarded.
+
+ You can use this macro in your own adaptors by placing it before your method's return value
+ (which must be "void") in the class declaration, as shown in the example:
+ \snippet code/doc_src_qdbusadaptors.cpp 12
+
+ Its presence in the method implementation (outside the class declaration) is optional.
+
+ \sa {Using QtDBus Adaptors}
+*/
diff --git a/src/dbus/doc/src/dbus-intro.qdoc b/src/dbus/doc/src/dbus-intro.qdoc
new file mode 100644
index 0000000000..b3cf29e129
--- /dev/null
+++ b/src/dbus/doc/src/dbus-intro.qdoc
@@ -0,0 +1,215 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $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 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 \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 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 QtDBus Adaptors}
+ \li \l{The QtDBus Type System}
+ \li \l{QtDBus XML compiler (qdbusxml2cpp)}
+ \endlist
+*/
diff --git a/src/dbus/doc/src/qdbusxml2cpp.qdoc b/src/dbus/doc/src/qdbusxml2cpp.qdoc
new file mode 100644
index 0000000000..996b5c7820
--- /dev/null
+++ b/src/dbus/doc/src/qdbusxml2cpp.qdoc
@@ -0,0 +1,49 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page qdbusxml2cpp.html
+ \title QtDBus XML compiler (qdbusxml2cpp)
+ \keyword qdbusxml2cpp
+
+ The QtDBus XML compiler is a tool that can be used to parse interface descriptions and produce
+ static code representing those interfaces, which can then be used to make calls to remote
+ objects or implement said interfaces.
+
+ \c qdbusxml2cpp has two modes of operation, that correspond to the two possible outputs it can
+ produce: the interface (proxy) class or the adaptor class. The latter consists of both a C++
+ header and a source file, which are meant to be edited and adapted to your needs.
+
+ The \c qdbusxml2cpp tool is not meant to be run every time you compile your
+ application. Instead, it's meant to be used when developing the code or when the interface
+ changes.
+
+ The adaptor classes generated by \c qdbusxml2cpp are just a skeleton that must be completed. It
+ generates, by default, calls to slots with the same name on the object the adaptor is attached
+ to. However, you may modify those slots or the property accessor functions to suit your needs.
+*/
+
diff --git a/src/dbus/doc/src/qtdbus.qdoc b/src/dbus/doc/src/qtdbus.qdoc
new file mode 100644
index 0000000000..739502e1fc
--- /dev/null
+++ b/src/dbus/doc/src/qtdbus.qdoc
@@ -0,0 +1,65 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \module QtDBus
+ \title QtDBus module
+ \ingroup modules
+
+ \keyword QtDBus
+ \target The QDBus compiler
+
+ \brief The QtDBus module is a Unix-only library that you can use
+ to perform Inter-Process Communication using the \l{D-Bus} protocol.
+
+ Applications using the QtDBus module can provide services to
+ other, remote applications by exporting objects, as well as use
+ services exported by those applications by placing calls and
+ accessing properties.
+
+ The QtDBus module provides an interface that extends the Qt \l
+ {signalsandslots.html}{Signals and Slots} mechanism, allowing one
+ to connect to a signal emitted remotely as well as to connect a
+ local signal to remote slot.
+
+ To use this module, use the following code in your application:
+
+ \snippet code/doc_src_qtdbus.cpp 0
+
+ If you're using qmake to build your application, you can add this
+ line to your .pro file to make it link against the QtDBus
+ libraries:
+
+ \snippet code/doc_src_qtdbus.pro 1
+
+ \note The source code for this module is located in the \c{src/qdbus}
+ directory. When installing Qt from source, this module is built when Qt's
+ tools are built.
+
+ See the \l {D-Bus} page for detailed information on
+ how to use this module.
+*/
diff --git a/src/dbus/qdbusabstractinterface.cpp b/src/dbus/qdbusabstractinterface.cpp
index ea32e6ead6..51b100839c 100644
--- a/src/dbus/qdbusabstractinterface.cpp
+++ b/src/dbus/qdbusabstractinterface.cpp
@@ -650,7 +650,7 @@ void QDBusAbstractInterface::internalPropSet(const char *propname, const QVarian
It can be used the following way:
- \snippet doc/src/snippets/code/src_qdbus_qdbusabstractinterface.cpp 0
+ \snippet code/src_qdbus_qdbusabstractinterface.cpp 0
This example illustrates function calling with 0, 1 and 2 parameters and illustrates different
parameter types passed in each (the first call to \c "ProcessWorkUnicode" will contain one
@@ -742,7 +742,7 @@ QDBusMessage QDBusAbstractInterface::call(QDBus::CallMode mode, const QString &m
It can be used the following way:
- \snippet doc/src/snippets/code/src_qdbus_qdbusabstractinterface.cpp 1
+ \snippet code/src_qdbus_qdbusabstractinterface.cpp 1
This example illustrates function calling with 0, 1 and 2 parameters and illustrates different
parameter types passed in each (the first call to \c "ProcessWorkUnicode" will contain one
diff --git a/src/dbus/qdbusargument.cpp b/src/dbus/qdbusargument.cpp
index 6e6e676dae..0969aef83f 100644
--- a/src/dbus/qdbusargument.cpp
+++ b/src/dbus/qdbusargument.cpp
@@ -190,13 +190,13 @@ bool QDBusArgumentPrivate::checkReadAndDetach(QDBusArgumentPrivate *&d)
integer and a string can be constructed using the \l
{qdbustypesystem.html}{QtDBus type system}:
- \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 0
+ \snippet code/src_qdbus_qdbusargument.cpp 0
The type has to be registered with qDBusRegisterMetaType() before
it can be used with QDBusArgument. Therefore, somewhere in your
program, you should add the following code:
- \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 1
+ \snippet code/src_qdbus_qdbusargument.cpp 1
Once registered, a type can be used in outgoing method calls
(placed with QDBusAbstractInterface::call()), signal emissions
@@ -275,11 +275,11 @@ bool QDBusArgumentPrivate::checkReadAndDetach(QDBusArgumentPrivate *&d)
Attempts to demarshall the contents of \a argument into the type
\c{T}. For example:
- \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 2
+ \snippet code/src_qdbus_qdbusargument.cpp 2
Note that it is equivalent to the following:
- \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 3
+ \snippet code/src_qdbus_qdbusargument.cpp 3
*/
/*!
@@ -817,12 +817,12 @@ const QDBusArgument &QDBusArgument::operator>>(QByteArray &arg) const
This function is used usually in \c{operator<<} streaming
operators, as in the following example:
- \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 4
+ \snippet code/src_qdbus_qdbusargument.cpp 4
Structures can contain other structures, so the following code is
also valid:
- \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 5
+ \snippet code/src_qdbus_qdbusargument.cpp 5
\sa endStructure(), beginArray(), beginMap()
*/
@@ -850,7 +850,7 @@ void QDBusArgument::endStructure()
This function is used usually in \c{operator<<} streaming
operators, as in the following example:
- \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 6
+ \snippet code/src_qdbus_qdbusargument.cpp 6
If the type you want to marshall is a QList, QVector or any of the
Qt's \l {Container Classes} that take one template parameter,
@@ -889,7 +889,7 @@ void QDBusArgument::endArray()
This function is used usually in \c{operator<<} streaming
operators, as in the following example:
- \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 7
+ \snippet code/src_qdbus_qdbusargument.cpp 7
If the type you want to marshall is a QMap or QHash, you need not
declare an \c{operator<<} function for it, since QtDBus provides
@@ -948,7 +948,7 @@ void QDBusArgument::endMapEntry()
This function is used usually in \c{operator>>} streaming
operators, as in the following example:
- \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 8
+ \snippet code/src_qdbus_qdbusargument.cpp 8
\sa endStructure(), beginArray(), beginMap()
*/
@@ -977,7 +977,7 @@ void QDBusArgument::endStructure() const
This function is used usually in \c{operator>>} streaming
operators, as in the following example:
- \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 9
+ \snippet code/src_qdbus_qdbusargument.cpp 9
If the type you want to demarshall is a QList, QVector or any of the
Qt's \l {Container Classes} that take one template parameter, you
@@ -1013,7 +1013,7 @@ void QDBusArgument::endArray() const
This function is used usually in \c{operator>>} streaming
operators, as in the following example:
- \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 10
+ \snippet code/src_qdbus_qdbusargument.cpp 10
If the type you want to demarshall is a QMap or QHash, you need not
declare an \c{operator>>} function for it, since QtDBus provides
diff --git a/src/dbus/qdbuscontext.cpp b/src/dbus/qdbuscontext.cpp
index cc987d1410..0a13fce9ee 100644
--- a/src/dbus/qdbuscontext.cpp
+++ b/src/dbus/qdbuscontext.cpp
@@ -90,7 +90,7 @@ QDBusContextPrivate *QDBusContextPrivate::set(QObject *obj, QDBusContextPrivate
exported using QDBusConnection::registerObject(). The following
example illustrates the usage:
- \snippet doc/src/snippets/code/src_qdbus_qdbuscontext.cpp 0
+ \snippet code/src_qdbus_qdbuscontext.cpp 0
The example illustrates the two typical uses, that of sending
error replies and that of delayed replies.
diff --git a/src/dbus/qdbusextratypes.cpp b/src/dbus/qdbusextratypes.cpp
index 4438e3c65f..4b2730c44a 100644
--- a/src/dbus/qdbusextratypes.cpp
+++ b/src/dbus/qdbusextratypes.cpp
@@ -73,11 +73,11 @@ void QDBusSignature::doCheck()
A D-Bus function that takes an integer, a D-Bus variant and a string as parameters
can be called with the following argument list (see QDBusMessage::setArguments()):
- \snippet doc/src/snippets/qdbusextratypes/qdbusextratypes.cpp 0
+ \snippet qdbusextratypes/qdbusextratypes.cpp 0
When a D-Bus function returns a D-Bus variant, it can be retrieved as follows:
- \snippet doc/src/snippets/qdbusextratypes/qdbusextratypes.cpp 1
+ \snippet qdbusextratypes/qdbusextratypes.cpp 1
The QVariant within a QDBusVariant is required to distinguish between a normal
D-Bus value and a value within a D-Bus variant.
diff --git a/src/dbus/qdbusinterface.cpp b/src/dbus/qdbusinterface.cpp
index f6a84b9980..844b0b7a4c 100644
--- a/src/dbus/qdbusinterface.cpp
+++ b/src/dbus/qdbusinterface.cpp
@@ -196,7 +196,7 @@ QDBusInterfacePrivate::~QDBusInterfacePrivate()
mathematical operation of \tt{"2 + 2"} in a remote application
called \c com.example.Calculator, accessed via the session bus.
- \snippet doc/src/snippets/code/src_qdbus_qdbusinterface.cpp 0
+ \snippet code/src_qdbus_qdbusinterface.cpp 0
\sa {QtDBus XML compiler (qdbusxml2cpp)}
*/
diff --git a/src/dbus/qdbusmetatype.cpp b/src/dbus/qdbusmetatype.cpp
index 0359b4da35..03cad1ee63 100644
--- a/src/dbus/qdbusmetatype.cpp
+++ b/src/dbus/qdbusmetatype.cpp
@@ -200,7 +200,7 @@ Q_GLOBAL_STATIC(QReadWriteLock, customTypesLock)
Q_DECLARE_METATYPE() macro, and then registered as in the
following example:
- \snippet doc/src/snippets/code/src_qdbus_qdbusmetatype.cpp 0
+ \snippet code/src_qdbus_qdbusmetatype.cpp 0
If \c{T} isn't a type derived from one of
Qt's \l{container classes}, the \c{operator<<} and
diff --git a/src/dbus/qdbuspendingcall.cpp b/src/dbus/qdbuspendingcall.cpp
index 3d5dc421d7..9ae68c7abc 100644
--- a/src/dbus/qdbuspendingcall.cpp
+++ b/src/dbus/qdbuspendingcall.cpp
@@ -97,7 +97,7 @@ QT_BEGIN_NAMESPACE
It is usually used like the following example:
- \snippet doc/src/snippets/code/src.qdbus.qdbuspendingcall.cpp 0
+ \snippet code/src_qdbus_qdbuspendingcall.cpp 0
Note that it is not necessary to keep the original QDBusPendingCall
object around since QDBusPendingCallWatcher inherits from that class
@@ -106,7 +106,7 @@ QT_BEGIN_NAMESPACE
The slot connected to by the above code could be something similar
to the following:
- \snippet doc/src/snippets/code/src.qdbus.qdbuspendingcall.cpp 1
+ \snippet code/src_qdbus_qdbuspendingcall.cpp 1
Note the use of QDBusPendingReply to validate the argument types in
the reply. If the reply did not contain exactly two arguments
diff --git a/src/dbus/qdbuspendingreply.cpp b/src/dbus/qdbuspendingreply.cpp
index b9694ca205..2fd219260d 100644
--- a/src/dbus/qdbuspendingreply.cpp
+++ b/src/dbus/qdbuspendingreply.cpp
@@ -69,22 +69,22 @@
Where with QDBusReply you would write:
- \snippet doc/src/snippets/code/src_qdbus_qdbusreply.cpp 0
+ \snippet code/src_qdbus_qdbusreply.cpp 0
with QDBusPendingReply, the equivalent code (including the blocking
wait for the reply) would be:
- \snippet doc/src/snippets/code/src.qdbus.qdbuspendingreply.cpp 0
+ \snippet code/src_qdbus_qdbuspendingreply.cpp 0
For method calls that have more than one output argument, with
QDBusReply, you would write:
- \snippet doc/src/snippets/code/src_qdbus_qdbusreply.cpp 1
+ \snippet code/src_qdbus_qdbusreply.cpp 1
whereas with QDBusPendingReply, all of the output arguments should
be template parameters:
- \snippet doc/src/snippets/code/src.qdbus.qdbuspendingreply.cpp 2
+ \snippet code/src_qdbus_qdbuspendingreply.cpp 2
QDBusPendingReply objects can be associated with
QDBusPendingCallWatcher objects, which emit signals when the reply
diff --git a/src/dbus/qdbusreply.cpp b/src/dbus/qdbusreply.cpp
index c891874d98..9875329a26 100644
--- a/src/dbus/qdbusreply.cpp
+++ b/src/dbus/qdbusreply.cpp
@@ -61,10 +61,10 @@ QT_BEGIN_NAMESPACE
argument.
It can be used in the following manner:
- \snippet doc/src/snippets/code/src_qdbus_qdbusreply.cpp 0
+ \snippet code/src_qdbus_qdbusreply.cpp 0
If the remote method call cannot fail, you can skip the error checking:
- \snippet doc/src/snippets/code/src_qdbus_qdbusreply.cpp 1
+ \snippet code/src_qdbus_qdbusreply.cpp 1
However, if it does fail under those conditions, the value returned by QDBusReply::value() is
a default-constructed value. It may be indistinguishable from a valid return value.