1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtDBus module of the Qt Toolkit.
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.
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.
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.
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.
40 ****************************************************************************/
42 #include "qdbusmessage.h"
43 #include "qdbusconnection.h"
44 #include "qdbusabstractadaptor.h"
46 #include "qdbuscontext.h"
47 #include "qdbuscontext_p.h"
53 QDBusContextPrivate *QDBusContextPrivate::set(QObject *obj, QDBusContextPrivate *newContext)
55 // determine if this is an adaptor or not
56 if (qobject_cast<QDBusAbstractAdaptor *>(obj))
61 void *ptr = obj->qt_metacast("QDBusContext");
62 QDBusContext *q_ptr = reinterpret_cast<QDBusContext *>(ptr);
64 QDBusContextPrivate *old = q_ptr->d_ptr;
65 q_ptr->d_ptr = newContext;
77 \brief The QDBusContext class allows slots to determine the D-Bus context of the calls.
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.
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)}.
89 QDBusContext is used by subclassing it from the objects being
90 exported using QDBusConnection::registerObject(). The following
91 example illustrates the usage:
93 \snippet code/src_qdbus_qdbuscontext.cpp 0
95 The example illustrates the two typical uses, that of sending
96 error replies and that of delayed replies.
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
106 Constructs an empty QDBusContext.
108 QDBusContext::QDBusContext()
116 QDBusContext::~QDBusContext()
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
125 Accessing those functions when this function returns false is
126 undefined and may lead to crashes.
128 bool QDBusContext::calledFromDBus() const
134 Returns the connection from which this call was received.
136 QDBusConnection QDBusContext::connection() const
138 return d_ptr->connection;
142 Returns the message that generated this call.
144 const QDBusMessage &QDBusContext::message() const
146 return d_ptr->message;
150 Returns true if this call will have a delayed reply.
152 \sa setDelayedReply()
154 bool QDBusContext::isDelayedReply() const
156 return message().isDelayedReply();
160 Sets whether this call will have a delayed reply or not.
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.
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
171 Failing to send a reply will result in an automatic timeout error
172 being generated by D-Bus.
174 void QDBusContext::setDelayedReply(bool enable) const
176 message().setDelayedReply(enable);
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.
183 If an error is sent, the return value and any output parameters
184 from the called slot will be ignored by QtDBus.
186 void QDBusContext::sendErrorReply(const QString &name, const QString &msg) const
188 setDelayedReply(true);
189 connection().send(message().createErrorReply(name, msg));
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.
197 If an error is sent, the return value and any output parameters
198 from the called slot will be ignored by QtDBus.
200 void QDBusContext::sendErrorReply(QDBusError::ErrorType type, const QString &msg) const
202 setDelayedReply(true);
203 connection().send(message().createErrorReply(type, msg));