QDBusContext Class Reference

The QDBusContext class allows slots to determine the D-Bus context of the calls. More...

#include <qdbuscontext.h>

Inheritance diagram for QDBusContext:

Collaboration diagram for QDBusContext:

Public Member Functions
	QDBusContext ()
	Constructs an empty QDBusContext.
	~QDBusContext ()
	An empty destructor.
bool	calledFromDBus () const
	Returns true if we are processing a D-Bus call.
QDBusConnection	connection () const
	Returns the connection from which this call was received.
const QDBusMessage &	message () const
	Returns the message that generated this call.
bool	isDelayedReply () const
	Returns true if this call will have a delayed reply.
void	setDelayedReply (bool enable) const
	Sets whether this call will have a delayed reply or not.
void	sendErrorReply (const QString &name, const QString &msg=QString()) const
	Sends an error name as a reply to the caller.
void	sendErrorReply (QDBusError::ErrorType type, const QString &msg=QString()) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Sends an error type as a reply to the caller.

Friends
class	QDBusContextPrivate

Detailed Description

The QDBusContext class allows slots to determine the D-Bus context of the calls.

Since

4.3

\inmodule QtDBus

When a slot is called in an object due to a signal delivery or due to a remote method call, it is sometimes necessary to know the context in which that happened. In particular, if the slot determines that it wants to send the reply at a later opportunity or if it wants to reply with an error, the context is needed.

The QDBusContext class is an alternative to accessing the context that doesn't involve modifying the code generated by the \l {Qt D-Bus XML compiler (qdbusxml2cpp)}.

QDBusContext is used by subclassing it from the objects being exported using QDBusConnection::registerObject(). The following example illustrates the usage:

class MyObject: public QObject,
                protected QDBusContext
{
    Q_OBJECT
 
    QDBusConnection conn;
    QDBusMessage msg;
 
    //...
 
protected slots:
    void process();
public slots:
    void methodWithError();
    QString methodWithDelayedReply();
};
 
void MyObject::methodWithError()
{
    sendErrorReply(QDBusError::NotSupported,
                   "The method call 'methodWithError()' is not supported");
}
 
QString MyObject::methodWithDelayedReply()
{
    conn = connection();
    msg = message();
    setDelayedReply(true);
    QMetaObject::invokeMethod(this, &MyObject::process, Qt::QueuedConnection);
    return QString();
}

The example illustrates the two typical uses, that of sending error replies and that of delayed replies.

Note: do not subclass QDBusContext and QDBusAbstractAdaptor at the same time. QDBusContext should appear in the real object, not the adaptor. If it's necessary from the adaptor code to determine the context, use a public inheritance and access the functions via QObject::parent().

Definition at line 20 of file qdbuscontext.h.

Constructor & Destructor Documentation

QDBusContext()

QDBusContext::QDBusContext

(

)

Constructs an empty QDBusContext.

Definition at line 70 of file qdbuscontext.cpp.

~QDBusContext()

QDBusContext::~QDBusContext

(

)

An empty destructor.

Definition at line 78 of file qdbuscontext.cpp.

Member Function Documentation

calledFromDBus()

bool QDBusContext::calledFromDBus

(

)

const

Returns true if we are processing a D-Bus call.

If this function returns true, the rest of the functions in this class are available.

Accessing those functions when this function returns false is undefined and may lead to crashes.

Definition at line 90 of file qdbuscontext.cpp.

connection()

QDBusConnection QDBusContext::connection

(

)

const

Returns the connection from which this call was received.

Definition at line 98 of file qdbuscontext.cpp.

References QDBusContextPrivate::connection.

Referenced by MyObject::methodWithDelayedReply(), sendErrorReply(), and sendErrorReply().

Here is the caller graph for this function:

isDelayedReply()

bool QDBusContext::isDelayedReply

(

)

const

Returns true if this call will have a delayed reply.

See also

setDelayedReply()

Definition at line 116 of file qdbuscontext.cpp.

References QDBusMessage::isDelayedReply(), and message().

Here is the call graph for this function:

message()

const QDBusMessage & QDBusContext::message

(

)

const

Returns the message that generated this call.

Definition at line 106 of file qdbuscontext.cpp.

References QDBusContextPrivate::message.

Referenced by isDelayedReply(), MyObject::methodWithDelayedReply(), sendErrorReply(), sendErrorReply(), and setDelayedReply().

Here is the caller graph for this function:

sendErrorReply() [1/2]

void QDBusContext::sendErrorReply	(	const QString &	name,
		const QString &	msg = QString()
	)		const

Sends an error name as a reply to the caller.

The optional msg parameter is a human-readable text explaining the failure.

If an error is sent, the return value and any output parameters from the called slot will be ignored by Qt D-Bus.

Definition at line 148 of file qdbuscontext.cpp.

References connection(), message(), QDBusConnection::send(), and setDelayedReply().

Referenced by MyObject::methodWithError().

Here is the call graph for this function:

Here is the caller graph for this function:

sendErrorReply() [2/2]

void QDBusContext::sendErrorReply	(	QDBusError::ErrorType	type,
		const QString &	msg = QString()
	)		const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Sends an error type as a reply to the caller.

The optional msg parameter is a human-readable text explaining the failure.

If an error is sent, the return value and any output parameters from the called slot will be ignored by Qt D-Bus.

Definition at line 162 of file qdbuscontext.cpp.

References connection(), message(), QDBusConnection::send(), and setDelayedReply().

Here is the call graph for this function:

setDelayedReply()

void QDBusContext::setDelayedReply

(

bool

enable

)

const

Sets whether this call will have a delayed reply or not.

If enable is false, Qt D-Bus will automatically generate a reply back to the caller, if needed, as soon as the called slot returns.

If enable is true, Qt D-Bus will not generate automatic replies. It will also ignore the return value from the slot and any output parameters. Instead, the called object is responsible for storing the incoming message and send a reply or error at a later time.

Failing to send a reply will result in an automatic timeout error being generated by D-Bus.

Definition at line 136 of file qdbuscontext.cpp.

References message(), and QDBusMessage::setDelayedReply().

Referenced by MyObject::methodWithDelayedReply(), OrgBluezProfile1ContextInterface::NewConnection(), OrgBluezProfile1ContextInterface::RequestDisconnection(), sendErrorReply(), and sendErrorReply().

Here is the call graph for this function:

Here is the caller graph for this function:

Friends And Related Symbol Documentation

QDBusContextPrivate

friend class QDBusContextPrivate

friend

Definition at line 39 of file qdbuscontext.h.

---

The documentation for this class was generated from the following files:

• qtbase/src/dbus/qdbuscontext.h
• qtbase/src/dbus/qdbuscontext.cpp