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