Long live Qt 4.5!

1 files changed, 425 insertions, 0 deletions

diff --git a/src/dbus/qdbusintrospection.cpp b/src/dbus/qdbusintrospection.cpp
new file mode 100644
index 0000000000..e642dbe64e
--- /dev/null
+++ b/src/dbus/qdbusintrospection.cpp
@@ -0,0 +1,425 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the QtDBus module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qdbusintrospection_p.h"
+#include "qdbusxmlparser_p.h"
+
+QT_BEGIN_NAMESPACE
+
+/*!
+    \class QDBusIntrospection
+    \brief Information about introspected objects and interfaces on D-Bus.
+    \internal
+
+    This class provides structures and methods for parsing the XML introspection data for D-Bus.
+    Normally, you don't have to use the methods provided here: QDBusInterface and QDBusObject will
+    do that for you.
+
+    But they may prove useful if the XML data was obtained through other means (like parsing a file).
+*/
+
+/*!
+    \class QDBusIntrospection::Argument
+    \brief One argument to a D-Bus method or signal.
+
+    This struct represents one argument passed to a method or received from a method or signal in
+    D-Bus. The struct does not contain information on the direction (input or output).
+*/
+
+/*!
+    \variable QDBusIntrospection::Argument::type
+    The argument type.
+*/
+
+/*!
+    \variable QDBusIntrospection::Argument::name
+    The argument name. The argument name is optional, so this may be a null QString.
+*/
+
+/*!
+    \fn QDBusIntrospection::Argument::operator==(const Argument &other) const
+    Compares this object against \a other and return true if they are the same.
+*/
+
+/*!
+    \class QDBusIntrospection::Method
+    \brief Information about one method.
+
+    This struct represents one method discovered through introspection. A method is composed of
+    its \a name, its input arguments, its output arguments, and, optionally, annotations. There are no
+    "in-out" arguments.
+*/
+
+/*!
+    \variable QDBusIntrospection::Method::name
+    The method's name.
+*/
+
+/*!
+    \variable QDBusIntrospection::Method::inputArgs
+    A list of the method's input arguments.
+*/
+
+/*!
+    \variable QDBusIntrospection::Method::outputArgs
+    A list of the method's output arguments (i.e., return values).
+*/
+
+/*!
+    \variable QDBusIntrospection::Method::annotations
+    The annotations associated with the method. Each annotation is a pair of strings, where the key
+    is of the same format as a D-Bus interface name. The value is arbitrary.
+*/
+
+/*!
+    \fn QDBusIntrospection::Method::operator==(const Method &other) const
+    Compares this object against \a other and return true if they are the same.
+*/
+
+/*!
+    \class QDBusIntrospection::Signal
+    \brief Information about one signal.
+
+    This struct represents one signal discovered through introspection. A signal is composed of
+    its \a name, its output arguments, and, optionally, annotations.
+*/
+
+/*!
+    \variable QDBusIntrospection::Signal::name
+    The signal's name.
+*/
+
+/*!
+    \variable QDBusIntrospection::Signal::outputArgs
+    A list of the signal's arguments.
+*/
+
+/*!
+    \variable QDBusIntrospection::Signal::annotations
+    The annotations associated with the signal. Each annotation is a pair of strings, where the key
+    is of the same format as a D-Bus interface name. The value is arbitrary.
+*/
+
+/*!
+    \fn QDBusIntrospection::Signal::operator==(const Signal& other) const
+    Compares this object against \a other and return true if they are the same.
+*/
+
+/*!
+    \class QDBusIntrospection::Property
+    \brief Information about one property.
+
+    This struct represents one property discovered through introspection. A property is composed of
+    its \a name, its \a type, its \a access rights, and, optionally, annotations.
+*/
+
+/*!
+    \variable QDBusIntrospection::Property::name
+    The property's name.
+*/
+
+/*!
+    \variable QDBusIntrospection::Property::type
+    The property's type.
+*/
+
+/*!
+    \enum QDBusIntrospection::Property::Access
+    The possible access rights for a property:
+    \value Read
+    \value Write
+    \value ReadWrite
+*/
+
+/*!
+    \variable QDBusIntrospection::Property::access
+    The property's access rights.
+*/
+
+/*!
+    \variable QDBusIntrospection::Property::annotations
+    The annotations associated with the property. Each annotation is a pair of strings, where the key
+    is of the same format as a D-Bus interface name. The value is arbitrary.
+*/
+
+/*!
+    \fn QDBusIntrospection::Property::operator==(const Property &other) const
+    Compares this object against \a other and return true if they are the same.
+*/
+
+/*!
+    \class QDBusIntrospection::Interface
+    \brief Information about one interface on the bus.
+
+    Each interface on D-Bus has an unique \a name, identifying where that interface was defined.
+    Interfaces may have annotations, methods, signals and properties, but none are mandatory.
+*/
+
+/*!
+    \variable QDBusIntrospection::Interface::name
+    The interface's name.
+*/
+
+/*!
+    \variable QDBusIntrospection::Interface::introspection
+    The XML document fragment describing this interface.
+
+    If parsed again through parseInterface, the object returned should have the same contents as
+    this object.
+*/
+
+/*!
+    \variable QDBusIntrospection::Interface::annotations
+    The annotations associated with the interface. Each annotation is a pair of strings, where the key
+    is of the same format as a D-Bus interface name. The value is arbitrary.
+*/
+
+/*!
+    \variable QDBusIntrospection::Interface::methods
+    The methods available in this interface. Note that method names are not unique (i.e., methods
+    can be overloaded with multiple arguments types).
+*/
+
+/*!
+    \variable QDBusIntrospection::Interface::signals_
+    The signals available in this interface. Note that signal names are not unique (i.e., signals
+    can be overloaded with multiple argument types).
+
+    This member is called "signals_" because "signals" is a reserved keyword in Qt.
+*/
+
+/*!
+    \variable QDBusIntrospection::Interface::properties
+    The properties available in this interface. Property names are unique.
+*/
+
+/*!
+    \fn QDBusIntrospection::Interface::operator==(const Interface &other) const
+    Compares this object against \a other and return true if they are the same.
+
+    Note that two interfaces are considered to be the same if they have the same name. The internal
+    structures in the objects are not compared.
+*/
+
+/*!
+    \class QDBusIntrospection::Object
+    \brief Information about one object on the bus.
+
+    An object on the D-Bus bus is represented by its service and path on the service but, unlike
+    interfaces, objects are mutable. That is, their contents can change with time. Therefore,
+    while the (service, path) pair uniquely identifies an object, the information contained in
+    this struct may no longer represent the object.
+
+    An object can contain interfaces and child (sub) objects.
+*/
+
+/*!
+    \variable QDBusIntrospection::Object::service
+    The object's service name.
+
+    \sa parseObject(), parseObjectTree()
+*/
+
+/*!
+    \variable QDBusIntrospection::Object::path
+    The object's path on the service. This is an absolute path.
+
+    \sa parseObject(), parseObjectTree()
+*/
+
+/*!
+    \variable QDBusIntrospection::Object::introspection
+    The XML document fragment describing this object, its interfaces and sub-objects at the time
+    of the parsing.
+
+    The result of parseObject with this XML data should be the same as the Object struct.
+*/
+
+/*!
+    \variable QDBusIntrospection::Object::interfaces
+    The list of interface names in this object.
+*/
+
+/*!
+    \variable QDBusIntrospection::Object::childObjects
+    The list of child object names in this object. Note that this is a relative name, not an
+    absolute path. To obtain the absolute path, concatenate with \l
+    {QDBusIntrospection::Object::path}{path}.
+*/
+
+/*!
+    \class QDBusIntrospection::ObjectTree
+    \brief Complete information about one object node and its descendency.
+    
+    This struct contains the same data as QDBusIntrospection::Object, plus the actual data for the
+    interfaces and child (sub) objects that was available in the XML document.
+*/
+
+/*!
+    \variable QDBusIntrospection::ObjectTree::interfaceData
+    A map of interfaces and their names.
+*/
+
+/*!
+    \variable QDBusIntrospection::ObjectTree::childObjectData
+    A map of object paths and their data. The map key contains the relative path to the object.
+
+    Note this map contains only the child notes that do have information about the sub-object's
+    contents. If the XML data did not contain the information, only the object name will be listed
+    in childObjects, but not in childObjectData.
+*/
+
+/*!
+    \typedef QDBusIntrospection::Annotations
+    Contains a QMap of an annotation pair. The annotation's name is stored in the QMap key and
+    must be unique. The annotation's value is stored in the QMap's value and is arbitrary.
+*/
+
+/*!
+    \typedef QDBusIntrospection::Arguments
+    Contains a list of arguments to either a Method or a Signal. The arguments' order is important.
+*/
+
+/*!
+    \typedef QDBusIntrospection::Methods
+    Contains a QMap of methods and their names. The method's name is stored in the map's key and
+    is not necessarily unique. The order in which multiple methods with the same name are stored
+    in this map is undefined.
+*/
+
+/*!
+    \typedef QDBusIntrospection::Signals
+    Contains a QMap of signals and their names. The signal's name is stored in the map's key and
+    is not necessarily unique. The order in which multiple signals with the same name are stored
+    in this map is undefined.
+*/
+
+/*!
+    \typedef QDBusIntrospection::Properties
+    Contains a QMap of properties and their names. Each property must have a unique name.
+*/
+
+/*!
+    \typedef QDBusIntrospection::Interfaces
+    Contains a QMap of interfaces and their names. Each interface has a unique name.
+*/
+
+/*!
+    \typedef QDBusIntrospection::Objects
+    Contains a QMap of objects and their paths relative to their immediate parent.
+
+    \sa parseObjectTree()
+*/
+
+/*!
+    Parses the XML document fragment (given by \a xml) containing one interface.
+
+    The first element tag in this XML data must be either \<node\> or \<interface\>. If it is
+    \<node\>, then the \<interface\> tag must be a child tag of the \<node\> one.
+
+    If there are multiple interfaces in this XML data, it is undefined which one will be
+    returned.
+*/
+QDBusIntrospection::Interface
+QDBusIntrospection::parseInterface(const QString &xml)
+{
+    // be lazy
+    Interfaces ifs = parseInterfaces(xml);
+    if (ifs.isEmpty())
+        return Interface();
+
+    // return the first in map order (probably alphabetical order)
+    return *ifs.constBegin().value();
+}
+
+/*!
+    Parses the XML document fragment (given by \a xml) containing several interfaces.
+
+    If the first element tag in this document fragment is \<node\>, the interfaces parsed will
+    be those found as child elements of the \<node\> tag.
+*/
+QDBusIntrospection::Interfaces
+QDBusIntrospection::parseInterfaces(const QString &xml)
+{
+    QString null;
+    QDBusXmlParser parser(null, null, xml);
+    return parser.interfaces();
+}
+
+/*!
+    Parses the XML document fragment (given by \a xml) containing one object, found at the service
+    \a service and path \a path.
+
+    The first element tag in this document must be \<node\>. If that tag does not contain
+    a name attribute, the \a path argument will be used to determine the path of this
+    object node.
+
+    This function does not parse the interfaces contained in the node, nor sub-object's contents.
+    It will only list their names. If you need to know their contents, use parseObjectTree.
+*/
+QDBusIntrospection::Object
+QDBusIntrospection::parseObject(const QString &xml, const QString &service, const QString &path)
+{
+    QDBusXmlParser parser(service, path, xml);
+    QSharedDataPointer<QDBusIntrospection::Object> retval = parser.object();
+    if (!retval)
+        return QDBusIntrospection::Object();
+    return *retval;
+}
+
+/*!
+    Parses the XML document fragment (given by \a xml) containing one object node and returns all
+    the information about the interfaces and sub-objects, found at the service \a service and path
+    \a path.
+
+    The Objects map returned will contain the absolute path names in the key.
+*/
+QDBusIntrospection::ObjectTree
+QDBusIntrospection::parseObjectTree(const QString &xml, const QString &service, const QString &path)
+{
+    QDBusXmlParser parser(service, path, xml);
+    QSharedDataPointer<QDBusIntrospection::ObjectTree> retval = parser.objectTree();
+    if (!retval)
+        return QDBusIntrospection::ObjectTree();
+    return *retval;
+}
+
+QT_END_NAMESPACE