From 3b8e6027c2f79bde70f9415f0757df073ef75702 Mon Sep 17 00:00:00 2001 From: Casper van Donderen Date: Mon, 7 May 2012 14:03:02 +0200 Subject: Doc: Modularize QtDBus documentation and add missing file to QtNetwork. This change moves the snippets and images to the modularized directories. Change-Id: Idacff866735d00b048d65318bc4c3ee1dfa16310 Reviewed-by: Marius Storm-Olsen --- src/dbus/doc/qtdbus.qdocconf | 92 ++++ .../doc/snippets/code/doc_src_introtodbus.qdoc | 48 ++ .../doc/snippets/code/doc_src_qdbusadaptors.cpp | 293 +++++++++++++ src/dbus/doc/snippets/code/doc_src_qtdbus.cpp | 43 ++ src/dbus/doc/snippets/code/doc_src_qtdbus.pro | 43 ++ .../code/src_qdbus_qdbusabstractinterface.cpp | 60 +++ .../doc/snippets/code/src_qdbus_qdbusargument.cpp | 191 ++++++++ .../doc/snippets/code/src_qdbus_qdbuscontext.cpp | 72 +++ .../doc/snippets/code/src_qdbus_qdbusinterface.cpp | 51 +++ .../doc/snippets/code/src_qdbus_qdbusmetatype.cpp | 44 ++ .../snippets/code/src_qdbus_qdbuspendingcall.cpp | 65 +++ .../snippets/code/src_qdbus_qdbuspendingreply.cpp | 63 +++ .../doc/snippets/code/src_qdbus_qdbusreply.cpp | 54 +++ .../snippets/qdbusextratypes/qdbusextratypes.cpp | 66 +++ src/dbus/doc/src/dbus-adaptors.qdoc | 481 +++++++++++++++++++++ src/dbus/doc/src/dbus-intro.qdoc | 215 +++++++++ src/dbus/doc/src/qdbusxml2cpp.qdoc | 49 +++ src/dbus/doc/src/qtdbus.qdoc | 65 +++ 18 files changed, 1995 insertions(+) create mode 100644 src/dbus/doc/qtdbus.qdocconf create mode 100644 src/dbus/doc/snippets/code/doc_src_introtodbus.qdoc create mode 100644 src/dbus/doc/snippets/code/doc_src_qdbusadaptors.cpp create mode 100644 src/dbus/doc/snippets/code/doc_src_qtdbus.cpp create mode 100644 src/dbus/doc/snippets/code/doc_src_qtdbus.pro create mode 100644 src/dbus/doc/snippets/code/src_qdbus_qdbusabstractinterface.cpp create mode 100644 src/dbus/doc/snippets/code/src_qdbus_qdbusargument.cpp create mode 100644 src/dbus/doc/snippets/code/src_qdbus_qdbuscontext.cpp create mode 100644 src/dbus/doc/snippets/code/src_qdbus_qdbusinterface.cpp create mode 100644 src/dbus/doc/snippets/code/src_qdbus_qdbusmetatype.cpp create mode 100644 src/dbus/doc/snippets/code/src_qdbus_qdbuspendingcall.cpp create mode 100644 src/dbus/doc/snippets/code/src_qdbus_qdbuspendingreply.cpp create mode 100644 src/dbus/doc/snippets/code/src_qdbus_qdbusreply.cpp create mode 100644 src/dbus/doc/snippets/qdbusextratypes/qdbusextratypes.cpp create mode 100644 src/dbus/doc/src/dbus-adaptors.qdoc create mode 100644 src/dbus/doc/src/dbus-intro.qdoc create mode 100644 src/dbus/doc/src/qdbusxml2cpp.qdoc create mode 100644 src/dbus/doc/src/qtdbus.qdoc (limited to 'src/dbus/doc') 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 = \ + " \n" + +HTML.endheader = \ + "\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 +//! [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..d0e6c0e837 --- /dev/null +++ b/src/dbus/doc/snippets/code/doc_src_qtdbus.pro @@ -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$ +** +****************************************************************************/ + +#! [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 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(); +//! [1] + + +//! [2] +MyType item = qdbus_cast(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() ); + 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() ); + 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 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 +qDBusRegisterMetaType(); +//! [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 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 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 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 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 +#include + +static QVariant callMyDBusFunction() { return QVariant(); } + +int main() +{ + QDBusMessage myDBusMessage; + +//! [0] + QList 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(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 and QMap. +*/ + +/*! + \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. +*/ -- cgit v1.2.3 From ee38dec6f3aff6f7f277323c5c8488d4cd385693 Mon Sep 17 00:00:00 2001 From: Marius Storm-Olsen Date: Thu, 10 May 2012 08:53:06 +0200 Subject: Don't add C-style copyright headers to qmake project files Leads to parse errors, and we don't really put copyrights into these files anyways. Change-Id: I4b423b3f4f5c4f1f5051d8e3613133c4f1df342a Reviewed-by: Casper van Donderen --- src/dbus/doc/snippets/code/doc_src_qtdbus.pro | 40 --------------------------- 1 file changed, 40 deletions(-) (limited to 'src/dbus/doc') diff --git a/src/dbus/doc/snippets/code/doc_src_qtdbus.pro b/src/dbus/doc/snippets/code/doc_src_qtdbus.pro index d0e6c0e837..a1ba138a85 100644 --- a/src/dbus/doc/snippets/code/doc_src_qtdbus.pro +++ b/src/dbus/doc/snippets/code/doc_src_qtdbus.pro @@ -1,43 +1,3 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - #! [1] QT += dbus #! [1] -- cgit v1.2.3