diff options
Diffstat (limited to 'src/dbus/doc')
27 files changed, 801 insertions, 1084 deletions
diff --git a/src/dbus/doc/qtdbus.qdocconf b/src/dbus/doc/qtdbus.qdocconf index e08bbfd94e..90ee5743ff 100644 --- a/src/dbus/doc/qtdbus.qdocconf +++ b/src/dbus/doc/qtdbus.qdocconf @@ -2,7 +2,9 @@ include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) include($QT_INSTALL_DOCS/config/exampleurl-qtbase.qdocconf) # Name of the project which must match the outputdir. Determines the .index file -project = QtDBus +project = QtDBus +description = Qt D-Bus Reference Documentation +version = $QT_VERSION # Directories in which to search for files to document and images. # By default set to the root directory of the project for sources @@ -10,8 +12,9 @@ project = QtDBus # Images should be placed in <rootdir>/dic/images and examples in # <rootdir>/examples. # Paths are relative to the location of this file. -exampledirs += ../../../examples/dbus \ - snippets +exampledirs += . \ + snippets \ + ../../../examples/dbus headerdirs += .. imagedirs += images \ @@ -24,7 +27,7 @@ examplesinstallpath = dbus tagfile = qtdbus.tags -depends += qtdoc qtcore +depends += qtcore qtdoc qmake qtcmake # The following parameters are for creating a qhp file, the qhelpgenerator # program can convert the qhp file into a qch file which can be opened in @@ -60,6 +63,8 @@ qhp.QtDBus.subprojects.examples.selectors = fake:example navigation.landingpage = "Qt D-Bus" navigation.cppclassespage = "Qt D-Bus C++ Classes" -manifestmeta.thumbnail.names = "QtDBus/D-Bus List Names Example" \ - "QtDBus/D-Bus Ping Pong Example" \ - "QtDBus/D-Bus Complex Ping Pong Example" +manifestmeta.thumbnail.names = "QtDBus/D-Bus Ping Pong" \ + "QtDBus/D-Bus Complex Ping Pong" + +# Enforce zero documentation warnings +warninglimit = 0 diff --git a/src/dbus/doc/snippets/CMakeLists.txt b/src/dbus/doc/snippets/CMakeLists.txt new file mode 100644 index 0000000000..4b4751d4fa --- /dev/null +++ b/src/dbus/doc/snippets/CMakeLists.txt @@ -0,0 +1,7 @@ +# Copyright (C) 2022 The Qt Company Ltd. +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#! [cmake_use] +find_package(Qt6 REQUIRED COMPONENTS DBus) +target_link_libraries(mytarget PRIVATE Qt6::DBus) +#! [cmake_use] diff --git a/src/dbus/doc/snippets/cmake/examples.cmake b/src/dbus/doc/snippets/cmake/examples.cmake index cb4f86844f..2bb6b63abb 100644 --- a/src/dbus/doc/snippets/cmake/examples.cmake +++ b/src/dbus/doc/snippets/cmake/examples.cmake @@ -1,3 +1,6 @@ -#! [qt5_add_dbus_adaptor] -qt5_add_dbus_adaptor(GENERATED_SOURCES org.example.chat.xml chat.h ChatMainWindow) -#! [qt5_add_dbus_adaptor] +# Copyright (C) 2022 The Qt Company Ltd. +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#! [qt_add_dbus_adaptor] +qt_add_dbus_adaptor(GENERATED_SOURCES org.example.chat.xml chat.h ChatMainWindow) +#! [qt_add_dbus_adaptor] diff --git a/src/dbus/doc/snippets/code/doc_src_introtodbus.qdoc b/src/dbus/doc/snippets/code/doc_src_introtodbus.qdoc index 5bade40a0b..61afa69790 100644 --- a/src/dbus/doc/snippets/code/doc_src_introtodbus.qdoc +++ b/src/dbus/doc/snippets/code/doc_src_introtodbus.qdoc @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, 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 The Qt Company Ltd 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$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only //! [0] org.freedesktop.DBus diff --git a/src/dbus/doc/snippets/code/doc_src_qdbusadaptors.cpp b/src/dbus/doc/snippets/code/doc_src_qdbusadaptors.cpp index f5d9fe7889..1cfb77db99 100644 --- a/src/dbus/doc/snippets/code/doc_src_qdbusadaptors.cpp +++ b/src/dbus/doc/snippets/code/doc_src_qdbusadaptors.cpp @@ -1,52 +1,11 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, 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 The Qt Company Ltd 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$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#include <QString> +#include <QDBusMessage> +#include <QDBusConnection> + +struct RequestData; +void appendRequest(RequestData *) {}; // stub //! [10] struct RequestData @@ -73,7 +32,7 @@ QString processRequest(const QString &request, const QDBusMessage &message) void sendReply(RequestData *data) { // data->processedData has been initialized with the request's reply - QDBusMessage &reply = &data->reply; + QDBusMessage &reply = data->reply; // send the reply over D-Bus: reply << data->processedData; diff --git a/src/dbus/doc/snippets/code/doc_src_qtdbus.cpp b/src/dbus/doc/snippets/code/doc_src_qtdbus.cpp deleted file mode 100644 index 444561267d..0000000000 --- a/src/dbus/doc/snippets/code/doc_src_qtdbus.cpp +++ /dev/null @@ -1,53 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, 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 The Qt Company Ltd 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 deleted file mode 100644 index a1ba138a85..0000000000 --- a/src/dbus/doc/snippets/code/doc_src_qtdbus.pro +++ /dev/null @@ -1,3 +0,0 @@ -#! [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 index b70cdf3455..92b9dea909 100644 --- a/src/dbus/doc/snippets/code/src_qdbus_qdbusabstractinterface.cpp +++ b/src/dbus/doc/snippets/code/src_qdbus_qdbusabstractinterface.cpp @@ -1,70 +1,68 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, 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 The Qt Company Ltd 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$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#include <QString> +#include <QDBusMessage> +#include <QDBusReply> +#include <QDBusInterface> + +using namespace Qt::StringLiterals; + +class Abstract_DBus_Interface : public QObject +{ + Q_OBJECT + +public: + Abstract_DBus_Interface(QObject *parent = nullptr) + : QObject(parent) { + interface = new QDBusInterface("org.example.Interface", "/Example/Methods"); + } + + ~Abstract_DBus_Interface() { delete interface; } + void interfaceMain(); + void asyncCall(); + QString retrieveValue() { return QString(); } + +public slots: + void callFinishedSlot(); + +private: + QDBusInterface *interface; +}; + +void Abstract_DBus_Interface::interfaceMain() +{ //! [0] QString value = retrieveValue(); QDBusMessage reply; -QDBusReply<int> api = interface->call(QLatin1String("GetAPIVersion")); +QDBusReply<int> api = interface->call("GetAPIVersion"_L1); if (api >= 14) - reply = interface->call(QLatin1String("ProcessWorkUnicode"), value); + reply = interface->call("ProcessWorkUnicode"_L1, value); else - reply = interface->call(QLatin1String("ProcessWork"), QLatin1String("UTF-8"), value.toUtf8()); + reply = interface->call("ProcessWork"_L1, "UTF-8"_L1, value.toUtf8()); //! [0] +} +void Abstract_DBus_Interface::asyncCall() +{ //! [1] -QString value = retrieveValue(); -QDBusPendingCall pcall = interface->asyncCall(QLatin1String("Process"), value); +QDBusPendingCall pcall = interface->asyncCall("GetAPIVersion"_L1); +auto watcher = new QDBusPendingCallWatcher(pcall, this); -QDBusPendingCallWatcher *watcher = new QDBusPendingCallWatcher(pcall, this); +QObject::connect(watcher, &QDBusPendingCallWatcher::finished, this, + [&](QDBusPendingCallWatcher *w) { + QString value = retrieveValue(); + QDBusPendingReply<int> reply(*w); + QDBusPendingCall pcall; + if (reply.argumentAt<0>() >= 14) + pcall = interface->asyncCall("ProcessWorkUnicode"_L1, value); + else + pcall = interface->asyncCall("ProcessWork"_L1, "UTF-8"_L1, value.toUtf8()); -QObject::connect(watcher, SIGNAL(finished(QDBusPendingCallWatcher*)), - this, SLOT(callFinishedSlot(QDBusPendingCallWatcher*))); + w = new QDBusPendingCallWatcher(pcall); + QObject::connect(w, &QDBusPendingCallWatcher::finished, this, + &Abstract_DBus_Interface::callFinishedSlot); +}); //! [1] +} diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbusargument.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbusargument.cpp index b64ea5cf21..5cb6ce5bb2 100644 --- a/src/dbus/doc/snippets/code/src_qdbus_qdbusargument.cpp +++ b/src/dbus/doc/snippets/code/src_qdbus_qdbusargument.cpp @@ -1,146 +1,205 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, 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 The Qt Company Ltd 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] +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#include <QString> +#include <QDBusArgument> +#include <QDBusMetaType> +#include <QDBusMessage> +#include <QDBusContext> + +typedef QDBusVariant MyElement; +typedef QList<MyElement> MyArray; +typedef QHash<int, MyElement> MyDictionary; +typedef QDBusVariant MyType; +typedef QDBusVariant MyValue; +typedef QDBusVariant Type; +QDBusArgument argument; + +class MyObject: public QObject +{ + Q_OBJECT + + Q_CLASSINFO("D-Bus Interface", "org.qtproject.QtDBus.MyObject") + Q_CLASSINFO("D-Bus Introspection", "" +" <interface name=\"org.qtproject.QtDBus.MyObject\" >\n" +" <property access=\"readwrite\" type=\"i\" name=\"prop1\" />\n" +" <property name=\"complexProp\" type=\"ai\" access=\"readwrite\">\n" +" <annotation name=\"org.qtproject.QtDBus.QtTypeName\" value=\"QList<int>\"/>\n" +" </property>\n" +" <signal name=\"somethingHappened\" >\n" +" <arg direction=\"out\" type=\"s\" />\n" +" </signal>\n" +" <method name=\"ping\" >\n" +" <arg direction=\"in\" type=\"v\" name=\"ping\" />\n" +" <arg direction=\"out\" type=\"v\" name=\"ping\" />\n" +" </method>\n" +" <method name=\"ping_invokable\" >\n" +" <arg direction=\"in\" type=\"v\" name=\"ping_invokable\" />\n" +" <arg direction=\"out\" type=\"v\" name=\"ping_invokable\" />\n" +" </method>\n" +" <method name=\"ping\" >\n" +" <arg direction=\"in\" type=\"v\" name=\"ping1\" />\n" +" <arg direction=\"in\" type=\"v\" name=\"ping2\" />\n" +" <arg direction=\"out\" type=\"v\" name=\"pong1\" />\n" +" <arg direction=\"out\" type=\"v\" name=\"pong2\" />\n" +" </method>\n" +" <method name=\"ping_invokable\" >\n" +" <arg direction=\"in\" type=\"v\" name=\"ping1_invokable\" />\n" +" <arg direction=\"in\" type=\"v\" name=\"ping2_invokable\" />\n" +" <arg direction=\"out\" type=\"v\" name=\"pong1_invokable\" />\n" +" <arg direction=\"out\" type=\"v\" name=\"pong2_invokable\" />\n" +" </method>\n" +" <method name=\"ping\" >\n" +" <arg direction=\"in\" type=\"ai\" name=\"ping\" />\n" +" <arg direction=\"out\" type=\"ai\" name=\"ping\" />\n" +" <annotation name=\"org.qtproject.QtDBus.QtTypeName.In0\" value=\"QList<int>\"/>\n" +" <annotation name=\"org.qtproject.QtDBus.QtTypeName.Out0\" value=\"QList<int>\"/>\n" +" </method>\n" +" <method name=\"ping_invokable\" >\n" +" <arg direction=\"in\" type=\"ai\" name=\"ping_invokable\" />\n" +" <arg direction=\"out\" type=\"ai\" name=\"ping_invokable\" />\n" +" <annotation name=\"org.qtproject.QtDBus.QtTypeName.In0\" value=\"QList<int>\"/>\n" +" <annotation name=\"org.qtproject.QtDBus.QtTypeName.Out0\" value=\"QList<int>\"/>\n" +" </method>\n" +" </interface>\n" + "") + Q_PROPERTY(int prop1 READ prop1 WRITE setProp1) + Q_PROPERTY(QList<int> complexProp READ complexProp WRITE setComplexProp) + +public: + static int callCount; + static QVariantList callArgs; + MyObject() + { + QObject *subObject = new QObject(this); + subObject->setObjectName("subObject"); + } +}; + +struct MyMember +{ + int subMember1; + int subMember2; +}; + +//! [0-0] struct MyStructure { int count; QString name; +//! [0-0] + MyMember member1; + MyMember member2; + MyMember member3; + MyMember member4; +//! [0-1] + // ... }; Q_DECLARE_METATYPE(MyStructure) // Marshall the MyStructure data into a D-Bus argument -QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &mystruct) +QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &myStruct) { argument.beginStructure(); - argument << mystruct.count << mystruct.name; + 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) +const QDBusArgument &operator>>(const QDBusArgument &argument, MyStructure &myStruct) { argument.beginStructure(); - argument >> mystruct.count >> mystruct.name; + argument >> myStruct.count >> myStruct.name; argument.endStructure(); return argument; } -//! [0] +//! [0-1] +const QDBusArgument &operator<<(const QDBusArgument &argument, const MyMember &/*member*/) +{ + return argument; +} + +const QDBusArgument &operator>>(const QDBusArgument &argument, const MyMember &/*member*/) +{ + return argument; +} +void registerMyStructure() +{ //! [1] qDBusRegisterMetaType<MyStructure>(); //! [1] +} - +void castType() +{ +QVariant argument = MyObject::callArgs.at(0); +QDBusVariant dv = qdbus_cast<QDBusVariant>(argument); //! [2] MyType item = qdbus_cast<Type>(argument); //! [2] +} - +void argumentItem() +{ //! [3] MyType item; argument >> item; //! [3] - - +} +namespace QDBusSnippets +{ //! [4] -QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &mystruct) +QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &myStruct) { argument.beginStructure(); - argument << mystruct.member1 << mystruct.member2 << ... ; + argument << myStruct.member1 << myStruct.member2; argument.endStructure(); return argument; } //! [4] - +namespace Alt { //! [5] -QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &mystruct) +QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &myStruct) { argument.beginStructure(); - argument << mystruct.member1 << mystruct.member2; + argument << myStruct.member1 << myStruct.member2; argument.beginStructure(); - argument << mystruct.member3.subMember1 << mystruct.member3.subMember2; + argument << myStruct.member3.subMember1 << myStruct.member3.subMember2; argument.endStructure(); - argument << mystruct.member4; + argument << myStruct.member4; argument.endStructure(); return argument; } //! [5] - +} // namespace //! [6] -// append an array of MyElement types -QDBusArgument &operator<<(QDBusArgument &argument, const MyArray &myarray) +// 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.beginArray(qMetaTypeId<MyElement>()); + for (const auto &element : myArray) + argument << element; argument.endArray(); return argument; } //! [6] - //! [7] -// append a dictionary that associates ints to MyValue types -QDBusArgument &operator<<(QDBusArgument &argument, const MyDictionary &mydict) +// 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.beginMap(QMetaType::fromType<int>(), QMetaType::fromType<MyValue>()); + MyDictionary::const_iterator i; + for (i = myDict.cbegin(); i != myDict.cend(); ++i) { argument.beginMapEntry(); - argument << mydict.data[i].key << mydict.data[i].value; + argument << i.key() << i.value(); argument.endMapEntry(); } argument.endMap(); @@ -148,29 +207,27 @@ QDBusArgument &operator<<(QDBusArgument &argument, const MyDictionary &mydict) } //! [7] - //! [8] -const QDBusArgument &operator>>(const QDBusArgument &argument, MyStructure &mystruct) +const QDBusArgument &operator>>(const QDBusArgument &argument, MyStructure &myStruct) { - argument.beginStructure() - argument >> mystruct.member1 >> mystruct.member2 >> mystruct.member3 >> ...; + 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) +// Extract a MyArray array of MyElement elements +const QDBusArgument &operator>>(const QDBusArgument &argument, MyArray &myArray) { argument.beginArray(); - myarray.clear(); + myArray.clear(); - while ( !argument.atEnd() ) { + while (!argument.atEnd()) { MyElement element; argument >> element; - myarray.append( element ); + myArray.append(element); } argument.endArray(); @@ -178,24 +235,24 @@ const QDBusArgument &operator>>(const QDBusArgument &argument, MyArray &myarray) } //! [9] - //! [10] -// extract a MyDictionary map that associates ints to MyValue elements -const QDBusArgument &operator>>(const QDBusArgument &argument, MyDictionary &mydict) +// Extract a MyDictionary map that associates integers to MyElement items +const QDBusArgument &operator>>(const QDBusArgument &argument, MyDictionary &myDict) { argument.beginMap(); - mydict.clear(); + myDict.clear(); - while ( !argument.atEnd() ) { + while (!argument.atEnd()) { int key; - MyValue value; + MyElement value; argument.beginMapEntry(); argument >> key >> value; argument.endMapEntry(); - mydict.append( key, value ); + myDict.insert(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 index dd49e004c5..75b4394595 100644 --- a/src/dbus/doc/snippets/code/src_qdbus_qdbuscontext.cpp +++ b/src/dbus/doc/snippets/code/src_qdbus_qdbuscontext.cpp @@ -1,62 +1,23 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, 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 The Qt Company Ltd 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$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#include <QString> +#include <QDBusConnection> +#include <QDBusArgument> +#include <QDBusMetaType> +#include <QDBusMessage> +#include <QDBusContext> //! [0] class MyObject: public QObject, protected QDBusContext { Q_OBJECT + QDBusConnection conn; QDBusMessage msg; -... + //... protected slots: void process(); @@ -76,7 +37,7 @@ QString MyObject::methodWithDelayedReply() conn = connection(); msg = message(); setDelayedReply(true); - QMetaObject::invokeMethod(this, "process", Qt::QueuedConnection); + QMetaObject::invokeMethod(this, &MyObject::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 index a9c1fdfe6d..06d654b97b 100644 --- a/src/dbus/doc/snippets/code/src_qdbus_qdbusinterface.cpp +++ b/src/dbus/doc/snippets/code/src_qdbus_qdbusinterface.cpp @@ -1,53 +1,10 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, 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 The Qt Company Ltd 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$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#include <QDBusInterface> +#include <QDBusReply> +void DBusInterface_main() +{ //! [0] QDBusInterface remoteApp( "com.example.Calculator", "/Calculator/Operations", "org.mathematics.RPNCalculator" ); @@ -59,3 +16,4 @@ 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 index bc90f118c9..c9e5281cdb 100644 --- a/src/dbus/doc/snippets/code/src_qdbus_qdbusmetatype.cpp +++ b/src/dbus/doc/snippets/code/src_qdbus_qdbusmetatype.cpp @@ -1,54 +1,14 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, 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 The Qt Company Ltd 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$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause -//! [0] +#include <QtCore/qlist.h> +typedef QList<QString> MyClass; + +//! [0-0] #include <QDBusMetaType> +//! [0-0] +void dbus() { +//! [0-1] qDBusRegisterMetaType<MyClass>(); -//! [0] +//! [0-1] +} diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingcall.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingcall.cpp index 9552054a5e..67b019a67d 100644 --- a/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingcall.cpp +++ b/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingcall.cpp @@ -1,66 +1,46 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, 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 The Qt Company Ltd 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$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#include <QDBusPendingCall> +#include <QDBusInterface> +#include <QDBusPendingReply> +class DBus_PendingCall_Interface : public QObject +{ + Q_OBJECT + +public: + DBus_PendingCall_Interface(QObject *parent = nullptr) + : QObject(parent) { + iface = new QDBusInterface("org.example.Interface", "/Example/Methods"); + } + + ~DBus_PendingCall_Interface() { delete iface; } + void callInterfaceMain(); + void showError(); + void showReply(QString&, QByteArray&); + QString value1; + QString value2; + void callFinishedSlot(QDBusPendingCallWatcher *call); +public slots: + +private: + QDBusInterface *iface; +}; + +void DBus_PendingCall_Interface::callInterfaceMain() { //! [0] QDBusPendingCall async = iface->asyncCall("RemoteMethod", value1, value2); QDBusPendingCallWatcher *watcher = new QDBusPendingCallWatcher(async, this); - QObject::connect(watcher, SIGNAL(finished(QDBusPendingCallWatcher*)), - this, SLOT(callFinishedSlot(QDBusPendingCallWatcher*))); + QObject::connect(watcher, &QDBusPendingCallWatcher::finished, this, + &DBus_PendingCall_Interface::callFinishedSlot); //! [0] } //! [1] -void MyClass::callFinishedSlot(QDBusPendingCallWatcher *call) +void DBus_PendingCall_Interface::callFinishedSlot(QDBusPendingCallWatcher *call) { QDBusPendingReply<QString, QByteArray> reply = *call; if (reply.isError()) { diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingreply.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingreply.cpp index 7e6ee55b8a..04f707dba8 100644 --- a/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingreply.cpp +++ b/src/dbus/doc/snippets/code/src_qdbus_qdbuspendingreply.cpp @@ -1,67 +1,51 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, 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 The Qt Company Ltd 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$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#include <QDBusPendingCall> +#include <QDBusInterface> +#include <QDBusPendingReply> +class DBus_PendingReply_Interface : public QObject +{ + Q_OBJECT + +public: + DBus_PendingReply_Interface(QObject *parent = nullptr) + : QObject(parent) { + iface = new QDBusInterface("org.example.Interface", "/Example/Methods"); + } + + ~DBus_PendingReply_Interface() { delete iface; } + void callInterfaceMainR(); + void PendingReplyString(); + void PendingReplyBool(); + void showErrorD(QDBusError); + void showSuccess(QVariant); + void showFailure(QVariant); + void useValue(QDBusPendingReplyTypes::Select<0, QString, void, void, void, void, void, void, void>::Type); +public slots: + +private: + QDBusInterface *iface; +}; + +void DBus_PendingReply_Interface::PendingReplyString() { //! [0] - QDBusPendingReply<QString> reply = interface->asyncCall("RemoteMethod"); + QDBusPendingReply<QString> reply = iface->asyncCall("RemoteMethod"); reply.waitForFinished(); if (reply.isError()) // call failed. Show an error condition. - showError(reply.error()); + showErrorD(reply.error()); else // use the returned value useValue(reply.value()); //! [0] +} +void DBus_PendingReply_Interface::PendingReplyBool() +{ //! [2] - QDBusPendingReply<bool, QString> reply = interface->asyncCall("RemoteMethod"); + QDBusPendingReply<bool, QString> reply = iface->asyncCall("RemoteMethod"); reply.waitForFinished(); if (!reply.isError()) { if (reply.argumentAt<0>()) diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbusreply.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbusreply.cpp index 1490cbb127..2def08bdfe 100644 --- a/src/dbus/doc/snippets/code/src_qdbus_qdbusreply.cpp +++ b/src/dbus/doc/snippets/code/src_qdbus_qdbusreply.cpp @@ -1,53 +1,31 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, 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 The Qt Company Ltd 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$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#include <QDBusPendingCall> +#include <QDBusInterface> +#include <QDBusPendingReply> +#include <QDBusReply> +class DBus_Process_String_Interface : public QObject +{ + Q_OBJECT + +public: + DBus_Process_String_Interface(QObject *parent = nullptr) + : QObject(parent) { + interface = new QDBusInterface("org.example.Interface", "/Example/Methods"); + } + + ~DBus_Process_String_Interface() { delete interface; } + void QDBus_reply(); + void useValue(QVariant); + void showError(const QDBusError&); +public slots: + +private: + QDBusInterface *interface; +}; +void DBus_Process_String_Interface::QDBus_reply() +{ //! [0] QDBusReply<QString> reply = interface->call("RemoteMethod"); if (reply.isValid()) @@ -60,5 +38,6 @@ else //! [1] -QString reply = interface->call("RemoteMethod"); +reply = interface->call("RemoteMethod"); //! [1] +} diff --git a/src/dbus/doc/snippets/qdbusextratypes/qdbusextratypes.cpp b/src/dbus/doc/snippets/qdbusextratypes/qdbusextratypes.cpp index a851e9f39f..9029fa8cf7 100644 --- a/src/dbus/doc/snippets/qdbusextratypes/qdbusextratypes.cpp +++ b/src/dbus/doc/snippets/qdbusextratypes/qdbusextratypes.cpp @@ -1,55 +1,8 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, 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 The Qt Company Ltd 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$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include <QtCore> -#include <QtDBus> + static QVariant callMyDBusFunction() { return QVariant(); } diff --git a/src/dbus/doc/snippets/snippets.pro b/src/dbus/doc/snippets/snippets.pro new file mode 100644 index 0000000000..6c3b57fec9 --- /dev/null +++ b/src/dbus/doc/snippets/snippets.pro @@ -0,0 +1,3 @@ +#! [qmake_use] +QT += dbus +#! [qmake_use] diff --git a/src/dbus/doc/src/dbus-adaptors.qdoc b/src/dbus/doc/src/dbus-adaptors.qdoc index 3398a45af7..e57cc095b9 100644 --- a/src/dbus/doc/src/dbus-adaptors.qdoc +++ b/src/dbus/doc/src/dbus-adaptors.qdoc @@ -1,36 +1,12 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page usingadaptors.html \title Using Qt D-Bus Adaptors \brief How to create and use DBus adaptors in Qt. - \ingroup best-practices + \ingroup how-to 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 @@ -68,7 +44,7 @@ \li \l{Declaring Slots in D-Bus Adaptors} \li \l{Declaring Signals in D-Bus Adaptors} \li \l{The Qt D-Bus Type System} - \li In the \l{D-Bus Complex Ping Pong Example}, \c complexpong.h and + \li In the \l{D-Bus Complex Ping Pong} example, \c complexpong.h and \c complexpong.cpp show an implementation of QDBusAbstractAdaptor. \endlist @@ -79,7 +55,6 @@ \page qdbusdeclaringslots.html \title Declaring Slots in D-Bus Adaptors - \contentspage Using Qt D-Bus Adaptors \nextpage Declaring Signals in D-Bus Adaptors Slots in D-Bus adaptors are declared just like normal, public slots, but their @@ -112,15 +87,15 @@ Asynchronous slots are marked by the keyword \l Q_NOREPLY in the method signature, before the \c void return type and the slot name. The \c quit() - slot in the \l {D-Bus Complex Ping Pong Example} is an example of this. + slot in the \l {D-Bus Complex Ping Pong} example is an example of this. \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. + Therefore, non-asynchronous slots should not block or should explicitly + state it will block in 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. @@ -191,7 +166,7 @@ The delayed reply itself is requested from Qt D-Bus by calling QDBusMessage::reply() on the original message. It then becomes the - resposibility of the called code to eventually send a reply to the + responsibility 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 @@ -208,7 +183,6 @@ \title Declaring Signals in D-Bus Adaptors \previouspage Declaring Slots in D-Bus Adaptors - \contentspage Using Qt D-Bus Adaptors \nextpage The Qt D-Bus Type System Any signal in a class derived from QDBusAbstractAdaptor will be automatically @@ -219,8 +193,8 @@ 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 you can see in the \l {D-Bus Complex Ping - Pong Example}. + the adaptor's constructor, as you can see in the \l {D-Bus Complex Ping Pong} + example. The QDBusAbstractAdaptor::setAutoRelaySignals() convenience function can also be used to make and break connections between signals in the real object and @@ -237,7 +211,6 @@ \title The Qt D-Bus Type System \previouspage Declaring Signals in D-Bus Adaptors - \contentspage Using Qt D-Bus Adaptors D-Bus has an extensible type system based on a few primitives and composition of the primitives in arrays and structures. Qt D-Bus diff --git a/src/dbus/doc/src/dontdocument.qdoc b/src/dbus/doc/src/dontdocument.qdoc index bbb8acb53c..c217ca9276 100644 --- a/src/dbus/doc/src/dontdocument.qdoc +++ b/src/dbus/doc/src/dontdocument.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2019 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \dontdocument (QTypeInfo QMetaTypeId QDBusAbstractInterfaceBase QDBusPendingReplyData QMetaTypeId2) diff --git a/src/dbus/doc/src/includes/cmake-find-package-dbus.qdocinc b/src/dbus/doc/src/includes/cmake-find-package-dbus.qdocinc new file mode 100644 index 0000000000..1ed1c6a8ec --- /dev/null +++ b/src/dbus/doc/src/includes/cmake-find-package-dbus.qdocinc @@ -0,0 +1,5 @@ +The command is defined in the \c DBus component of the \c Qt6 package. Load the package with: + +\code +find_package(Qt6 REQUIRED COMPONENTS DBus) +\endcode diff --git a/src/dbus/doc/src/qdbusxml2cpp.qdoc b/src/dbus/doc/src/qdbusxml2cpp.qdoc index 1dd8a9af7a..d63453bf78 100644 --- a/src/dbus/doc/src/qdbusxml2cpp.qdoc +++ b/src/dbus/doc/src/qdbusxml2cpp.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qdbusxml2cpp.html diff --git a/src/dbus/doc/src/qt6-changes.qdoc b/src/dbus/doc/src/qt6-changes.qdoc new file mode 100644 index 0000000000..80cd56c627 --- /dev/null +++ b/src/dbus/doc/src/qt6-changes.qdoc @@ -0,0 +1,44 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page dbus-changes-qt6.html + \title Changes to Qt D-Bus + \ingroup changes-qt-5-to-6 + \brief Minimal porting effort to be able to switch to Qt 6. + + Qt 6 is a result of the conscious effort to make the framework more + efficient and easy to use. + + We try to maintain binary and source compatibility for all the public + APIs in each release. But some changes were inevitable in an effort to + make Qt a better framework. + + In this topic we summarize those changes in Qt DBus, and provide + guidance to handle them. + + \section1 API changes + + The QtDBus module has undergone some basic consolidation and + cleanup. There should be minimal porting effort to be able to switch to Qt6. + + \section2 The QDBusMessage class + The QDBusMessage::call() and QDBusMessage::asyncCall() methods with a fixed + size of arguments have been removed in Qt6. + + \section2 The QDBusArgument class + The QDBusArgument::operator<<() specializations for QHash, QMap and QList + have been unified into common specializations for associative containers. + + \section2 The QDBusConnection class + The QDBusConnection::sender() function has been removed in Qt6. + + \section2 The QDBusMessage class + The QDBusMessage::createErrorReply() function now takes the QString \c name + argument by const reference instead of taking by value. + + \section2 The QDBusPendingReply class + QDBusPendingReply has been changed to be a variadic template class in order + to support more than 8 template parameters now. The template parameters + are the types that will be used to extract the contents of the reply's data. +*/ diff --git a/src/dbus/doc/src/qtdbus-cmake.qdoc b/src/dbus/doc/src/qtdbus-cmake.qdoc index de127fa9f4..86807af6e5 100644 --- a/src/dbus/doc/src/qtdbus-cmake.qdoc +++ b/src/dbus/doc/src/qtdbus-cmake.qdoc @@ -1,45 +1,43 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2019 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qtdbus-cmake-qt5-add-dbus-interface.html +\group cmake-commands-qtdbus +\title CMake Commands in Qt6 DBus +\brief Lists CMake commands defined in Qt6::DBus. + +The following CMake commands are defined when Qt6::DBus is loaded, for instance +with + +\code +find_package(Qt6 REQUIRED COMPONENTS DBus) +\endcode + +\sa{CMake Command Reference} +*/ + +/*! +\page qtdbus-cmake-qt-add-dbus-interface.html \ingroup cmake-commands-qtdbus -\title qt5_add_dbus_interface +\title qt_add_dbus_interface +\keyword qt6_add_dbus_interface -\brief Generates C++ sources implementing an interface for a D-Bus interface -description file. +\summary {Generates C++ sources implementing an interface for a D-Bus interface +description file.} + +\include cmake-find-package-dbus.qdocinc + +\cmakecommandsince 6.0 \section1 Synopsis \badcode -qt5_add_dbus_interface(<VAR> dbus_spec basename) +qt_add_dbus_interface(<VAR> dbus_spec basename) \endcode +\versionlessCMakeCommandsNote qt6_add_dbus_interface() + \section1 Description Generates C++ sources implementing an interface for a D-Bus interface description @@ -64,7 +62,7 @@ class named after the interface name, with a namespaced alias: \section1 Options -Options can be set using \c set_source_file_property on the \c dbus_spec: +Options can be set using \c set_source_files_properties on the \c dbus_spec: \table \header @@ -87,20 +85,27 @@ Options can be set using \c set_source_file_property on the \c dbus_spec: */ /*! -\page qtdbus-cmake-qt5-add-dbus-interfaces.html +\page qtdbus-cmake-qt-add-dbus-interfaces.html \ingroup cmake-commands-qtdbus -\title qt5_add_dbus_interfaces +\title qt_add_dbus_interfaces +\keyword qt6_add_dbus_interfaces -\brief Generates C++ sources implementing interfaces for D-Bus interface -description files. +\summary {Generates C++ sources implementing interfaces for D-Bus interface +description files.} + +\include cmake-find-package-dbus.qdocinc + +\cmakecommandsince 6.0 \section1 Synopsis \badcode -qt5_add_dbus_interfaces(<VAR> dbus_spec1 [dbus_spec2 ...]) +qt_add_dbus_interfaces(<VAR> dbus_spec1 [dbus_spec2 ...]) \endcode +\versionlessCMakeCommandsNote qt6_add_dbus_interfaces() + \section1 Description Generates C++ sources implementing D-Bus interfaces defined in \c{dbus_spec1}, @@ -117,7 +122,7 @@ The generated C++ source files are named after the XML file: For the file \section1 Options -Options can be set using \c set_source_file_property on each of the file +Options can be set using \c set_source_files_properties on each of the file arguments: \table @@ -141,26 +146,33 @@ arguments: */ /*! -\page qtdbus-cmake-qt5-generate-dbus-interface.html +\page qtdbus-cmake-qt-generate-dbus-interface.html \ingroup cmake-commands-qtdbus -\title qt5_generate_dbus_interface +\title qt_generate_dbus_interface +\keyword qt6_generate_dbus_interface -\brief Generates a D-Bus interface from a header file. +\summary {Generates a D-Bus interface from a header file.} + +\include cmake-find-package-dbus.qdocinc + +\cmakecommandsince 6.0 \section1 Synopsis \badcode -qt5_generate_dbus_interface(header +qt_generate_dbus_interface(header [customName] [OPTIONS options] ) \endcode +\versionlessCMakeCommandsNote qt6_generate_dbus_interface() + \section1 Description Parses the C++ source or header file containing a QObject-derived class -declaration and generates a file containing the D-BUS Introspection XML. +declaration and generates a file containing the D-Bus Introspection XML. By default, the generated XML file is stored in the current binary directory, and has the same base name as the header. You can specify a different name or @@ -173,21 +185,30 @@ arguments to the tool can be set after \c{OPTIONS}. */ /*! -\page qtdbus-cmake-qt5-add-dbus-adaptor.html +\page qtdbus-cmake-qt-add-dbus-adaptor.html \ingroup cmake-commands-qtdbus -\title qt5_add_dbus_adaptor +\title qt_add_dbus_adaptor +\keyword qt6_add_dbus_adaptor -\brief Generates an adaptor class for a D-Bus interface. +\summary {Generates an adaptor class for a D-Bus interface.} + +\include cmake-find-package-dbus.qdocinc + +\cmakecommandsince 6.0 \section1 Synopsis \badcode -qt5_add_dbus_adaptor(<VAR> dbus_spec header parent_class - [basename] - [classname]) +qt_add_dbus_adaptor(<VAR> dbus_spec header + [parent_class] + [basename] + [classname] +) \endcode +\versionlessCMakeCommandsNote qt6_add_dbus_adaptor() + \section1 Description Generates a C++ header file implementing an adaptor for a D-Bus interface @@ -220,5 +241,67 @@ argument. \section1 Examples -\snippet cmake/examples.cmake qt5_add_dbus_adaptor +\snippet cmake/examples.cmake qt_add_dbus_adaptor +*/ + +/*! +\group cmake-source-file-properties-qtdbus +\title CMake Source File Properties in Qt6 DBus +\brief Lists CMake file properties used in Qt6::DBus. + +\l{CMake Commands in Qt6 DBus}{CMake Commands} know about the following CMake +source file properties: + +\sa{CMake Property Reference} */ + +/*! +\page cmake-source-file-property-classname.html +\ingroup cmake-source-file-properties-qtdbus + +\title CLASSNAME +\target cmake-source-file-property-CLASSNAME + +\summary {Overrides the default interface class name.} + +\cmakepropertysince 5.0 + +When this property is set, the generated C++ class name is overridden +with the provided property value. + +\sa{qt6_add_dbus_interface}{qt_add_dbus_interface} +*/ + +/*! +\page cmake-source-file-property-include.html +\ingroup cmake-source-file-properties-qtdbus + +\title INCLUDE +\target cmake-source-file-property-INCLUDE + +\summary {Adds an include path.} + +\cmakepropertysince 5.0 + +When this property is set, an #include "path" is added +to the generated C++ file. + +\sa{qt6_add_dbus_interface}{qt_add_dbus_interface} +*/ + +/*! +\page cmake-source-file-property-no-namespace.html +\ingroup cmake-source-file-properties-qtdbus + +\title NO_NAMESPACE +\target cmake-source-file-property-NO_NAMESPACE + +\summary {Disables generation of a namespaced name.} + +\cmakepropertysince 5.0 + +When this property is set, the generated C++ class will not contain a namespaced alias. + +\sa{qt6_add_dbus_interface}{qt_add_dbus_interface} +*/ + diff --git a/src/dbus/doc/src/qtdbus-examples.qdoc b/src/dbus/doc/src/qtdbus-examples.qdoc index a35207ddee..9b55e3f3f7 100644 --- a/src/dbus/doc/src/qtdbus-examples.qdoc +++ b/src/dbus/doc/src/qtdbus-examples.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \group examples-dbus diff --git a/src/dbus/doc/src/qtdbus-index.qdoc b/src/dbus/doc/src/qtdbus-index.qdoc index 18a4aa6d0f..05ca38a207 100644 --- a/src/dbus/doc/src/qtdbus-index.qdoc +++ b/src/dbus/doc/src/qtdbus-index.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtdbus-index.html @@ -32,202 +8,75 @@ \keyword QtDBus - \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 + was also 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. + \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 + 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 Qt D-Bus 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: - - \image 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 Using the Module + + \include {module-use.qdocinc} {using the c++ api} + + \include {module-use.qdocinc} {building with cmake} {DBus} + + \section1 Articles and Guides + + 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 {Qt D-Bus Overview} + \li \l {Using Qt D-Bus Adaptors} + \li \l {The Qt D-Bus Type System} + \li \l {Qt D-Bus XML compiler (qdbusxml2cpp)} + \li \l{D-Bus Viewer} + \endlist + + \section1 Examples + + \list + \li \l{Qt D-Bus Examples} + \endlist + + \section1 Reference + + \list + \li \l{Qt D-Bus C++ Classes} + \li \l{CMake Commands in Qt6 DBus} + \endlist + + \section1 Module Evolution + + \l{Changes to Qt D-Bus} lists important changes in the module API + and functionality that were made for the Qt 6 series of Qt. \section1 Licenses and Attributions The Qt D-Bus module is available under commercial licenses from \l{The Qt Company}. - In addition, it is available under free software licenses. Since Qt 5.4, - these free software licenses are - \l{GNU Lesser General Public License, version 3}, or + In addition, it is available under free software licenses: + The \l{GNU Lesser General Public License, version 3}, or the \l{GNU General Public License, version 2}. See \l{Qt Licensing} for further details. Furthermore, Qt D-Bus in Qt \QtVersion may contain third party - modules under following permissive licenses: + modules under the following permissive licenses: \generatelist{groupsbymodule attributions-qtdbus} - - \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 Qt D-Bus Adaptors} - \li \l{The Qt D-Bus Type System} - \li \l{Qt D-Bus XML compiler (qdbusxml2cpp)} - \li \l{Qt D-Bus C++ Classes} - \li \l{Qt D-Bus Examples} - \li \l{D-Bus Viewer} - \endlist */ /*! diff --git a/src/dbus/doc/src/qtdbus-module.qdoc b/src/dbus/doc/src/qtdbus-module.qdoc index 0ef5999b11..c89b4dc937 100644 --- a/src/dbus/doc/src/qtdbus-module.qdoc +++ b/src/dbus/doc/src/qtdbus-module.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** 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. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \module QtDBus @@ -32,6 +8,7 @@ to perform Inter-Process Communication using the \l{Qt D-Bus}{D-Bus} protocol. \ingroup modules + \qtcmakepackage DBus \qtvariable dbus \keyword The QDBus compiler @@ -42,27 +19,5 @@ services exported by those applications by placing calls and accessing properties. - The Qt D-Bus 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 !defined(qtforpython) - If you're using qmake to build your application, you can add this - line to your .pro file to make it link against the Qt D-Bus - 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. - \endif - - See the \l {Qt D-Bus}{D-Bus} page for detailed information on - how to use this module. + The \l{Qt D-Bus} page contains information about how to use the module. */ diff --git a/src/dbus/doc/src/qtdbus-overview.qdoc b/src/dbus/doc/src/qtdbus-overview.qdoc new file mode 100644 index 0000000000..6342e674fd --- /dev/null +++ b/src/dbus/doc/src/qtdbus-overview.qdoc @@ -0,0 +1,176 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qtdbus-overview.html + \title Qt D-Bus Overview + \brief Provides insight into the Qt Qt D-Bus module. + \ingroup explanations-networkingandconnectivity + + 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 + was also 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 when many-to-many communication is + desired. In order to achieve that, a central server is launched + before any application 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 probably be found on the + session bus. + + On the system bus, you can also expect to find restrictions on + what services each application is allowed to offer. Therefore, you + can be reasonably certain that if a certain service is present, + it's 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 Qt D-Bus 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 your 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 organized, much like the parent-child + relationship that classes derived from QObject possess. One + difference, however, is that there is the concept of "root + object", which all objects have as the ultimate parent. + + If we continue our analogy with Web services, object paths + equate to the path part of a URL: + + \image 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. + +*/ |