src/dbus/qdbuscontext.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2010 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 "qdbusmessage.h"
  43 #include "qdbusconnection.h"
  44 #include "qdbusabstractadaptor.h"
  45
  46 #include "qdbuscontext.h"
  47 #include "qdbuscontext_p.h"
  48
  49 QT_BEGIN_NAMESPACE
  50
  51 QDBusContextPrivate *QDBusContextPrivate::set(QObject *obj, QDBusContextPrivate *newContext)
  52 {
  53     // determine if this is an adaptor or not
  54     if (qobject_cast<QDBusAbstractAdaptor *>(obj))
  55         obj = obj->parent();
  56
  57     Q_ASSERT(obj);
  58
  59     void *ptr = obj->qt_metacast("QDBusContext");
  60     QDBusContext *q_ptr = reinterpret_cast<QDBusContext *>(ptr);
  61     if (q_ptr) {
  62         QDBusContextPrivate *old = q_ptr->d_ptr;
  63         q_ptr->d_ptr = newContext;
  64         return old;
  65     }
  66
  67     return 0;
  68 }
  69
  70 /*!
  71     \since 4.3
  72     \class QDBusContext
  73     \inmodule QtDBus
  74
  75     \brief The QDBusContext class allows slots to determine the D-Bus context of the calls.
  76
  77     When a slot is called in an object due to a signal delivery or due
  78     to a remote method call, it is sometimes necessary to know the
  79     context in which that happened. In particular, if the slot
  80     determines that it wants to send the reply at a later opportunity
  81     or if it wants to reply with an error, the context is needed.
  82
  83     The QDBusContext class is an alternative to accessing the context
  84     that doesn't involve modifying the code generated by the \l
  85     {QtDBus XML Compiler (qdbusxml2cpp)}.
  86
  87     QDBusContext is used by subclassing it from the objects being
  88     exported using QDBusConnection::registerObject(). The following
  89     example illustrates the usage:
  90
  91     \snippet doc/src/snippets/code/src_qdbus_qdbuscontext.cpp 0
  92
  93     The example illustrates the two typical uses, that of sending
  94     error replies and that of delayed replies.
  95
  96     Note: do not subclass QDBusContext and QDBusAbstractAdaptor at the
  97     same time. QDBusContext should appear in the real object, not the
  98     adaptor. If it's necessary from the adaptor code to determine the
  99     context, use a public inheritance and access the functions via
 100     QObject::parent().
 101 */
 102
 103 /*!
 104   Constructs an empty QDBusContext.
 105  */
 106 QDBusContext::QDBusContext()
 107     : d_ptr(0)
 108 {
 109 }
 110
 111 /*!
 112   An empty destructor.
 113  */
 114 QDBusContext::~QDBusContext()
 115 {
 116 }
 117
 118 /*!
 119     Returns true if we are processing a D-Bus call. If this function
 120     returns true, the rest of the functions in this class are
 121     available.
 122
 123     Accessing those functions when this function returns false is
 124     undefined and may lead to crashes.
 125 */
 126 bool QDBusContext::calledFromDBus() const
 127 {
 128     return d_ptr;
 129 }
 130
 131 /*!
 132     Returns the connection from which this call was received.
 133 */
 134 QDBusConnection QDBusContext::connection() const
 135 {
 136     return d_ptr->connection;
 137 }
 138
 139 /*!
 140     Returns the message that generated this call.
 141 */
 142 const QDBusMessage &QDBusContext::message() const
 143 {
 144     return d_ptr->message;
 145 }
 146
 147 /*!
 148     Returns true if this call will have a delayed reply.
 149
 150     \sa setDelayedReply()
 151 */
 152 bool QDBusContext::isDelayedReply() const
 153 {
 154     return message().isDelayedReply();
 155 }
 156
 157 /*!
 158     Sets whether this call will have a delayed reply or not.
 159
 160     If \a enable is false, QtDBus will automatically generate a reply
 161     back to the caller, if needed, as soon as the called slot returns.
 162
 163     If \a enable is true, QtDBus will not generate automatic
 164     replies. It will also ignore the return value from the slot and
 165     any output parameters. Instead, the called object is responsible
 166     for storing the incoming message and send a reply or error at a
 167     later time.
 168
 169     Failing to send a reply will result in an automatic timeout error
 170     being generated by D-Bus.
 171 */
 172 void QDBusContext::setDelayedReply(bool enable) const
 173 {
 174     message().setDelayedReply(enable);
 175 }
 176
 177 /*!
 178     Sends an error \a name as a reply to the caller. The optional \a
 179     msg parameter is a human-readable text explaining the failure.
 180
 181     If an error is sent, the return value and any output parameters
 182     from the called slot will be ignored by QtDBus.
 183 */
 184 void QDBusContext::sendErrorReply(const QString &name, const QString &msg) const
 185 {
 186     setDelayedReply(true);
 187     connection().send(message().createErrorReply(name, msg));
 188 }
 189
 190 /*!
 191     \overload
 192     Sends an error \a type as a reply to the caller. The optional \a
 193     msg parameter is a human-readable text explaining the failure.
 194
 195     If an error is sent, the return value and any output parameters
 196     from the called slot will be ignored by QtDBus.
 197 */
 198 void QDBusContext::sendErrorReply(QDBusError::ErrorType type, const QString &msg) const
 199 {
 200     setDelayedReply(true);
 201     connection().send(message().createErrorReply(type, msg));
 202 }
 203
 204 QT_END_NAMESPACE