1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qdbusintrospection_p.h"
5#include "qdbusxmlparser_p.h"
6
7#ifndef QT_NO_DBUS
8
9QT_BEGIN_NAMESPACE
10
11/*!
12 \class QDBusIntrospection
13 \inmodule QtDBus
14 \brief Information about introspected objects and interfaces on D-Bus.
15 \internal
16
17 This class provides structures and methods for parsing the XML introspection data for D-Bus.
18 Normally, you don't have to use the methods provided here: QDBusInterface and QDBusObject will
19 do that for you.
20
21 But they may prove useful if the XML data was obtained through other means (like parsing a file).
22*/
23
24/*!
25 \class QDBusIntrospection::Argument
26 \inmodule QtDBus
27 \brief One argument to a D-Bus method or signal.
28
29 This struct represents one argument passed to a method or received from a method or signal in
30 D-Bus. The struct does not contain information on the direction (input or output).
31*/
32
33/*!
34 \variable QDBusIntrospection::Argument::type
35 The argument type.
36*/
37
38/*!
39 \variable QDBusIntrospection::Argument::name
40 The argument name. The argument name is optional, so this may be a null QString.
41*/
42
43/*!
44 \fn QDBusIntrospection::Argument::operator==(const Argument &other) const
45 Compares this object against \a other and return true if they are the same.
46*/
47
48/*!
49 \class QDBusIntrospection::Method
50 \inmodule QtDBus
51 \brief Information about one method.
52
53 This struct represents one method discovered through introspection. A method is composed of
54 its \a name, its input arguments, its output arguments, and, optionally, annotations. There are no
55 "in-out" arguments.
56*/
57
58/*!
59 \variable QDBusIntrospection::Method::name
60 The method's name.
61*/
62
63/*!
64 \variable QDBusIntrospection::Method::inputArgs
65 A list of the method's input arguments.
66*/
67
68/*!
69 \variable QDBusIntrospection::Method::outputArgs
70 A list of the method's output arguments (i.e., return values).
71*/
72
73/*!
74 \variable QDBusIntrospection::Method::annotations
75 The annotations associated with the method. Each annotation is a pair of strings, where the key
76 is of the same format as a D-Bus interface name. The value is arbitrary.
77*/
78
79/*!
80 \fn QDBusIntrospection::Method::operator==(const Method &other) const
81 Compares this object against \a other and return true if they are the same.
82*/
83
84/*!
85 \class QDBusIntrospection::Signal
86 \inmodule QtDBus
87 \brief Information about one signal.
88
89 This struct represents one signal discovered through introspection. A signal is composed of
90 its \a name, its output arguments, and, optionally, annotations.
91*/
92
93/*!
94 \variable QDBusIntrospection::Signal::name
95 The signal's name.
96*/
97
98/*!
99 \variable QDBusIntrospection::Signal::outputArgs
100 A list of the signal's arguments.
101*/
102
103/*!
104 \variable QDBusIntrospection::Signal::annotations
105 The annotations associated with the signal. Each annotation is a pair of strings, where the key
106 is of the same format as a D-Bus interface name. The value is arbitrary.
107*/
108
109/*!
110 \fn QDBusIntrospection::Signal::operator==(const Signal& other) const
111 Compares this object against \a other and return true if they are the same.
112*/
113
114/*!
115 \class QDBusIntrospection::Property
116 \inmodule QtDBus
117 \brief Information about one property.
118
119 This struct represents one property discovered through introspection. A property is composed of
120 its \a name, its \a type, its \a access rights, and, optionally, annotations.
121*/
122
123/*!
124 \variable QDBusIntrospection::Property::name
125 The property's name.
126*/
127
128/*!
129 \variable QDBusIntrospection::Property::type
130 The property's type.
131*/
132
133/*!
134 \enum QDBusIntrospection::Property::Access
135 The possible access rights for a property:
136 \value Read
137 \value Write
138 \value ReadWrite
139*/
140
141/*!
142 \variable QDBusIntrospection::Property::access
143 The property's access rights.
144*/
145
146/*!
147 \variable QDBusIntrospection::Property::annotations
148 The annotations associated with the property. Each annotation is a pair of strings, where the key
149 is of the same format as a D-Bus interface name. The value is arbitrary.
150*/
151
152/*!
153 \fn QDBusIntrospection::Property::operator==(const Property &other) const
154 Compares this object against \a other and return true if they are the same.
155*/
156
157/*!
158 \class QDBusIntrospection::Interface
159 \inmodule QtDBus
160 \brief Information about one interface on the bus.
161
162 Each interface on D-Bus has a unique \a name, identifying where that interface was defined.
163 Interfaces may have annotations, methods, signals and properties, but none are mandatory.
164*/
165
166/*!
167 \variable QDBusIntrospection::Interface::name
168 The interface's name.
169*/
170
171/*!
172 \variable QDBusIntrospection::Interface::introspection
173 The XML document fragment describing this interface.
174
175 If parsed again through parseInterface, the object returned should have the same contents as
176 this object.
177*/
178
179/*!
180 \variable QDBusIntrospection::Interface::annotations
181 The annotations associated with the interface. Each annotation is a pair of strings, where the key
182 is of the same format as a D-Bus interface name. The value is arbitrary.
183*/
184
185/*!
186 \variable QDBusIntrospection::Interface::methods
187 The methods available in this interface. Note that method names are not unique (i.e., methods
188 can be overloaded with multiple arguments types).
189*/
190
191/*!
192 \variable QDBusIntrospection::Interface::signals_
193 The signals available in this interface. Note that signal names are not unique (i.e., signals
194 can be overloaded with multiple argument types).
195
196 This member is called "signals_" because "signals" is a reserved keyword in Qt.
197*/
198
199/*!
200 \variable QDBusIntrospection::Interface::properties
201 The properties available in this interface. Property names are unique.
202*/
203
204/*!
205 \fn QDBusIntrospection::Interface::operator==(const Interface &other) const
206 Compares this object against \a other and return true if they are the same.
207
208 Note that two interfaces are considered to be the same if they have the same name. The internal
209 structures in the objects are not compared.
210*/
211
212/*!
213 \class QDBusIntrospection::Object
214 \inmodule QtDBus
215 \brief Information about one object on the bus.
216
217 An object on the D-Bus bus is represented by its service and path on the service but, unlike
218 interfaces, objects are mutable. That is, their contents can change with time. Therefore,
219 while the (service, path) pair uniquely identifies an object, the information contained in
220 this struct may no longer represent the object.
221
222 An object can contain interfaces and child (sub) objects.
223*/
224
225/*!
226 \variable QDBusIntrospection::Object::service
227 The object's service name.
228
229 \sa parseObject()
230*/
231
232/*!
233 \variable QDBusIntrospection::Object::path
234 The object's path on the service. This is an absolute path.
235
236 \sa parseObject()
237*/
238
239/*!
240 \variable QDBusIntrospection::Object::interfaces
241 The list of interface names in this object.
242*/
243
244/*!
245 \variable QDBusIntrospection::Object::childObjects
246 The list of child object names in this object. Note that this is a relative name, not an
247 absolute path. To obtain the absolute path, concatenate with \l
248 {QDBusIntrospection::Object::path}{path}.
249*/
250
251/*!
252 \typedef QDBusIntrospection::Annotations
253 Contains a QMap of an annotation pair. The annotation's name is stored in the QMap key and
254 must be unique. The annotation's value is stored in the QMap's value and is arbitrary.
255*/
256
257/*!
258 \typedef QDBusIntrospection::Arguments
259 Contains a list of arguments to either a Method or a Signal. The arguments' order is important.
260*/
261
262/*!
263 \typedef QDBusIntrospection::Methods
264 Contains a QMap of methods and their names. The method's name is stored in the map's key and
265 is not necessarily unique. The order in which multiple methods with the same name are stored
266 in this map is undefined.
267*/
268
269/*!
270 \typedef QDBusIntrospection::Signals
271 Contains a QMap of signals and their names. The signal's name is stored in the map's key and
272 is not necessarily unique. The order in which multiple signals with the same name are stored
273 in this map is undefined.
274*/
275
276/*!
277 \typedef QDBusIntrospection::Properties
278 Contains a QMap of properties and their names. Each property must have a unique name.
279*/
280
281/*!
282 \typedef QDBusIntrospection::Interfaces
283 Contains a QMap of interfaces and their names. Each interface has a unique name.
284*/
285
286/*!
287 \typedef QDBusIntrospection::Objects
288 Contains a QMap of objects and their paths relative to their immediate parent.
289*/
290
291/*!
292 Parses the XML document fragment (given by \a xml) containing one interface.
293
294 The first element tag in this XML data must be either \<node\> or \<interface\>. If it is
295 \<node\>, then the \<interface\> tag must be a child tag of the \<node\> one.
296
297 If there are multiple interfaces in this XML data, it is undefined which one will be
298 returned.
299*/
300QDBusIntrospection::Interface
301QDBusIntrospection::parseInterface(const QString &xml)
302{
303 // be lazy
304 Interfaces ifs = parseInterfaces(xml);
305 if (ifs.isEmpty())
306 return Interface();
307
308 // return the first in map order (probably alphabetical order)
309 return *ifs.constBegin().value();
310}
311
312/*!
313 Parses the XML document fragment (given by \a xml) containing several interfaces.
314
315 If the first element tag in this document fragment is \<node\>, the interfaces parsed will
316 be those found as child elements of the \<node\> tag.
317*/
318QDBusIntrospection::Interfaces
319QDBusIntrospection::parseInterfaces(const QString &xml)
320{
321 QString null;
322 QDBusXmlParser parser(null, null, xml);
323 return parser.interfaces();
324}
325
326/*!
327 Parses the XML document fragment (given by \a xml) containing one object, found at the service
328 \a service and path \a path.
329
330 The first element tag in this document must be \<node\>. If that tag does not contain
331 a name attribute, the \a path argument will be used to determine the path of this
332 object node.
333
334 This function does not parse the interfaces contained in the node, nor sub-object's contents.
335 It will only list their names.
336*/
337QDBusIntrospection::Object
338QDBusIntrospection::parseObject(const QString &xml, const QString &service, const QString &path)
339{
340 QDBusXmlParser parser(service, path, xml);
341 QSharedDataPointer<QDBusIntrospection::Object> retval = parser.object();
342 if (!retval)
343 return QDBusIntrospection::Object();
344 return *retval;
345}
346
347QT_END_NAMESPACE
348
349#endif // QT_NO_DBUS
350

source code of qtbase/src/dbus/qdbusintrospection.cpp