src/dbus/qdbuscontext.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtDBus module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  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 #ifndef QT_NO_DBUS
  50
  51 QT_BEGIN_NAMESPACE
  52
  53 QDBusContextPrivate *QDBusContextPrivate::set(QObject *obj, QDBusContextPrivate *newContext)
  54 {
  55     // determine if this is an adaptor or not
  56     if (qobject_cast<QDBusAbstractAdaptor *>(obj))
  57         obj = obj->parent();
  58
  59     Q_ASSERT(obj);
  60
  61     void *ptr = obj->qt_metacast("QDBusContext");
  62     QDBusContext *q_ptr = reinterpret_cast<QDBusContext *>(ptr);
  63     if (q_ptr) {
  64         QDBusContextPrivate *old = q_ptr->d_ptr;
  65         q_ptr->d_ptr = newContext;
  66         return old;
  67     }
  68
  69     return 0;
  70 }
  71
  72 /*!
  73     \since 4.3
  74     \class QDBusContext
  75     \inmodule QtDBus
  76
  77     \brief The QDBusContext class allows slots to determine the D-Bus context of the calls.
  78
  79     When a slot is called in an object due to a signal delivery or due
  80     to a remote method call, it is sometimes necessary to know the
  81     context in which that happened. In particular, if the slot
  82     determines that it wants to send the reply at a later opportunity
  83     or if it wants to reply with an error, the context is needed.
  84
  85     The QDBusContext class is an alternative to accessing the context
  86     that doesn't involve modifying the code generated by the \l
  87     {QtDBus XML Compiler (qdbusxml2cpp)}.
  88
  89     QDBusContext is used by subclassing it from the objects being
  90     exported using QDBusConnection::registerObject(). The following
  91     example illustrates the usage:
  92
  93     \snippet code/src_qdbus_qdbuscontext.cpp 0
  94
  95     The example illustrates the two typical uses, that of sending
  96     error replies and that of delayed replies.
  97
  98     Note: do not subclass QDBusContext and QDBusAbstractAdaptor at the
  99     same time. QDBusContext should appear in the real object, not the
 100     adaptor. If it's necessary from the adaptor code to determine the
 101     context, use a public inheritance and access the functions via
 102     QObject::parent().
 103 */
 104
 105 /*!
 106   Constructs an empty QDBusContext.
 107  */
 108 QDBusContext::QDBusContext()
 109     : d_ptr(0)
 110 {
 111 }
 112
 113 /*!
 114   An empty destructor.
 115  */
 116 QDBusContext::~QDBusContext()
 117 {
 118 }
 119
 120 /*!
 121     Returns true if we are processing a D-Bus call. If this function
 122     returns true, the rest of the functions in this class are
 123     available.
 124
 125     Accessing those functions when this function returns false is
 126     undefined and may lead to crashes.
 127 */
 128 bool QDBusContext::calledFromDBus() const
 129 {
 130     return d_ptr;
 131 }
 132
 133 /*!
 134     Returns the connection from which this call was received.
 135 */
 136 QDBusConnection QDBusContext::connection() const
 137 {
 138     return d_ptr->connection;
 139 }
 140
 141 /*!
 142     Returns the message that generated this call.
 143 */
 144 const QDBusMessage &QDBusContext::message() const
 145 {
 146     return d_ptr->message;
 147 }
 148
 149 /*!
 150     Returns true if this call will have a delayed reply.
 151
 152     \sa setDelayedReply()
 153 */
 154 bool QDBusContext::isDelayedReply() const
 155 {
 156     return message().isDelayedReply();
 157 }
 158
 159 /*!
 160     Sets whether this call will have a delayed reply or not.
 161
 162     If \a enable is false, QtDBus will automatically generate a reply
 163     back to the caller, if needed, as soon as the called slot returns.
 164
 165     If \a enable is true, QtDBus will not generate automatic
 166     replies. It will also ignore the return value from the slot and
 167     any output parameters. Instead, the called object is responsible
 168     for storing the incoming message and send a reply or error at a
 169     later time.
 170
 171     Failing to send a reply will result in an automatic timeout error
 172     being generated by D-Bus.
 173 */
 174 void QDBusContext::setDelayedReply(bool enable) const
 175 {
 176     message().setDelayedReply(enable);
 177 }
 178
 179 /*!
 180     Sends an error \a name as a reply to the caller. The optional \a
 181     msg parameter is a human-readable text explaining the failure.
 182
 183     If an error is sent, the return value and any output parameters
 184     from the called slot will be ignored by QtDBus.
 185 */
 186 void QDBusContext::sendErrorReply(const QString &name, const QString &msg) const
 187 {
 188     setDelayedReply(true);
 189     connection().send(message().createErrorReply(name, msg));
 190 }
 191
 192 /*!
 193     \overload
 194     Sends an error \a type as a reply to the caller. The optional \a
 195     msg parameter is a human-readable text explaining the failure.
 196
 197     If an error is sent, the return value and any output parameters
 198     from the called slot will be ignored by QtDBus.
 199 */
 200 void QDBusContext::sendErrorReply(QDBusError::ErrorType type, const QString &msg) const
 201 {
 202     setDelayedReply(true);
 203     connection().send(message().createErrorReply(type, msg));
 204 }
 205
 206 QT_END_NAMESPACE
 207
 208 #endif // QT_NO_DBUS