1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtDBus module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    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 QT_BEGIN_NAMESPACE

    46 

    47 /*!

    48     \class QDBusIntrospection

    49     \brief Information about introspected objects and interfaces on D-Bus.

    50     \internal

    51 

    52     This class provides structures and methods for parsing the XML introspection data for D-Bus.

    53     Normally, you don't have to use the methods provided here: QDBusInterface and QDBusObject will

    54     do that for you.

    55 

    56     But they may prove useful if the XML data was obtained through other means (like parsing a file).

    57 */

    58 

    59 /*!

    60     \class QDBusIntrospection::Argument

    61     \brief One argument to a D-Bus method or signal.

    62 

    63     This struct represents one argument passed to a method or received from a method or signal in

    64     D-Bus. The struct does not contain information on the direction (input or output).

    65 */

    66 

    67 /*!

    68     \variable QDBusIntrospection::Argument::type

    69     The argument type.

    70 */

    71 

    72 /*!

    73     \variable QDBusIntrospection::Argument::name

    74     The argument name. The argument name is optional, so this may be a null QString.

    75 */

    76 

    77 /*!

    78     \fn QDBusIntrospection::Argument::operator==(const Argument &other) const

    79     Compares this object against \a other and return true if they are the same.

    80 */

    81 

    82 /*!

    83     \class QDBusIntrospection::Method

    84     \brief Information about one method.

    85 

    86     This struct represents one method discovered through introspection. A method is composed of

    87     its \a name, its input arguments, its output arguments, and, optionally, annotations. There are no

    88     "in-out" arguments.

    89 */

    90 

    91 /*!

    92     \variable QDBusIntrospection::Method::name

    93     The method's name.

    94 */

    95 

    96 /*!

    97     \variable QDBusIntrospection::Method::inputArgs

    98     A list of the method's input arguments.

    99 */

   100 

   101 /*!

   102     \variable QDBusIntrospection::Method::outputArgs

   103     A list of the method's output arguments (i.e., return values).

   104 */

   105 

   106 /*!

   107     \variable QDBusIntrospection::Method::annotations

   108     The annotations associated with the method. Each annotation is a pair of strings, where the key

   109     is of the same format as a D-Bus interface name. The value is arbitrary.

   110 */

   111 

   112 /*!

   113     \fn QDBusIntrospection::Method::operator==(const Method &other) const

   114     Compares this object against \a other and return true if they are the same.

   115 */

   116 

   117 /*!

   118     \class QDBusIntrospection::Signal

   119     \brief Information about one signal.

   120 

   121     This struct represents one signal discovered through introspection. A signal is composed of

   122     its \a name, its output arguments, and, optionally, annotations.

   123 */

   124 

   125 /*!

   126     \variable QDBusIntrospection::Signal::name

   127     The signal's name.

   128 */

   129 

   130 /*!

   131     \variable QDBusIntrospection::Signal::outputArgs

   132     A list of the signal's arguments.

   133 */

   134 

   135 /*!

   136     \variable QDBusIntrospection::Signal::annotations

   137     The annotations associated with the signal. Each annotation is a pair of strings, where the key

   138     is of the same format as a D-Bus interface name. The value is arbitrary.

   139 */

   140 

   141 /*!

   142     \fn QDBusIntrospection::Signal::operator==(const Signal& other) const

   143     Compares this object against \a other and return true if they are the same.

   144 */

   145 

   146 /*!

   147     \class QDBusIntrospection::Property

   148     \brief Information about one property.

   149 

   150     This struct represents one property discovered through introspection. A property is composed of

   151     its \a name, its \a type, its \a access rights, and, optionally, annotations.

   152 */

   153 

   154 /*!

   155     \variable QDBusIntrospection::Property::name

   156     The property's name.

   157 */

   158 

   159 /*!

   160     \variable QDBusIntrospection::Property::type

   161     The property's type.

   162 */

   163 

   164 /*!

   165     \enum QDBusIntrospection::Property::Access

   166     The possible access rights for a property:

   167     \value Read

   168     \value Write

   169     \value ReadWrite

   170 */

   171 

   172 /*!

   173     \variable QDBusIntrospection::Property::access

   174     The property's access rights.

   175 */

   176 

   177 /*!

   178     \variable QDBusIntrospection::Property::annotations

   179     The annotations associated with the property. Each annotation is a pair of strings, where the key

   180     is of the same format as a D-Bus interface name. The value is arbitrary.

   181 */

   182 

   183 /*!

   184     \fn QDBusIntrospection::Property::operator==(const Property &other) const

   185     Compares this object against \a other and return true if they are the same.

   186 */

   187 

   188 /*!

   189     \class QDBusIntrospection::Interface

   190     \brief Information about one interface on the bus.

   191 

   192     Each interface on D-Bus has an unique \a name, identifying where that interface was defined.

   193     Interfaces may have annotations, methods, signals and properties, but none are mandatory.

   194 */

   195 

   196 /*!

   197     \variable QDBusIntrospection::Interface::name

   198     The interface's name.

   199 */

   200 

   201 /*!

   202     \variable QDBusIntrospection::Interface::introspection

   203     The XML document fragment describing this interface.

   204 

   205     If parsed again through parseInterface, the object returned should have the same contents as

   206     this object.

   207 */

   208 

   209 /*!

   210     \variable QDBusIntrospection::Interface::annotations

   211     The annotations associated with the interface. Each annotation is a pair of strings, where the key

   212     is of the same format as a D-Bus interface name. The value is arbitrary.

   213 */

   214 

   215 /*!

   216     \variable QDBusIntrospection::Interface::methods

   217     The methods available in this interface. Note that method names are not unique (i.e., methods

   218     can be overloaded with multiple arguments types).

   219 */

   220 

   221 /*!

   222     \variable QDBusIntrospection::Interface::signals_

   223     The signals available in this interface. Note that signal names are not unique (i.e., signals

   224     can be overloaded with multiple argument types).

   225 

   226     This member is called "signals_" because "signals" is a reserved keyword in Qt.

   227 */

   228 

   229 /*!

   230     \variable QDBusIntrospection::Interface::properties

   231     The properties available in this interface. Property names are unique.

   232 */

   233 

   234 /*!

   235     \fn QDBusIntrospection::Interface::operator==(const Interface &other) const

   236     Compares this object against \a other and return true if they are the same.

   237 

   238     Note that two interfaces are considered to be the same if they have the same name. The internal

   239     structures in the objects are not compared.

   240 */

   241 

   242 /*!

   243     \class QDBusIntrospection::Object

   244     \brief Information about one object on the bus.

   245 

   246     An object on the D-Bus bus is represented by its service and path on the service but, unlike

   247     interfaces, objects are mutable. That is, their contents can change with time. Therefore,

   248     while the (service, path) pair uniquely identifies an object, the information contained in

   249     this struct may no longer represent the object.

   250 

   251     An object can contain interfaces and child (sub) objects.

   252 */

   253 

   254 /*!

   255     \variable QDBusIntrospection::Object::service

   256     The object's service name.

   257 

   258     \sa parseObject(), parseObjectTree()

   259 */

   260 

   261 /*!

   262     \variable QDBusIntrospection::Object::path

   263     The object's path on the service. This is an absolute path.

   264 

   265     \sa parseObject(), parseObjectTree()

   266 */

   267 

   268 /*!

   269     \variable QDBusIntrospection::Object::introspection

   270     The XML document fragment describing this object, its interfaces and sub-objects at the time

   271     of the parsing.

   272 

   273     The result of parseObject with this XML data should be the same as the Object struct.

   274 */

   275 

   276 /*!

   277     \variable QDBusIntrospection::Object::interfaces

   278     The list of interface names in this object.

   279 */

   280 

   281 /*!

   282     \variable QDBusIntrospection::Object::childObjects

   283     The list of child object names in this object. Note that this is a relative name, not an

   284     absolute path. To obtain the absolute path, concatenate with \l

   285     {QDBusIntrospection::Object::path}{path}.

   286 */

   287 

   288 /*!

   289     \class QDBusIntrospection::ObjectTree

   290     \brief Complete information about one object node and its descendency.

   291     

   292     This struct contains the same data as QDBusIntrospection::Object, plus the actual data for the

   293     interfaces and child (sub) objects that was available in the XML document.

   294 */

   295 

   296 /*!

   297     \variable QDBusIntrospection::ObjectTree::interfaceData

   298     A map of interfaces and their names.

   299 */

   300 

   301 /*!

   302     \variable QDBusIntrospection::ObjectTree::childObjectData

   303     A map of object paths and their data. The map key contains the relative path to the object.

   304 

   305     Note this map contains only the child notes that do have information about the sub-object's

   306     contents. If the XML data did not contain the information, only the object name will be listed

   307     in childObjects, but not in childObjectData.

   308 */

   309 

   310 /*!

   311     \typedef QDBusIntrospection::Annotations

   312     Contains a QMap of an annotation pair. The annotation's name is stored in the QMap key and

   313     must be unique. The annotation's value is stored in the QMap's value and is arbitrary.

   314 */

   315 

   316 /*!

   317     \typedef QDBusIntrospection::Arguments

   318     Contains a list of arguments to either a Method or a Signal. The arguments' order is important.

   319 */

   320 

   321 /*!

   322     \typedef QDBusIntrospection::Methods

   323     Contains a QMap of methods and their names. The method's name is stored in the map's key and

   324     is not necessarily unique. The order in which multiple methods with the same name are stored

   325     in this map is undefined.

   326 */

   327 

   328 /*!

   329     \typedef QDBusIntrospection::Signals

   330     Contains a QMap of signals and their names. The signal's name is stored in the map's key and

   331     is not necessarily unique. The order in which multiple signals with the same name are stored

   332     in this map is undefined.

   333 */

   334 

   335 /*!

   336     \typedef QDBusIntrospection::Properties

   337     Contains a QMap of properties and their names. Each property must have a unique name.

   338 */

   339 

   340 /*!

   341     \typedef QDBusIntrospection::Interfaces

   342     Contains a QMap of interfaces and their names. Each interface has a unique name.

   343 */

   344 

   345 /*!

   346     \typedef QDBusIntrospection::Objects

   347     Contains a QMap of objects and their paths relative to their immediate parent.

   348 

   349     \sa parseObjectTree()

   350 */

   351 

   352 /*!

   353     Parses the XML document fragment (given by \a xml) containing one interface.

   354 

   355     The first element tag in this XML data must be either \<node\> or \<interface\>. If it is

   356     \<node\>, then the \<interface\> tag must be a child tag of the \<node\> one.

   357 

   358     If there are multiple interfaces in this XML data, it is undefined which one will be

   359     returned.

   360 */

   361 QDBusIntrospection::Interface

   362 QDBusIntrospection::parseInterface(const QString &xml)

   363 {

   364     // be lazy

   365     Interfaces ifs = parseInterfaces(xml);

   366     if (ifs.isEmpty())

   367         return Interface();

   368 

   369     // return the first in map order (probably alphabetical order)

   370     return *ifs.constBegin().value();

   371 }

   372 

   373 /*!

   374     Parses the XML document fragment (given by \a xml) containing several interfaces.

   375 

   376     If the first element tag in this document fragment is \<node\>, the interfaces parsed will

   377     be those found as child elements of the \<node\> tag.

   378 */

   379 QDBusIntrospection::Interfaces

   380 QDBusIntrospection::parseInterfaces(const QString &xml)

   381 {

   382     QString null;

   383     QDBusXmlParser parser(null, null, xml);

   384     return parser.interfaces();

   385 }

   386 

   387 /*!

   388     Parses the XML document fragment (given by \a xml) containing one object, found at the service

   389     \a service and path \a path.

   390 

   391     The first element tag in this document must be \<node\>. If that tag does not contain

   392     a name attribute, the \a path argument will be used to determine the path of this

   393     object node.

   394 

   395     This function does not parse the interfaces contained in the node, nor sub-object's contents.

   396     It will only list their names. If you need to know their contents, use parseObjectTree.

   397 */

   398 QDBusIntrospection::Object

   399 QDBusIntrospection::parseObject(const QString &xml, const QString &service, const QString &path)

   400 {

   401     QDBusXmlParser parser(service, path, xml);

   402     QSharedDataPointer<QDBusIntrospection::Object> retval = parser.object();

   403     if (!retval)

   404         return QDBusIntrospection::Object();

   405     return *retval;

   406 }

   407 

   408 /*!

   409     Parses the XML document fragment (given by \a xml) containing one object node and returns all

   410     the information about the interfaces and sub-objects, found at the service \a service and path

   411     \a path.

   412 

   413     The Objects map returned will contain the absolute path names in the key.

   414 */

   415 QDBusIntrospection::ObjectTree

   416 QDBusIntrospection::parseObjectTree(const QString &xml, const QString &service, const QString &path)

   417 {

   418     QDBusXmlParser parser(service, path, xml);

   419     QSharedDataPointer<QDBusIntrospection::ObjectTree> retval = parser.objectTree();

   420     if (!retval)

   421         return QDBusIntrospection::ObjectTree();

   422     return *retval;

   423 }

   424 

   425 QT_END_NAMESPACE