QDBusMessage Class Reference

The QDBusMessage class represents one message sent or received over the D-Bus bus. More...

#include <qdbusmessage.h>

Public Types
enum	MessageType {   InvalidMessage, MethodCallMessage, ReplyMessage, ErrorMessage,   SignalMessage }
	The possible message types: More...

Public Functions
QList< QVariant >	arguments () const
	Returns the list of arguments that are going to be sent or were received from D-Bus. More...
bool	autoStartService () const
	Returns the auto start flag, as set by setAutoStartService(). More...
QDBusMessage	createErrorReply (const QString name, const QString &msg) const
	Constructs a new DBus message representing an error reply message, with the given name and msg. More...
QDBusMessage	createErrorReply (const QDBusError &err) const
	Constructs a new DBus message representing an error reply message, from the given error object. More...
QDBusMessage	createErrorReply (QDBusError::ErrorType type, const QString &msg) const
	Constructs a new DBus reply message for the error type type using the message msg. More...
QDBusMessage	createReply (const QList< QVariant > &arguments=QList< QVariant >()) const
	Constructs a new DBus message representing a reply, with the given arguments. More...
QDBusMessage	createReply (const QVariant &argument) const
	Constructs a new DBus message representing a reply, with the given argument. More...
QString	errorMessage () const
	Returns the human-readable message associated with the error that was received. More...
QString	errorName () const
	Returns the name of the error that was received. More...
QString	interface () const
	Returns the interface of the method being called (in the case of a method call) or of the signal being received from. More...
bool	isDelayedReply () const
	Returns the delayed reply flag, as set by setDelayedReply(). More...
bool	isReplyRequired () const
	Returns the flag that indicates if this message should see a reply or not. More...
QString	member () const
	Returns the name of the signal that was emitted or the name of the method that was called. More...
QDBusMessage &	operator<< (const QVariant &arg)
	Appends the argument arg to the list of arguments to be sent over D-Bus in a method call or signal emission. More...
QDBusMessage &	operator= (const QDBusMessage &other)
	Copies the contents of the object given by other. More...
QString	path () const
	Returns the path of the object that this message is being sent to (in the case of a method call) or being received from (for a signal). More...
	QDBusMessage ()
	Constructs an empty, invalid QDBusMessage object. More...
	QDBusMessage (const QDBusMessage &other)
	Constructs a copy of the object given by other. More...
QString	service () const
	Returns the name of the service or the bus address of the remote method call. More...
void	setArguments (const QList< QVariant > &arguments)
	Sets the arguments that are going to be sent over D-Bus to arguments. More...
void	setAutoStartService (bool enable)
	Sets the auto start flag to enable. More...
void	setDelayedReply (bool enable) const
	Sets whether the message will be replied later (if enable is true) or if an automatic reply should be generated by QtDBus (if enable is false). More...
QString	signature () const
	Returns the signature of the signal that was received or for the output arguments of a method call. More...
MessageType	type () const
	Returns the message type. More...
	~QDBusMessage ()
	Disposes of the object and frees any resources that were being held. More...

Static Public Functions
static QDBusMessage	createError (const QString &name, const QString &msg)
	Constructs a new DBus message representing an error, with the given name and msg. More...
static QDBusMessage	createError (const QDBusError &err)
	Constructs a new DBus message representing the given error. More...
static QDBusMessage	createError (QDBusError::ErrorType type, const QString &msg)
	Constructs a new DBus message for the error type type using the message msg. More...
static QDBusMessage	createMethodCall (const QString &destination, const QString &path, const QString &interface, const QString &method)
	Constructs a new DBus message representing a method call. More...
static QDBusMessage	createSignal (const QString &path, const QString &interface, const QString &name)
	Constructs a new DBus message with the given path, interface and name, representing a signal emission. More...

Properties
QDBusMessagePrivate *	d_ptr

Friends
class	QDBusMessagePrivate

Detailed Description

The QDBusMessage class represents one message sent or received over the D-Bus bus.

Attention

Module: QtDBus

Since

4.2

This object can represent any of the four different types of messages (MessageType) that can occur on the bus:

• Method calls
• Method return values
• Signal emissions
• Error codes

Objects of this type are created with the static createError(), createMethodCall() and createSignal() functions. Use the QDBusConnection::send() function to send the messages.

Definition at line 59 of file qdbusmessage.h.

Enumerations

MessageType

enum QDBusMessage::MessageType

The possible message types:

• MethodCallMessage a message representing an outgoing or incoming method call
• SignalMessage a message representing an outgoing or incoming signal emission
• ReplyMessage a message representing the return values of a method call
• ErrorMessage a message representing an error condition in response to a method call
• InvalidMessage an invalid message: this is never set on messages received from D-Bus

Enumerator
InvalidMessage
MethodCallMessage
ReplyMessage
ErrorMessage
SignalMessage

Definition at line 62 of file qdbusmessage.h.

                     {
        InvalidMessage,
        MethodCallMessage,
        ReplyMessage,
        ErrorMessage,
        SignalMessage
    };

Constructors and Destructors

QDBusMessage() [1/2]

QDBusMessage::QDBusMessage

(

)

Constructs an empty, invalid QDBusMessage object.

See also

createError(), createMethodCall(), createSignal()

Definition at line 543 of file qdbusmessage.cpp.

{
    d_ptr = new QDBusMessagePrivate;
}

QDBusMessage() [2/2]

QDBusMessage::QDBusMessage

(

const QDBusMessage &

other

)

Constructs a copy of the object given by other.

Note: QDBusMessage objects are shared. Modifications made to the copy will affect the original one as well. See setDelayedReply() for more information.

Definition at line 555 of file qdbusmessage.cpp.

{
    d_ptr = other.d_ptr;
    d_ptr->ref.ref();
}

~QDBusMessage()

QDBusMessage::~QDBusMessage

(

)

Disposes of the object and frees any resources that were being held.

Definition at line 564 of file qdbusmessage.cpp.

{
    if (!d_ptr->ref.deref())
        delete d_ptr;
}

Functions

arguments()

QList< QVariant > QDBusMessage::arguments

(

)

const

Returns the list of arguments that are going to be sent or were received from D-Bus.

Definition at line 735 of file qdbusmessage.cpp.

Referenced by QDBusPendingReplyData::argumentAt(), QIcdEngine::asyncUpdateConfigurationsSlot(), QDBusAbstractInterface::callWithArgumentList(), QIcdEngine::connectionStateSignalsSlot(), QDBusConnectionPrivate::deliverCall(), do_dbus_call(), QDBusConnectionPrivate::findMetaObject(), QDBusConnectionPrivate::getNameOwnerNoCache(), QDBusConnectionPrivate::handleSignal(), messageToScriptValue(), QDBusInterfacePrivate::metacall(), operator<<(), operator<<(), QDBusConnectionPrivate::prepareReply(), qDBusPropertyGet(), qDBusPropertyGetAll(), qDBusPropertySet(), qDBusReplyFill(), QDBusConnectionInterface::registerService(), QIcdEngine::requestUpdate(), QNetworkSessionPrivateImpl::stateChange(), and QDBusConnectionInterface::unregisterService().

{
    return d_ptr->arguments;
}

autoStartService()

bool QDBusMessage::autoStartService

(

)

const

Returns the auto start flag, as set by setAutoStartService().

By default, this flag is true, which means QtDBus will auto start a service, if it is not running already.

See also

setAutoStartService()

Since

4.7

Definition at line 714 of file qdbusmessage.cpp.

{
    return d_ptr->autoStartService;
}

createError() [1/3]

QDBusMessage QDBusMessage::createError ( const QString &  name, const QString &  msg  )

static

Constructs a new DBus message representing an error, with the given name and msg.

Definition at line 427 of file qdbusmessage.cpp.

Referenced by QDBusConnection::call(), QDBusAbstractInterface::callWithArgumentList(), QDBusPendingCallPrivate::checkReceivedSignature(), QScriptDBusMessageConstructor::createError(), createErrorReply(), QDBusPendingCall::fromError(), QDBusMessagePrivate::makeLocal(), QDBusPendingCall::operator=(), QDBusConnectionPrivate::sendWithReply(), QDBusConnectionPrivate::sendWithReplyAsync(), and QDBusConnectionPrivate::sendWithReplyLocal().

{
    QDBusMessage error;
    error.d_ptr->type = DBUS_MESSAGE_TYPE_ERROR;
    error.d_ptr->name = name;
    error.d_ptr->message = msg;

    return error;
}

createError() [2/3]

QDBusMessage QDBusMessage::createError ( const QDBusError &  err )

inlinestatic

Constructs a new DBus message representing the given error.

Definition at line 80 of file qdbusmessage.h.

    { return createError(err.name(), err.message()); }

createError() [3/3]

QDBusMessage QDBusMessage::createError ( QDBusError::ErrorType  type, const QString &  msg  )

inlinestatic

Constructs a new DBus message for the error type type using the message msg.

Returns the DBus message.

Definition at line 82 of file qdbusmessage.h.

    { return createError(QDBusError::errorString(type), msg); }

createErrorReply() [1/3]

QDBusMessage QDBusMessage::createErrorReply	(	const QString	name,
		const QString &	msg
	)		const

Constructs a new DBus message representing an error reply message, with the given name and msg.

Definition at line 486 of file qdbusmessage.cpp.

Referenced by QScriptDBusMessageConstructor::createErrorReply(), QDBusConnectionPrivate::deliverCall(), QDBusConnectionPrivate::handleObjectCall(), interfaceNotFoundError(), propertyNotFoundError(), propertyWriteReply(), and QDBusConnectionPrivate::sendError().

{
    QDBusMessage reply = QDBusMessage::createError(name, msg);
    if (d_ptr->msg)
        reply.d_ptr->reply = q_dbus_message_ref(d_ptr->msg);
    if (d_ptr->localMessage) {
        reply.d_ptr->localMessage = true;
        d_ptr->localReply = new QDBusMessage(reply); // keep an internal copy
    }

    // the reply must have a msg or be a local-loop optimization
    Q_ASSERT(reply.d_ptr->reply || reply.d_ptr->localMessage);
    return reply;
}

createErrorReply() [2/3]

QDBusMessage QDBusMessage::createErrorReply ( const QDBusError &  err ) const

inline

Constructs a new DBus message representing an error reply message, from the given error object.

Definition at line 90 of file qdbusmessage.h.

    { return createErrorReply(err.name(), err.message()); }

createErrorReply() [3/3]

QDBusMessage QDBusMessage::createErrorReply	(	QDBusError::ErrorType	type,
		const QString &	msg
	)		const

Constructs a new DBus reply message for the error type type using the message msg.

Returns the DBus message.

Definition at line 530 of file qdbusmessage.cpp.

{
    QDBusMessage msg = createErrorReply(QDBusError::errorString(atype), amsg);
    msg.d_ptr->parametersValidated = true;
    return msg;
}

createMethodCall()

QDBusMessage QDBusMessage::createMethodCall ( const QString &  service, const QString &  path, const QString &  interface, const QString &  method  )

static

Constructs a new DBus message representing a method call.

A method call always informs its destination address (service, path, interface and method).

The DBus bus allows calling a method on a given remote object without specifying the destination interface, if the method name is unique. However, if two interfaces on the remote object export the same method name, the result is undefined (one of the two may be called or an error may be returned).

When using DBus in a peer-to-peer context (i.e., not on a bus), the service parameter is optional.

The QDBusObject and QDBusInterface classes provide a simpler abstraction to synchronous method calling.

This function returns a QDBusMessage object that can be sent with QDBusConnection::call().

Definition at line 410 of file qdbusmessage.cpp.

Referenced by QDBusAbstractInterface::asyncCallWithArgumentList(), QDBusAbstractInterface::callWithArgumentList(), QDBusAbstractInterface::callWithCallback(), QScriptDBusMessageConstructor::createMethodCall(), do_dbus_call(), QDBusConnectionPrivate::findMetaObject(), QDBusConnectionPrivate::getNameOwnerNoCache(), QDBusAbstractInterfacePrivate::property(), and QDBusAbstractInterfacePrivate::setProperty().

{
    QDBusMessage message;
    message.d_ptr->type = DBUS_MESSAGE_TYPE_METHOD_CALL;
    message.d_ptr->service = service;
    message.d_ptr->path = path;
    message.d_ptr->interface = interface;
    message.d_ptr->name = method;

    return message;
}

createReply() [1/2]

QDBusMessage QDBusMessage::createReply

(

const QList< QVariant > &

arguments = QList<QVariant>()

)

const

Constructs a new DBus message representing a reply, with the given arguments.

Definition at line 465 of file qdbusmessage.cpp.

Referenced by QDBusConnectionPrivate::activateInternalFilters(), QScriptDBusMessageConstructor::createReply(), QDBusConnectionPrivate::deliverCall(), propertyWriteReply(), qDBusPropertyGet(), and qDBusPropertyGetAll().

{
    QDBusMessage reply;
    reply.setArguments(arguments);
    reply.d_ptr->type = DBUS_MESSAGE_TYPE_METHOD_RETURN;
    if (d_ptr->msg)
        reply.d_ptr->reply = q_dbus_message_ref(d_ptr->msg);
    if (d_ptr->localMessage) {
        reply.d_ptr->localMessage = true;
        d_ptr->localReply = new QDBusMessage(reply); // keep an internal copy
    }

    // the reply must have a msg or be a local-loop optimization
    Q_ASSERT(reply.d_ptr->reply || reply.d_ptr->localMessage);
    return reply;
}

createReply() [2/2]

QDBusMessage QDBusMessage::createReply ( const QVariant &  argument ) const

inline

Constructs a new DBus message representing a reply, with the given argument.

Definition at line 86 of file qdbusmessage.h.

    { return createReply(QList<QVariant>() << argument); }

createSignal()

QDBusMessage QDBusMessage::createSignal ( const QString &  path, const QString &  interface, const QString &  name  )

static

Constructs a new DBus message with the given path, interface and name, representing a signal emission.

A DBus signal is emitted from one application and is received by all applications that are listening for that signal from that interface.

The QDBusMessage object that is returned can be sent using the QDBusConnection::send() function.

Definition at line 379 of file qdbusmessage.cpp.

Referenced by QScriptDBusMessageConstructor::createSignal(), and QDBusConnectionPrivate::relaySignal().

{
    QDBusMessage message;
    message.d_ptr->type = DBUS_MESSAGE_TYPE_SIGNAL;
    message.d_ptr->path = path;
    message.d_ptr->interface = interface;
    message.d_ptr->name = name;

    return message;
}

errorMessage()

QString QDBusMessage::errorMessage

(

)

const

Returns the human-readable message associated with the error that was received.

Since

4.3

Definition at line 88 of file qdbusmessage.cpp.

Referenced by operator<<(), QDBusError::QDBusError(), and QOfonoPrimaryDataContextInterface::setProp().

{
    if (d_ptr->type == ErrorMessage) {
        if (!d_ptr->message.isEmpty())
           return d_ptr->message;
        if (!d_ptr->arguments.isEmpty())
            return d_ptr->arguments.at(0).toString();
    }
    return QString();
}

errorName()

QString QDBusMessage::errorName

(

)

const

Returns the name of the error that was received.

Definition at line 622 of file qdbusmessage.cpp.

Referenced by operator<<(), and QDBusError::QDBusError().

{
    if (d_ptr->type == ErrorMessage)
        return d_ptr->name;
    return QString();
}

interface()

QString QDBusMessage::interface

(

)

const

Returns the interface of the method being called (in the case of a method call) or of the signal being received from.

Definition at line 604 of file qdbusmessage.cpp.

Referenced by QDBusConnectionPrivate::activateObject(), QDBusConnectionPrivate::handleSignal(), messageToScriptValue(), operator<<(), QDBusConnectionPrivate::send(), QDBusConnectionPrivate::sendError(), QDBusConnectionPrivate::sendWithReply(), and QDBusConnectionPrivate::sendWithReplyAsync().

{
    return d_ptr->interface;
}

isDelayedReply()

bool QDBusMessage::isDelayedReply

(

)

const

Returns the delayed reply flag, as set by setDelayedReply().

By default, this flag is false, which means QtDBus will generate automatic replies when necessary.

Definition at line 675 of file qdbusmessage.cpp.

Referenced by QDBusConnectionPrivate::deliverCall(), QDBusContext::isDelayedReply(), and messageToScriptValue().

{
    return d_ptr->delayedReply;
}

isReplyRequired()

bool QDBusMessage::isReplyRequired

(

)

const

Returns the flag that indicates if this message should see a reply or not.

This is only meaningful for MethodCallMessage{method call messages}: any other kind of message cannot have replies and this function will always return false for them.

Definition at line 644 of file qdbusmessage.cpp.

Referenced by QDBusConnectionPrivate::deliverCall(), and messageToScriptValue().

{
    if (!d_ptr->msg)
        return d_ptr->localMessage; // if it's a local message, reply is required
    return !q_dbus_message_get_no_reply(d_ptr->msg);
}

member()

QString QDBusMessage::member

(

)

const

Returns the name of the signal that was emitted or the name of the method that was called.

Definition at line 612 of file qdbusmessage.cpp.

Referenced by QDBusConnectionPrivate::activateCall(), QDBusConnectionPrivate::activateInternalFilters(), QDBusConnectionPrivate::handleSignal(), messageToScriptValue(), operator<<(), QDBusConnectionPrivate::send(), QDBusConnectionPrivate::sendError(), QDBusConnectionPrivate::sendWithReply(), QDBusConnectionPrivate::sendWithReplyAsync(), and QDBusConnectionPrivate::sendWithReplyLocal().

{
    if (d_ptr->type != ErrorMessage)
        return d_ptr->name;
    return QString();
}

operator<<()

QDBusMessage & QDBusMessage::operator<<

(

const QVariant &

arg

)

Appends the argument arg to the list of arguments to be sent over D-Bus in a method call or signal emission.

Definition at line 745 of file qdbusmessage.cpp.

{
    // FIXME: should we detach?
    d_ptr->arguments.append(arg);
    return *this;
}

operator=()

QDBusMessage & QDBusMessage::operator=

(

const QDBusMessage &

other

)

Copies the contents of the object given by other.

Note: QDBusMessage objects are shared. Modifications made to the copy will affect the original one as well. See setDelayedReply() for more information.

Definition at line 577 of file qdbusmessage.cpp.

{
    qAtomicAssign(d_ptr, other.d_ptr);
    return *this;
}

path()

QString QDBusMessage::path

(

)

const

Returns the path of the object that this message is being sent to (in the case of a method call) or being received from (for a signal).

Definition at line 595 of file qdbusmessage.cpp.

Referenced by QDBusConnectionPrivate::activateInternalFilters(), QDBusConnectionPrivate::activateObject(), QNmDBusHelper::deviceStateChanged(), QDBusConnectionPrivate::handleObjectCall(), QDBusConnectionPrivate::handleSignal(), interfaceNotFoundError(), messageToScriptValue(), operator<<(), QOfonoDBusHelper::propertyChanged(), QConnmanDBusHelper::propertyChanged(), propertyNotFoundError(), QDBusConnectionPrivate::send(), QDBusConnectionPrivate::sendError(), QDBusConnectionPrivate::sendWithReply(), QDBusConnectionPrivate::sendWithReplyAsync(), QDBusConnectionPrivate::sendWithReplyLocal(), QNmDBusHelper::slotAccessPointAdded(), QNmDBusHelper::slotAccessPointRemoved(), QNmDBusHelper::slotPropertiesChanged(), and QNmDBusHelper::slotSettingsRemoved().

{
    return d_ptr->path;
}

service()

QString QDBusMessage::service

(

)

const

Returns the name of the service or the bus address of the remote method call.

Definition at line 586 of file qdbusmessage.cpp.

Referenced by QDBusConnectionPrivate::handleSignal(), messageToScriptValue(), operator<<(), QDBusConnectionPrivate::send(), QDBusConnectionPrivate::sendWithReply(), and QDBusConnectionPrivate::sendWithReplyAsync().

{
    return d_ptr->service;
}

setArguments()

void QDBusMessage::setArguments

(

const QList< QVariant > &

arguments

)

Sets the arguments that are going to be sent over D-Bus to arguments.

Those will be the arguments to a method call or the parameters in the signal.

See also

arguments()

Definition at line 725 of file qdbusmessage.cpp.

Referenced by QDBusAbstractInterface::asyncCallWithArgumentList(), QDBusAbstractInterface::callWithArgumentList(), QDBusAbstractInterface::callWithCallback(), createReply(), do_dbus_call(), QDBusConnectionInterface::registerService(), QDBusConnectionPrivate::relaySignal(), scriptValueToMessage(), and QDBusConnectionInterface::unregisterService().

{
    // FIXME: should we detach?
    d_ptr->arguments = arguments;
}

setAutoStartService()

void QDBusMessage::setAutoStartService

(

bool

enable

)

Sets the auto start flag to enable.

This flag only makes sense for method call messages, where it tells the D-Bus server to either auto start the service responsible for the service name, or not to auto start it.

By default this flag is true, i.e. a service is autostarted. This means:

When the service that this method call is sent to is already running, the method call is sent to it. If the service is not running yet, the D-Bus daemon is requested to autostart the service that is assigned to this service name. This is handled by .service files that are placed in a directory known to the D-Bus server. These files then each contain a service name and the path to a program that should be executed when this service name is requested.

Since

4.7

Definition at line 700 of file qdbusmessage.cpp.

{
    d_ptr->autoStartService = enable;
}

setDelayedReply()

void QDBusMessage::setDelayedReply

(

bool

enable

)

const

Sets whether the message will be replied later (if enable is true) or if an automatic reply should be generated by QtDBus (if enable is false).

In D-Bus, all method calls must generate a reply to the caller, unless the caller explicitly indicates otherwise (see isReplyRequired()). QtDBus automatically generates such replies for any slots being called, but it also allows slots to indicate whether they will take responsibility of sending the reply at a later time, after the function has finished processing.

See also

{Delayed Replies}

Definition at line 665 of file qdbusmessage.cpp.

Referenced by scriptValueToMessage(), and QDBusContext::setDelayedReply().

{
    d_ptr->delayedReply = enable;
}

signature()

QString QDBusMessage::signature

(

)

const

Returns the signature of the signal that was received or for the output arguments of a method call.

Definition at line 633 of file qdbusmessage.cpp.

Referenced by QDBusConnectionPrivate::activateCall(), QDBusConnectionPrivate::activateInternalFilters(), QDBusConnectionPrivate::findMetaObject(), QDBusConnectionPrivate::handleSignal(), messageToScriptValue(), operator<<(), QDBusConnectionPrivate::sendError(), and QDBusConnectionPrivate::sendWithReplyLocal().

{
    return d_ptr->signature;
}

type()

QDBusMessage::MessageType QDBusMessage::type

(

)

const

Returns the message type.

Definition at line 755 of file qdbusmessage.cpp.

Referenced by QDBusPendingCallWatcherHelper::emitSignals(), QDBusConnectionPrivate::findMetaObject(), QDBusPendingCall::fromCompletedCall(), QDBusConnectionPrivate::getNameOwnerNoCache(), QDBusConnectionPrivate::handleMessage(), messageToScriptValue(), QDBusInterfacePrivate::metacall(), operator<<(), QDBusPendingCall::operator=(), QDBusError::QDBusError(), QDBusPendingCallWatcher::QDBusPendingCallWatcher(), QDBusConnectionInterface::registerService(), QDBusConnectionPrivate::send(), QDBusConnectionPrivate::sendWithReply(), QDBusConnectionPrivate::sendWithReplyLocal(), QOfonoPrimaryDataContextInterface::setProp(), and QDBusConnectionInterface::unregisterService().

{
    switch (d_ptr->type) {
    case DBUS_MESSAGE_TYPE_METHOD_CALL:
        return MethodCallMessage;
    case DBUS_MESSAGE_TYPE_METHOD_RETURN:
        return ReplyMessage;
    case DBUS_MESSAGE_TYPE_ERROR:
        return ErrorMessage;
    case DBUS_MESSAGE_TYPE_SIGNAL:
        return SignalMessage;
    default:
        break;
    }
    return InvalidMessage;
}

Friends and Related Functions

QDBusMessagePrivate

friend class QDBusMessagePrivate

friend

Definition at line 118 of file qdbusmessage.h.

Properties

d_ptr

QDBusMessagePrivate* QDBusMessage::d_ptr

private

Definition at line 119 of file qdbusmessage.h.

Referenced by createError(), createErrorReply(), createMethodCall(), createReply(), createSignal(), QDBusMessagePrivate::fromDBusMessage(), QDBusMessagePrivate::isLocal(), QDBusMessagePrivate::makeLocal(), QDBusMessagePrivate::makeLocalReply(), operator=(), QDBusMessage(), QDBusMessagePrivate::setParametersValidated(), and QDBusMessagePrivate::toDBusMessage().

---

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

• /src/dbus/qdbusmessage.h
• /src/dbus/qdbusmessage.cpp