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#include <QtCore/private/qlocking_p.h>
46
47#ifndef QT_NO_DBUS
48
49/*!
50 \class QDBusPendingReply
51 \inmodule QtDBus
52 \since 4.5
53
54 \brief The QDBusPendingReply class contains the reply to an asynchronous method call.
55
56 The QDBusPendingReply is a variadic template class. The template parameters
57 are the types that will be used to extract the contents of the reply's data.
58
59 This class is similar in functionality to QDBusReply, but with two
60 important differences:
61
62 \list
63 \li QDBusReply accepts exactly one return type, whereas
64 QDBusPendingReply can have any number of types
65 \li QDBusReply only works on already completed replies, whereas
66 QDBusPendingReply allows one to wait for replies from pending
67 calls
68 \endlist
69
70 Where with QDBusReply you would write:
71
72 \snippet code/src_qdbus_qdbusreply.cpp 0
73
74 with QDBusPendingReply, the equivalent code (including the blocking
75 wait for the reply) would be:
76
77 \snippet code/src_qdbus_qdbuspendingreply.cpp 0
78
79 For method calls that have more than one output argument, with
80 QDBusReply, you would write:
81
82 \snippet code/src_qdbus_qdbusreply.cpp 1
83
84 whereas with QDBusPendingReply, all of the output arguments should
85 be template parameters:
86
87 \snippet code/src_qdbus_qdbuspendingreply.cpp 2
88
89 QDBusPendingReply objects can be associated with
90 QDBusPendingCallWatcher objects, which emit signals when the reply
91 arrives.
92
93 \sa QDBusPendingCallWatcher, QDBusReply
94*/
95
96/*!
97 \fn template<typename... Types> QDBusPendingReply<Types...>::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... Types> QDBusPendingReply<Types...>::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... Types> QDBusPendingReply<Types...>::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... Types> QDBusPendingReply<Types...>::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... Types> QDBusPendingReply &QDBusPendingReply<Types...>::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... Types> QDBusPendingReply &QDBusPendingReply<Types...>::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... Types> QDBusPendingReply &QDBusPendingReply<Types...>::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... Types> int QDBusPendingReply<Types...>::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... Types> QVariant QDBusPendingReply<Types...>::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... Types> typename Select<0>::Type QDBusPendingReply<Types...>::value() const
202
203 Returns the first argument in this reply, cast to type \c Types[0] (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 Types[0] 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... Types> QDBusPendingReply<Types...>::operator typename Select<0>::Type() const
220
221 Returns the first argument in this reply, cast to type \c Types[0] (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 Types[0] 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... Types> void QDBusPendingReply<Types...>::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
247QDBusPendingReplyBase::QDBusPendingReplyBase()
248 : QDBusPendingCall(nullptr) // initialize base class empty
249{
250}
251
252QDBusPendingReplyBase::~QDBusPendingReplyBase()
253{
254}
255
256void QDBusPendingReplyBase::assign(const QDBusPendingCall &other)
257{
258 QDBusPendingCall::operator=(other);
259}
260
261void QDBusPendingReplyBase::assign(const QDBusMessage &message)
262{
263 d = new QDBusPendingCallPrivate(QDBusMessage(), nullptr); // drops the reference to the old one
264 d->replyMessage = message;
265}
266
267QVariant QDBusPendingReplyBase::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 QDBusPendingReplyBase::setMetaTypes(int count, const QMetaType *types)
278{
279 Q_ASSERT(d);
280 const auto locker = qt_scoped_lock(d->mutex);
281 d->setMetaTypes(count, types);
282 d->checkReceivedSignature();
283}
284
285#endif // QT_NO_DBUS
286