1// Copyright (C) 2016 The Qt Company Ltd.
2// Copyright (C) 2016 Intel Corporation.
3// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
4// Qt-Security score:significant reason:default
5
6#include "qdbuspendingreply.h"
7#include "qdbuspendingcall_p.h"
8#include "qdbusmetatype.h"
9
10#include <QtCore/private/qlocking_p.h>
11
12#ifndef QT_NO_DBUS
13
14/*!
15 \class QDBusPendingReply
16 \inmodule QtDBus
17 \since 4.5
18
19 \brief The QDBusPendingReply class contains the reply to an asynchronous method call.
20
21 The QDBusPendingReply is a variadic template class. The template parameters
22 are the types that will be used to extract the contents of the reply's data.
23
24 This class is similar in functionality to QDBusReply, but with two
25 important differences:
26
27 \list
28 \li QDBusReply accepts exactly one return type, whereas
29 QDBusPendingReply can have any number of types
30 \li QDBusReply only works on already completed replies, whereas
31 QDBusPendingReply allows one to wait for replies from pending
32 calls
33 \endlist
34
35 Where with QDBusReply you would write:
36
37 \snippet code/src_qdbus_qdbusreply.cpp 0
38
39 with QDBusPendingReply, the equivalent code (including the blocking
40 wait for the reply) would be:
41
42 \snippet code/src_qdbus_qdbuspendingreply.cpp 0
43
44 For method calls that have more than one output argument, with
45 QDBusReply, you would write:
46
47 \snippet code/src_qdbus_qdbusreply.cpp 1
48
49 whereas with QDBusPendingReply, all of the output arguments should
50 be template parameters:
51
52 \snippet code/src_qdbus_qdbuspendingreply.cpp 2
53
54 QDBusPendingReply objects can be associated with
55 QDBusPendingCallWatcher objects, which emit signals when the reply
56 arrives.
57
58 \sa QDBusPendingCallWatcher, QDBusReply
59*/
60
61/*!
62 \fn template<typename... Types> QDBusPendingReply<Types...>::QDBusPendingReply()
63
64 Creates an empty QDBusPendingReply object. Without assigning a
65 QDBusPendingCall object to this reply, QDBusPendingReply cannot do
66 anything. All functions return their failure values.
67*/
68
69/*!
70 \fn template<typename... Types> QDBusPendingReply<Types...>::QDBusPendingReply(const QDBusPendingReply &other)
71
72 Creates a copy of the \a other QDBusPendingReply object. Just like
73 QDBusPendingCall and QDBusPendingCallWatcher, this QDBusPendingReply
74 object will share the same pending call reference. All copies
75 share the same return values.
76*/
77
78/*!
79 \fn template<typename... Types> QDBusPendingReply<Types...>::QDBusPendingReply(QDBusPendingReply &&other)
80 \since 6.10
81
82 Moves-constructs a new QDBusPendingReply from \a other.
83*/
84
85/*!
86 \fn template<typename... Types> QDBusPendingReply<Types...>::QDBusPendingReply(const QDBusPendingCall &call)
87
88 Creates a QDBusPendingReply object that will take its contents from
89 the \a call pending asynchronous call. This QDBusPendingReply object
90 will share the same pending call reference as \a call.
91*/
92
93/*!
94 \fn template<typename... Types> QDBusPendingReply<Types...>::QDBusPendingReply(const QDBusMessage &message)
95
96 Creates a QDBusPendingReply object that will take its contents from
97 the message \a message. In this case, this object will be already
98 in its finished state and the reply's contents will be accessible.
99
100 \sa isFinished()
101*/
102
103/*!
104 \fn template<typename... Types> QDBusPendingReply &QDBusPendingReply<Types...>::operator=(const QDBusPendingReply &other)
105
106 Makes a copy of \a other and drops the reference to the current
107 pending call. If the current reference is to an unfinished pending
108 call and this is the last reference, the pending call will be
109 canceled and there will be no way of retrieving the reply's
110 contents, when they arrive.
111*/
112
113/*!
114 \fn template<typename... Types> QDBusPendingReply &QDBusPendingReply<Types...>::operator=(QDBusPendingReply &&other)
115 \since 6.10
116
117 Move-assigns \a other to this QDBusPendingReply instance and drops
118 the reference to the current pending call. If the current reference
119 is to an unfinished pending call and this is the last reference, the
120 pending call will be canceled and there will be no way of retrieving
121 the reply's contents, when they arrive.
122*/
123
124/*!
125 \fn template<typename... Types> QDBusPendingReply &QDBusPendingReply<Types...>::operator=(const QDBusPendingCall &call)
126
127 Makes this object take its contents from the \a call pending call
128 and drops the reference to the current pending call. If the
129 current reference is to an unfinished pending call and this is the
130 last reference, the pending call will be canceled and there will
131 be no way of retrieving the reply's contents, when they arrive.
132*/
133
134/*!
135 \fn template<typename... Types> QDBusPendingReply &QDBusPendingReply<Types...>::operator=(const QDBusMessage &message)
136
137 Makes this object take its contents from the \a message message
138 and drops the reference to the current pending call. If the
139 current reference is to an unfinished pending call and this is the
140 last reference, the pending call will be canceled and there will
141 be no way of retrieving the reply's contents, when they arrive.
142
143 After this function is finished, the QDBusPendingReply object will
144 be in its "finished" state and the \a message contents will be
145 accessible.
146
147 \sa isFinished()
148*/
149
150/*!
151 \enum QDBusPendingReply::anonymous
152
153 \value Count The number of arguments the reply is expected to have
154 */
155
156/*!
157 \fn template<typename... Types> int QDBusPendingReply<Types...>::count() const
158
159 Return the number of arguments the reply is supposed to have. This
160 number matches the number of non-void template parameters in this
161 class.
162
163 If the reply arrives with a different number of arguments (or with
164 different types), it will be transformed into an error reply
165 indicating a bad signature.
166*/
167
168/*!
169 \fn template<typename... Types> QVariant QDBusPendingReply<Types...>::argumentAt(int index) const
170
171 Returns the argument at position \a index in the reply's
172 contents. If the reply doesn't have that many elements, this
173 function's return value is undefined (will probably cause an
174 assertion failure), so it is important to verify that the
175 processing is finished and the reply is valid.
176
177 If the reply does not contain an argument at position \a index or if the
178 reply was an error, this function returns an invalid QVariant. Since D-Bus
179 messages can never contain invalid QVariants, this return can be used to
180 detect an error condition.
181*/
182
183/*!
184 \fn template<typename... Types> typename Select<0>::Type QDBusPendingReply<Types...>::value() const
185
186 Returns the first argument in this reply, cast to type \c Types[0] (the
187 first template parameter of this class). This is equivalent to
188 calling argumentAt<0>().
189
190 This function is provided as a convenience, matching the
191 QDBusReply::value() function.
192
193 Note that, if the reply hasn't arrived, this function causes the
194 calling thread to block until the reply is processed.
195
196 If the reply is an error reply, this function returns a default-constructed
197 \c Types[0] object, which may be indistinguishable from a valid value. To
198 reliably determine whether the message was an error, use isError().
199*/
200
201/*!
202 \fn template<typename... Types> QDBusPendingReply<Types...>::operator typename Select<0>::Type() const
203
204 Returns the first argument in this reply, cast to type \c Types[0] (the
205 first template parameter of this class). This is equivalent to
206 calling argumentAt<0>().
207
208 This function is provided as a convenience, matching the
209 QDBusReply::value() function.
210
211 Note that, if the reply hasn't arrived, this function causes the
212 calling thread to block until the reply is processed.
213
214 If the reply is an error reply, this function returns a default-constructed
215 \c Types[0] object, which may be indistinguishable from a valid value. To
216 reliably determine whether the message was an error, use isError().
217*/
218
219/*!
220 \fn template<typename... Types> void QDBusPendingReply<Types...>::waitForFinished()
221
222 Suspends the execution of the calling thread until the reply is
223 received and processed. After this function returns, isFinished()
224 should return true, indicating the reply's contents are ready to
225 be processed.
226
227 \sa QDBusPendingCallWatcher::waitForFinished()
228*/
229
230QDBusPendingReplyBase::QDBusPendingReplyBase()
231 : QDBusPendingCall(nullptr) // initialize base class empty
232{
233}
234
235#if QT_VERSION < QT_VERSION_CHECK(7, 0, 0)
236QDBusPendingReplyBase::~QDBusPendingReplyBase()
237{
238}
239#endif
240
241void QDBusPendingReplyBase::assign(const QDBusPendingCall &other)
242{
243 QDBusPendingCall::operator=(other);
244}
245
246void QDBusPendingReplyBase::assign(const QDBusMessage &message)
247{
248 d = new QDBusPendingCallPrivate(QDBusMessage(), nullptr); // drops the reference to the old one
249 d->replyMessage = message;
250}
251
252QVariant QDBusPendingReplyBase::argumentAt(int index) const
253{
254 if (!d)
255 return QVariant();
256
257 d->waitForFinished(); // bypasses "const"
258
259 return d->replyMessage.arguments().value(i: index);
260}
261
262void QDBusPendingReplyBase::setMetaTypes(int count, const QMetaType *types)
263{
264 Q_ASSERT(d);
265 const auto locker = qt_scoped_lock(mutex&: d->mutex);
266 d->setMetaTypes(count, types);
267 d->checkReceivedSignature();
268}
269
270#endif // QT_NO_DBUS
271

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