QDBusMessage Class Reference

A message converts and transports data over D-Bus. More...

#include <qdbusmessage.h>

Public Types
enum	{ DefaultTimeout = -1, NoTimeout = INT_MAX }
	Anonymous enum for timeout constants. More...
enum	MessageType { InvalidMessage, MethodCallMessage, ReplyMessage, ErrorMessage, SignalMessage }
	D-Bus message types. More...
Public Member Functions
	QDBusMessage ()
	Creates an empty and invalid message.
	QDBusMessage (const QDBusMessage &other)
	Creates a shallow copy of the given message.
	~QDBusMessage ()
	Destroys a message.
QDBusMessage &	operator= (const QDBusMessage &other)
	Creates a shallow copy of the given message.
QString	path () const
	Returns the message's object path.
QString	interface () const
	Returns the message's interface name.
QString	member () const
	Returns the message's member name.
QString	sender () const
	Returns the name of the message sender.
QDBusError	error () const
	Returns the error of an error message.
MessageType	type () const
	Returns which kind of message this is.
int	timeout () const
	Returns the message's timeout.
void	setTimeout (int ms)
	Sets the message's timeout.
int	serialNumber () const
	Returns the message's serial number.
int	replySerialNumber () const
	Returns the message's reply serial number.
DBusMessage *	toDBusMessage () const
	Creates a raw D-Bus message from this Qt3-bindings message.
Static Public Member Functions
static QDBusMessage	signal (const QString &path, const QString &interface, const QString &member)
	Creates a message for sending a D-Bus signal.
static QDBusMessage	methodCall (const QString &service, const QString &path, const QString &interface, const QString &method)
	Creates a message for sending a D-Bus method call.
static QDBusMessage	methodReply (const QDBusMessage &other)
	Creates a message for replying to a D-Bus method call.
static QDBusMessage	methodError (const QDBusMessage &other, const QDBusError &error)
	Creates a message for replying to a D-Bus method call.
static QDBusMessage	fromDBusMessage (DBusMessage *dmsg)
	Creates a Qt3-bindings message from the given raw D-Bus message.
Friends
class	QDBusConnection

Detailed Description

A message converts and transports data over D-Bus.

A QDBusMessage is implicitly shared, similar to a QString, i.e. copying a message creates just a shallow copy.

The QDBusMessage is the Qt3 bindings means of encapsulating data for a method call, a method reply or an error.

Data specifying the sender and receipient is directly accessible through getter methods, while data, e.g. method parameters or return values, are managed as a list of QDBusData.

To create a message suitable for sending use one of the static factory methods:

signal() for creating a D-Bus signal message

methodCall() for creating a D-Bus method calls to a service object

methodReply() for creating a method reply on success

methodError() for creating a method reply on error

Note:: for applications that just want to perform method calls and/or receive signals, it is usually more convenient to use QDBusProxy instead.

Message sending is achieved through QDBusConnection

Example:

   QDBusConnection con = QDBusConnection::sessionBus();

   // receipient service is the bus' main interface

   QString service   = "org.freedesktop.DBus";
   QString path      = "/org/freedesktop/DBus";
   QString interface = "org.freedesktop.DBus";

   QDBusMessage msg = QBusMessage::methodCall(service, path, interface, "ListNames");

   QDBusMessage reply = con.sendWithReply(msg);

   // awaiting for a message list

   if (reply.type() != QDBusMessage::ReplyMessage || reply.count() != 2 ||
       reply[0].type() != QDBusData::List)
   {
       // error handling here
   }
   else
   {
       QStringList list = reply[0].toQStringList();

       // reply handling here
   }

A service returning such a reply would do something like this

   bool Service::handleMethodCall(const QDBusMessage& call)
   {
       // checks for correctness, i.e. correct interface, member,
       // would usually haven been placed here

       QStringList result;
       result << "Foo" << "Bar";

       QDBusMessage reply = QDBusMessage::methodReply(call);
       reply << QDBusData::fromList(result);

       connection.send(reply);

       return true;
   }

Examples:: example-client.cpp, and example-service.cpp.

Member Enumeration Documentation

anonymous enum

Anonymous enum for timeout constants.

See also:: timeout(); setTimeout()

Enumerator:

DefaultTimeout	Use whatever D-Bus has as default timeout
NoTimeout	Use no timeout at all, i.e. wait as long as necessary

enum QDBusMessage::MessageType

D-Bus message types.

A message of a specific type can be created using the respective factory method. A message created by the default constructor becomes an InvalidMessage

See also:: type(); signal(); methodCall(); methodReply(); methodError()

Enumerator:

InvalidMessage	An invalid message cannot be sent over D-Bus. This type serves for initializing message variables without requiring a "real" message
MethodCallMessage	A message for doing method calls on remote service objects See also: methodCall()
ReplyMessage	A message for replying to a method call in case of success See also: methodReply()
ErrorMessage	A message for replying to a method call in case of failure See also: methodError()
SignalMessage	A message for emitting D-Bus signals See also: signal()

Constructor & Destructor Documentation

QDBusMessage::QDBusMessage ( )

Creates an empty and invalid message.

To create a message suitable for sending through D-Bus see the factory methods signal(), methodCall(), methodReply() and methodError()

See also:: InvalidMessage

QDBusMessage::QDBusMessage ( const QDBusMessage & other )

Creates a shallow copy of the given message.

This instance will become a handle to the same message data the other message is using, including MessageType

Parameters:

other

the message to copy

QDBusMessage::~QDBusMessage ( )

Destroys a message.

If this message handle is the last one using this respective message content, the message content will be deleted as well

Member Function Documentation

QDBusError QDBusMessage::error ( ) const

Returns the error of an error message.

If this message is of type ErrorMessage, this method can be used to retrieve the respective error object

Returns:: the transported error object. Will be empty if this is not an error message

See also:: type()

Examples:: example-client.cpp.

static QDBusMessage QDBusMessage::fromDBusMessage ( DBusMessage * dmsg ) [static]

Creates a Qt3-bindings message from the given raw D-Bus message.

De-marshalls data contained in the message to a list of QDBusData.

Note:: ownership of the given message is shared between the caller and the returned message, i.e. the message as increased the reference counter and will still have access to the raw message even if the caller "deleted" it using dbus_message_unref()

Parameters:

dmsg

a C API D-Bus message

Returns:: a Qt3 bindings message. Can be an InvalidMessage if the given message was 0 or if de-marshalling failed

QString QDBusMessage::interface ( ) const

Returns the message's interface name.

See section Interface names for details.

The context of the interface name depends on the message type:

SignalMessage: the name of the interface which emits the signal
MethodCallMessage: the name of the interface the call is sent to
ReplyMessage: the name of the interface to which the method belonged
ErrorMessage: the name of the interface to which the method belonged

Returns:: a non-empty interface name or QString::null

See also:: path(); member(); sender()

Examples:: example-service.cpp.

QString QDBusMessage::member ( ) const

Returns the message's member name.

See section Method and signal names for details.

The context of the member name depends on the message type:

SignalMessage: the name of the emitted signal
MethodCallMessage: the name of the method to call
ReplyMessage: the name of the method which replies
ErrorMessage: the name of the method which replies

Returns:: a non-empty member name or QString::null

See also:: path(); interface(); sender()

Examples:: example-client.cpp, and example-service.cpp.

static QDBusMessage QDBusMessage::methodCall	(	const QString &	service,
		const QString &	path,
		const QString &	interface,
		const QString &	method
	)			`[static]`

Creates a message for sending a D-Bus method call.

Invoking a method over D-Bus requires a message of type MethodCallMessage as well as the information where it should be sent to, e.g which interface of which object in which service. See Naming and syntax conventions in D-Bus for recommendations on those parameters.

Parameters:

	service	the D-Bus name of the application hosting the service object
	path	the object path of the service object
	interface	the object's interface to which the method belongs
	method	the method's name

Returns:: a message suitable for appending arguments and for sending

See also:: methodReply(); methodError(); QDBusConnection::send()

static QDBusMessage QDBusMessage::methodError	(	const QDBusMessage &	other,
		const QDBusError &	error
	)			`[static]`

Creates a message for replying to a D-Bus method call.

Replying to a D-Bus method call in the case of failure requires a message of type ErrorMessage as well as the information to which method call it is replying to and which error occured.

Parameters:

	other	the method call message it is replying to
	error	the error which occured during during the method call

Returns:: a message suitable for appending arguments and for sending

See also:: methodCall(); methodReply(); QDBusConnection::send()

Examples:: example-service.cpp.

static QDBusMessage QDBusMessage::methodReply ( const QDBusMessage & other ) [static]

Creates a message for replying to a D-Bus method call.

Replying to a D-Bus method call in the case of success requires a message of type ReplyMessage as well as the information to which method call it is replying to.

Parameters:

other

the method call message it is replying to

Returns:: a message suitable for appending arguments and for sending

See also:: methodCall(); methodError(); QDBusConnection::send()

Examples:: example-service.cpp.

QDBusMessage& QDBusMessage::operator= ( const QDBusMessage & other )

Creates a shallow copy of the given message.

This instance will become a handle to the same message data the other message is usingm including MessageType

Any content used in this instance will be deleted if this instance was the last handle using that content

Parameters:

other

the message to copy

Returns:: a reference to this instance as required by assignment operator semantics

QString QDBusMessage::path ( ) const

Returns the message's object path.

See section Object paths for details.

The context of the object path depends on the message type:

SignalMessage: the path of the service object which emits the signal
MethodCallMessage: the path of the service object the call is sent to
ReplyMessage: the path of the object which is replying
ErrorMessage: the path of the object which is replying

Returns:: a non-empty object path or QString::null

See also:: interface(); member(); sender()

int QDBusMessage::replySerialNumber ( ) const

Returns the message's reply serial number.

The reply serial number is the serial number of the method call message this message is a reply to.

If this is neither a message of type ReplyMessage or ErrorMessage, the returned value will be 0

It can be used to associate a reply or error message with a method call message.

Returns:: the serial number of the associated method call message or 0 if this message is not a reply message

See also:: serialNumber(); methodReply(); methodError(); QDBusConnection::sendWithAsyncReply(); QDBusProxy::sendWithAsyncReply()

QString QDBusMessage::sender ( ) const

Returns the name of the message sender.

The message sender name or address used on the D-Bus message bus to refer to the application which sent this message.

See section Service names for details.

This can either be a unique name as handed out by the bus, see QDBusConnection::uniqueName() or a name registered with QDBusConnection::requestName()

Returns:: a non-empty D-Bus sender name or QString::null

See also:: path(); interface(); member()

int QDBusMessage::serialNumber ( ) const

Returns the message's serial number.

The serial number is some kind of short term identifier for messages travelling the same connection.

It can be used to associate a reply or error message with a method call message.

Returns:: the message's serial number or 0 if the message hasn't been send yets

See also:: replySerialNumber()

void QDBusMessage::setTimeout ( int ms )

Sets the message's timeout.

The timeout is the number of milliseconds the D-Bus connection will wait for the reply of an asynchronous call.

If no reply is received in time, an error message will be delivered to the asynchronous reply receiver.

If no timeout is set explicitly, DefaultTimeout is assumed, which is usually the best option

Returns:: the asynchronous wait timeout in milliseconds

Parameters:

ms

timeout in milliseconds

See also:: timeout(); DefaultTimeout; NoTimeout

static QDBusMessage QDBusMessage::signal	(	const QString &	path,
		const QString &	interface,
		const QString &	member
	)			`[static]`

Creates a message for sending a D-Bus signal.

Sending/emitting a signal over D-Bus requires a message of type SignalMessage as well as the information where it is coming from, i.e. which interface of which object is sending it. See Naming and syntax conventions in D-Bus for recommendations on those parameters.

Parameters:

	path	the object path of the service object
	interface	the object's interface to which the signal belongs
	member	the signal's name

Returns:: a message suitable for appending arguments and for sending

See also:: QDBusConnection::send()

int QDBusMessage::timeout ( ) const

Returns the message's timeout.

Returns:: the asynchronous wait timeout in milliseconds

See also:: setTimeout()

DBusMessage* QDBusMessage::toDBusMessage ( ) const

Creates a raw D-Bus message from this Qt3-bindings message.

Marshalls data contained in the message's value list into D-Bus data format and creates a low level API D-Bus message for it.

Note:: ownership of the returned message is transferred to the caller, i.e. it has to be deleted using dbus_message_unref()

Returns:: a C API D-Bus message or 0 if this is an InvalidMessage or marshalling failed

MessageType QDBusMessage::type ( ) const

Returns which kind of message this is.

Returns:: the message's type

Examples:: example-client.cpp, and example-service.cpp.

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

/data/store/work/kde/3.5/dbus-qt4-qt3backport/dbus/qdbusmessage.h

QDBusMessage Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation