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

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