1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtDBus module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qdbuspendingreply.h"

    43 #include "qdbuspendingcall_p.h"

    44 #include "qdbusmetatype.h"

    45 

    46 /*!

    47     \class QDBusPendingReply

    48     \inmodule QtDBus

    49     \since 4.5

    50 

    51     \brief The QDBusPendingReply class contains the reply to an asynchronous method call

    52 

    53     The QDBusPendingReply is a template class with up to 8 template

    54     parameters. Those parameters are the types that will be used to

    55     extract the contents of the reply's data.

    56 

    57     This class is similar in functionality to QDBusReply, but with two

    58     important differences:

    59 

    60     \list

    61       \o QDBusReply accepts exactly one return type, whereas

    62          QDBusPendingReply can have from 1 to 8 types

    63       \o QDBusReply only works on already completed replies, whereas

    64          QDBusPendingReply allows one to wait for replies from pending

    65          calls

    66     \endlist

    67 

    68     Where with QDBusReply you would write:

    69 

    70     \snippet doc/src/snippets/code/src_qdbus_qdbusreply.cpp 0

    71 

    72     with QDBusPendingReply, the equivalent code (including the blocking

    73     wait for the reply) would be:

    74 

    75     \snippet doc/src/snippets/code/src.qdbus.qdbuspendingreply.cpp 0

    76 

    77     For method calls that have more than one output argument, with

    78     QDBusReply, you would write:

    79 

    80     \snippet doc/src/snippets/code/src_qdbus_qdbusreply.cpp 1

    81 

    82     whereas with QDBusPendingReply, all of the output arguments should

    83     be template parameters:

    84 

    85     \snippet doc/src/snippets/code/src.qdbus.qdbuspendingreply.cpp 2

    86 

    87     QDBusPendingReply objects can be associated with

    88     QDBusPendingCallWatcher objects, which emit signals when the reply

    89     arrives.

    90 

    91     \sa QDBusPendingCallWatcher, QDBusReply,

    92         QDBusAbstractInterface::asyncCall()

    93 */

    94 

    95 /*!

    96     \fn QDBusPendingReply::QDBusPendingReply()

    97 

    98     Creates an empty QDBusPendingReply object. Without assigning a

    99     QDBusPendingCall object to this reply, QDBusPendingReply cannot do

   100     anything. All functions return their failure values.

   101 */

   102 

   103 /*!

   104     \fn QDBusPendingReply::QDBusPendingReply(const QDBusPendingReply &other)

   105 

   106     Creates a copy of the \a other QDBusPendingReply object. Just like

   107     QDBusPendingCall and QDBusPendingCallWatcher, this QDBusPendingReply

   108     object will share the same pending call reference. All copies

   109     share the same return values.

   110 */

   111 

   112 /*!

   113     \fn QDBusPendingReply::QDBusPendingReply(const QDBusPendingCall &call)

   114 

   115     Creates a QDBusPendingReply object that will take its contents from

   116     the \a call pending asynchronous call. This QDBusPendingReply object

   117     will share the same pending call reference as \a call.

   118 */

   119 

   120 /*!

   121     \fn QDBusPendingReply::QDBusPendingReply(const QDBusMessage &message)

   122 

   123     Creates a QDBusPendingReply object that will take its contents from

   124     the message \a message. In this case, this object will be already

   125     in its finished state and the reply's contents will be accessible.

   126 

   127     \sa isFinished()

   128 */

   129 

   130 /*!

   131     \fn QDBusPendingReply &QDBusPendingReply::operator=(const QDBusPendingReply &other)

   132 

   133     Makes a copy of \a other and drops the reference to the current

   134     pending call. If the current reference is to an unfinished pending

   135     call and this is the last reference, the pending call will be

   136     canceled and there will be no way of retrieving the reply's

   137     contents, when they arrive.

   138 */

   139 

   140 /*!

   141     \fn QDBusPendingReply &QDBusPendingReply::operator=(const QDBusPendingCall &call)

   142 

   143     Makes this object take its contents from the \a call pending call

   144     and drops the reference to the current pending call. If the

   145     current reference is to an unfinished pending call and this is the

   146     last reference, the pending call will be canceled and there will

   147     be no way of retrieving the reply's contents, when they arrive.

   148 */

   149 

   150 /*!

   151     \fn QDBusPendingReply &QDBusPendingReply::operator=(const QDBusMessage &message)

   152 

   153     Makes this object take its contents from the \a message message

   154     and drops the reference to the current pending call. If the

   155     current reference is to an unfinished pending call and this is the

   156     last reference, the pending call will be canceled and there will

   157     be no way of retrieving the reply's contents, when they arrive.

   158 

   159     After this function is finished, the QDBusPendingReply object will

   160     be in its "finished" state and the \a message contents will be

   161     accessible.

   162 

   163     \sa isFinished()

   164 */

   165 

   166 /*!

   167     \fn int QDBusPendingReply::count() const

   168 

   169     Return the number of arguments the reply is supposed to have. This

   170     number matches the number of non-void template parameters in this

   171     class.

   172 

   173     If the reply arrives with a different number of arguments (or with

   174     different types), it will be transformed into an error reply

   175     indicating a bad signature.

   176 */

   177 

   178 /*!

   179     \fn QVariant QDBusPendingReply::argumentAt(int index) const

   180 

   181     Returns the argument at position \a index in the reply's

   182     contents. If the reply doesn't have that many elements, this

   183     function's return value is undefined (will probably cause an

   184     assertion failure), so it is important to verify that the

   185     processing is finished and the reply is valid.

   186 */

   187 

   188 /*!

   189     \fn Type QDBusPendingReply::argumentAt() const

   190 

   191     Returns the argument at position \c Index (which is a template

   192     parameter) cast to type \c Type. This function uses template code

   193     to determine the proper \c Type type, according to the type list

   194     used in the construction of this object.

   195 

   196     Note that, if the reply hasn't arrived, this function causes the

   197     calling thread to block until the reply is processed.

   198 */

   199 

   200 /*!

   201     \fn T1 QDBusPendingReply::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 

   214 /*!

   215     \fn QDBusPendingReply::operator T1() const

   216 

   217     Returns the first argument in this reply, cast to type \c T1 (the

   218     first template parameter of this class). This is equivalent to

   219     calling argumentAt<0>().

   220 

   221     This function is provided as a convenience, matching the

   222     QDBusReply::value() function.

   223 

   224     Note that, if the reply hasn't arrived, this function causes the

   225     calling thread to block until the reply is processed.

   226 */

   227 

   228 /*!

   229     \fn void QDBusPendingReply::waitForFinished()

   230 

   231     Suspends the execution of the calling thread until the reply is

   232     received and processed. After this function returns, isFinished()

   233     should return true, indicating the reply's contents are ready to

   234     be processed.

   235 

   236     \sa QDBusPendingCallWatcher::waitForFinished()

   237 */

   238 

   239 QDBusPendingReplyData::QDBusPendingReplyData()

   240     : QDBusPendingCall(0)         // initialize base class empty

   241 {

   242 }

   243 

   244 QDBusPendingReplyData::~QDBusPendingReplyData()

   245 {

   246 }

   247 

   248 void QDBusPendingReplyData::assign(const QDBusPendingCall &other)

   249 {

   250     QDBusPendingCall::operator=(other);

   251 }

   252 

   253 void QDBusPendingReplyData::assign(const QDBusMessage &message)

   254 {

   255     d = new QDBusPendingCallPrivate; // drops the reference to the old one

   256     d->replyMessage = message;

   257 }

   258 

   259 QVariant QDBusPendingReplyData::argumentAt(int index) const

   260 {

   261     if (d)

   262         d->waitForFinished();   // bypasses "const"

   263 

   264     Q_ASSERT_X(d && index >= 0 && index < d->replyMessage.arguments().count(),

   265                "QDBusPendingReply::argumentAt",

   266                "Index out of bounds");

   267 

   268     return d->replyMessage.arguments().at(index);

   269 }

   270 

   271 void QDBusPendingReplyData::setMetaTypes(int count, const int *types)

   272 {

   273     Q_ASSERT(d);

   274     d->setMetaTypes(count, types);

   275     d->checkReceivedSignature();

   276 }

   277