src/dbus/qdbusintrospection.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtDBus module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qdbusintrospection_p.h"
  43 #include "qdbusxmlparser_p.h"
  44
  45 #ifndef QT_NO_DBUS
  46
  47 QT_BEGIN_NAMESPACE
  48
  49 /*!
  50     \class QDBusIntrospection
  51     \inmodule QtDBus
  52     \brief Information about introspected objects and interfaces on D-Bus.
  53     \internal
  54
  55     This class provides structures and methods for parsing the XML introspection data for D-Bus.
  56     Normally, you don't have to use the methods provided here: QDBusInterface and QDBusObject will
  57     do that for you.
  58
  59     But they may prove useful if the XML data was obtained through other means (like parsing a file).
  60 */
  61
  62 /*!
  63     \class QDBusIntrospection::Argument
  64     \inmodule QtDBus
  65     \brief One argument to a D-Bus method or signal.
  66
  67     This struct represents one argument passed to a method or received from a method or signal in
  68     D-Bus. The struct does not contain information on the direction (input or output).
  69 */
  70
  71 /*!
  72     \variable QDBusIntrospection::Argument::type
  73     The argument type.
  74 */
  75
  76 /*!
  77     \variable QDBusIntrospection::Argument::name
  78     The argument name. The argument name is optional, so this may be a null QString.
  79 */
  80
  81 /*!
  82     \fn QDBusIntrospection::Argument::operator==(const Argument &other) const
  83     Compares this object against \a other and return true if they are the same.
  84 */
  85
  86 /*!
  87     \class QDBusIntrospection::Method
  88     \inmodule QtDBus
  89     \brief Information about one method.
  90
  91     This struct represents one method discovered through introspection. A method is composed of
  92     its \a name, its input arguments, its output arguments, and, optionally, annotations. There are no
  93     "in-out" arguments.
  94 */
  95
  96 /*!
  97     \variable QDBusIntrospection::Method::name
  98     The method's name.
  99 */
 100
 101 /*!
 102     \variable QDBusIntrospection::Method::inputArgs
 103     A list of the method's input arguments.
 104 */
 105
 106 /*!
 107     \variable QDBusIntrospection::Method::outputArgs
 108     A list of the method's output arguments (i.e., return values).
 109 */
 110
 111 /*!
 112     \variable QDBusIntrospection::Method::annotations
 113     The annotations associated with the method. Each annotation is a pair of strings, where the key
 114     is of the same format as a D-Bus interface name. The value is arbitrary.
 115 */
 116
 117 /*!
 118     \fn QDBusIntrospection::Method::operator==(const Method &other) const
 119     Compares this object against \a other and return true if they are the same.
 120 */
 121
 122 /*!
 123     \class QDBusIntrospection::Signal
 124     \inmodule QtDBus
 125     \brief Information about one signal.
 126
 127     This struct represents one signal discovered through introspection. A signal is composed of
 128     its \a name, its output arguments, and, optionally, annotations.
 129 */
 130
 131 /*!
 132     \variable QDBusIntrospection::Signal::name
 133     The signal's name.
 134 */
 135
 136 /*!
 137     \variable QDBusIntrospection::Signal::outputArgs
 138     A list of the signal's arguments.
 139 */
 140
 141 /*!
 142     \variable QDBusIntrospection::Signal::annotations
 143     The annotations associated with the signal. Each annotation is a pair of strings, where the key
 144     is of the same format as a D-Bus interface name. The value is arbitrary.
 145 */
 146
 147 /*!
 148     \fn QDBusIntrospection::Signal::operator==(const Signal& other) const
 149     Compares this object against \a other and return true if they are the same.
 150 */
 151
 152 /*!
 153     \class QDBusIntrospection::Property
 154     \inmodule QtDBus
 155     \brief Information about one property.
 156
 157     This struct represents one property discovered through introspection. A property is composed of
 158     its \a name, its \a type, its \a access rights, and, optionally, annotations.
 159 */
 160
 161 /*!
 162     \variable QDBusIntrospection::Property::name
 163     The property's name.
 164 */
 165
 166 /*!
 167     \variable QDBusIntrospection::Property::type
 168     The property's type.
 169 */
 170
 171 /*!
 172     \enum QDBusIntrospection::Property::Access
 173     The possible access rights for a property:
 174     \value Read
 175     \value Write
 176     \value ReadWrite
 177 */
 178
 179 /*!
 180     \variable QDBusIntrospection::Property::access
 181     The property's access rights.
 182 */
 183
 184 /*!
 185     \variable QDBusIntrospection::Property::annotations
 186     The annotations associated with the property. Each annotation is a pair of strings, where the key
 187     is of the same format as a D-Bus interface name. The value is arbitrary.
 188 */
 189
 190 /*!
 191     \fn QDBusIntrospection::Property::operator==(const Property &other) const
 192     Compares this object against \a other and return true if they are the same.
 193 */
 194
 195 /*!
 196     \class QDBusIntrospection::Interface
 197     \inmodule QtDBus
 198     \brief Information about one interface on the bus.
 199
 200     Each interface on D-Bus has an unique \a name, identifying where that interface was defined.
 201     Interfaces may have annotations, methods, signals and properties, but none are mandatory.
 202 */
 203
 204 /*!
 205     \variable QDBusIntrospection::Interface::name
 206     The interface's name.
 207 */
 208
 209 /*!
 210     \variable QDBusIntrospection::Interface::introspection
 211     The XML document fragment describing this interface.
 212
 213     If parsed again through parseInterface, the object returned should have the same contents as
 214     this object.
 215 */
 216
 217 /*!
 218     \variable QDBusIntrospection::Interface::annotations
 219     The annotations associated with the interface. Each annotation is a pair of strings, where the key
 220     is of the same format as a D-Bus interface name. The value is arbitrary.
 221 */
 222
 223 /*!
 224     \variable QDBusIntrospection::Interface::methods
 225     The methods available in this interface. Note that method names are not unique (i.e., methods
 226     can be overloaded with multiple arguments types).
 227 */
 228
 229 /*!
 230     \variable QDBusIntrospection::Interface::signals_
 231     The signals available in this interface. Note that signal names are not unique (i.e., signals
 232     can be overloaded with multiple argument types).
 233
 234     This member is called "signals_" because "signals" is a reserved keyword in Qt.
 235 */
 236
 237 /*!
 238     \variable QDBusIntrospection::Interface::properties
 239     The properties available in this interface. Property names are unique.
 240 */
 241
 242 /*!
 243     \fn QDBusIntrospection::Interface::operator==(const Interface &other) const
 244     Compares this object against \a other and return true if they are the same.
 245
 246     Note that two interfaces are considered to be the same if they have the same name. The internal
 247     structures in the objects are not compared.
 248 */
 249
 250 /*!
 251     \class QDBusIntrospection::Object
 252     \inmodule QtDBus
 253     \brief Information about one object on the bus.
 254
 255     An object on the D-Bus bus is represented by its service and path on the service but, unlike
 256     interfaces, objects are mutable. That is, their contents can change with time. Therefore,
 257     while the (service, path) pair uniquely identifies an object, the information contained in
 258     this struct may no longer represent the object.
 259
 260     An object can contain interfaces and child (sub) objects.
 261 */
 262
 263 /*!
 264     \variable QDBusIntrospection::Object::service
 265     The object's service name.
 266
 267     \sa parseObject(), parseObjectTree()
 268 */
 269
 270 /*!
 271     \variable QDBusIntrospection::Object::path
 272     The object's path on the service. This is an absolute path.
 273
 274     \sa parseObject(), parseObjectTree()
 275 */
 276
 277 /*!
 278     \variable QDBusIntrospection::Object::introspection
 279     The XML document fragment describing this object, its interfaces and sub-objects at the time
 280     of the parsing.
 281
 282     The result of parseObject with this XML data should be the same as the Object struct.
 283 */
 284
 285 /*!
 286     \variable QDBusIntrospection::Object::interfaces
 287     The list of interface names in this object.
 288 */
 289
 290 /*!
 291     \variable QDBusIntrospection::Object::childObjects
 292     The list of child object names in this object. Note that this is a relative name, not an
 293     absolute path. To obtain the absolute path, concatenate with \l
 294     {QDBusIntrospection::Object::path}{path}.
 295 */
 296
 297 /*!
 298     \class QDBusIntrospection::ObjectTree
 299     \inmodule QtDBus
 300     \brief Complete information about one object node and its descendency.
 301
 302     This struct contains the same data as QDBusIntrospection::Object, plus the actual data for the
 303     interfaces and child (sub) objects that was available in the XML document.
 304 */
 305
 306 /*!
 307     \variable QDBusIntrospection::ObjectTree::interfaceData
 308     A map of interfaces and their names.
 309 */
 310
 311 /*!
 312     \variable QDBusIntrospection::ObjectTree::childObjectData
 313     A map of object paths and their data. The map key contains the relative path to the object.
 314
 315     Note this map contains only the child notes that do have information about the sub-object's
 316     contents. If the XML data did not contain the information, only the object name will be listed
 317     in childObjects, but not in childObjectData.
 318 */
 319
 320 /*!
 321     \typedef QDBusIntrospection::Annotations
 322     Contains a QMap of an annotation pair. The annotation's name is stored in the QMap key and
 323     must be unique. The annotation's value is stored in the QMap's value and is arbitrary.
 324 */
 325
 326 /*!
 327     \typedef QDBusIntrospection::Arguments
 328     Contains a list of arguments to either a Method or a Signal. The arguments' order is important.
 329 */
 330
 331 /*!
 332     \typedef QDBusIntrospection::Methods
 333     Contains a QMap of methods and their names. The method's name is stored in the map's key and
 334     is not necessarily unique. The order in which multiple methods with the same name are stored
 335     in this map is undefined.
 336 */
 337
 338 /*!
 339     \typedef QDBusIntrospection::Signals
 340     Contains a QMap of signals and their names. The signal's name is stored in the map's key and
 341     is not necessarily unique. The order in which multiple signals with the same name are stored
 342     in this map is undefined.
 343 */
 344
 345 /*!
 346     \typedef QDBusIntrospection::Properties
 347     Contains a QMap of properties and their names. Each property must have a unique name.
 348 */
 349
 350 /*!
 351     \typedef QDBusIntrospection::Interfaces
 352     Contains a QMap of interfaces and their names. Each interface has a unique name.
 353 */
 354
 355 /*!
 356     \typedef QDBusIntrospection::Objects
 357     Contains a QMap of objects and their paths relative to their immediate parent.
 358
 359     \sa parseObjectTree()
 360 */
 361
 362 /*!
 363     Parses the XML document fragment (given by \a xml) containing one interface.
 364
 365     The first element tag in this XML data must be either \<node\> or \<interface\>. If it is
 366     \<node\>, then the \<interface\> tag must be a child tag of the \<node\> one.
 367
 368     If there are multiple interfaces in this XML data, it is undefined which one will be
 369     returned.
 370 */
 371 QDBusIntrospection::Interface
 372 QDBusIntrospection::parseInterface(const QString &xml)
 373 {
 374     // be lazy
 375     Interfaces ifs = parseInterfaces(xml);
 376     if (ifs.isEmpty())
 377         return Interface();
 378
 379     // return the first in map order (probably alphabetical order)
 380     return *ifs.constBegin().value();
 381 }
 382
 383 /*!
 384     Parses the XML document fragment (given by \a xml) containing several interfaces.
 385
 386     If the first element tag in this document fragment is \<node\>, the interfaces parsed will
 387     be those found as child elements of the \<node\> tag.
 388 */
 389 QDBusIntrospection::Interfaces
 390 QDBusIntrospection::parseInterfaces(const QString &xml)
 391 {
 392     QString null;
 393     QDBusXmlParser parser(null, null, xml);
 394     return parser.interfaces();
 395 }
 396
 397 /*!
 398     Parses the XML document fragment (given by \a xml) containing one object, found at the service
 399     \a service and path \a path.
 400
 401     The first element tag in this document must be \<node\>. If that tag does not contain
 402     a name attribute, the \a path argument will be used to determine the path of this
 403     object node.
 404
 405     This function does not parse the interfaces contained in the node, nor sub-object's contents.
 406     It will only list their names. If you need to know their contents, use parseObjectTree.
 407 */
 408 QDBusIntrospection::Object
 409 QDBusIntrospection::parseObject(const QString &xml, const QString &service, const QString &path)
 410 {
 411     QDBusXmlParser parser(service, path, xml);
 412     QSharedDataPointer<QDBusIntrospection::Object> retval = parser.object();
 413     if (!retval)
 414         return QDBusIntrospection::Object();
 415     return *retval;
 416 }
 417
 418 QT_END_NAMESPACE
 419
 420 #endif // QT_NO_DBUS