TQT_DBusMessage Class Reference

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

#include <tqdbusmessage.h>

Collaboration diagram for TQT_DBusMessage:

Public Types
enum	{ DefaultTimeout = -1, NoTimeout = INT_MAX }
enum	MessageType { InvalidMessage, MethodCallMessage, ReplyMessage, ErrorMessage, SignalMessage }
Public Member Functions
	TQT_DBusMessage ()
	TQT_DBusMessage (const TQT_DBusMessage &other)
	~TQT_DBusMessage ()
TQT_DBusMessage &	operator= (const TQT_DBusMessage &other)
TQString	path () const
TQString	interface () const
TQString	member () const
TQString	sender () const
TQT_DBusError	error () const
MessageType	type () const
int	timeout () const
void	setTimeout (int ms)
int	serialNumber () const
int	replySerialNumber () const
DBusMessage *	toDBusMessage () const
Static Public Member Functions
static TQT_DBusMessage	signal (const TQString &path, const TQString &interface, const TQString &member)
static TQT_DBusMessage	methodCall (const TQString &service, const TQString &path, const TQString &interface, const TQString &method)
static TQT_DBusMessage	methodReply (const TQT_DBusMessage &other)
static TQT_DBusMessage	methodError (const TQT_DBusMessage &other, const TQT_DBusError &error)
static TQT_DBusMessage	fromDBusMessage (DBusMessage *dmsg)
Private Attributes
TQT_DBusMessagePrivate *	d
Friends
class	TQT_DBusConnection

Detailed Description

A message converts and transports data over D-Bus.

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

The TQT_DBusMessage is the TQt3 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 TQT_DBusData.

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 TQT_DBusProxy instead.

Message sending is achieved through TQT_DBusConnection

Example:

   TQT_DBusConnection con = TQT_DBusConnection::sessionBus();

   // receipient service is the bus' main interface

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

   TQT_DBusMessage msg = TQBusMessage::methodCall(service, path, interface, "ListNames");

   TQT_DBusMessage reply = con.sendWithReply(msg);

   // awaiting for a message list

   if (reply.type() != TQT_DBusMessage::ReplyMessage || reply.count() != 2 ||
       reply[0].type() != TQT_DBusData::List)
   {
       // error handling here
   }
   else
   {
       TQStringList list = reply[0].toTQStringList();

       // reply handling here
   }

A service returning such a reply would do something like this

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

       TQStringList result;
       result << "Foo" << "Bar";

       TQT_DBusMessage reply = TQT_DBusMessage::methodReply(call);
       reply << TQT_DBusData::fromList(result);

       connection.send(reply);

       return true;
   }

Definition at line 115 of file tqdbusmessage.h.

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

Definition at line 125 of file tqdbusmessage.h.

00126     {
00130         DefaultTimeout = -1,
00131 
00135         NoTimeout = INT_MAX
00136     };

enum TQT_DBusMessage::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()

Definition at line 151 of file tqdbusmessage.h.

00152     {
00157         InvalidMessage,
00158 
00164         MethodCallMessage,
00165 
00171         ReplyMessage,
00172 
00178         ErrorMessage,
00179 
00185         SignalMessage
00186     };

Constructor & Destructor Documentation

TQT_DBusMessage::TQT_DBusMessage ( )

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

Definition at line 104 of file tqdbusmessage.cpp.

References d.

00105 {
00106     d = new TQT_DBusMessagePrivate(this);
00107 }

TQT_DBusMessage::TQT_DBusMessage ( const TQT_DBusMessage & 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

Definition at line 109 of file tqdbusmessage.cpp.

References d, Atomic::ref(), and TQT_DBusMessagePrivate::ref.

00110     : TQValueList<TQT_DBusData>(other)
00111 {
00112     d = other.d;
00113     d->ref.ref();
00114 }

Here is the call graph for this function:

TQT_DBusMessage::~TQT_DBusMessage ( )

Destroys a message.

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

Definition at line 116 of file tqdbusmessage.cpp.

References d, Atomic::deref(), and TQT_DBusMessagePrivate::ref.

00117 {
00118     if (!d->ref.deref())
00119         delete d;
00120 }

Here is the call graph for this function:

Member Function Documentation

TQT_DBusError TQT_DBusMessage::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()

Definition at line 207 of file tqdbusmessage.cpp.

References d, and TQT_DBusMessagePrivate::error.

00208 {
00209     return d->error;
00210 }

Here is the caller graph for this function:

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

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

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

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 TQt3 bindings message. Can be an InvalidMessage if the given message was 0 or if de-marshalling failed

Definition at line 162 of file tqdbusmessage.cpp.

References d, TQT_DBusMessagePrivate::error, TQT_DBusMessagePrivate::interface, TQT_DBusMessagePrivate::member, TQT_DBusMarshall::messageToList(), TQT_DBusMessagePrivate::msg, TQT_DBusMessagePrivate::path, TQT_DBusMessagePrivate::sender, and TQT_DBusMessagePrivate::type.

00163 {
00164     TQT_DBusMessage message;
00165     if (!dmsg)
00166         return message;
00167 
00168     message.d->type = dbus_message_get_type(dmsg);
00169     message.d->path = TQString::fromUtf8(dbus_message_get_path(dmsg));
00170     message.d->interface = TQString::fromUtf8(dbus_message_get_interface(dmsg));
00171     message.d->member = TQString::fromUtf8(dbus_message_get_member(dmsg));
00172     message.d->sender = TQString::fromUtf8(dbus_message_get_sender(dmsg));
00173     message.d->msg = dbus_message_ref(dmsg);
00174 
00175     DBusError dbusError;
00176     dbus_error_init(&dbusError);
00177     if (dbus_set_error_from_message(&dbusError, dmsg))
00178     {
00179         message.d->error = TQT_DBusError(&dbusError);
00180     }
00181 
00182     TQT_DBusMarshall::messageToList(message, dmsg);
00183 
00184     return message;
00185 }

Here is the call graph for this function:

Here is the caller graph for this function:

TQString TQT_DBusMessage::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 TQString()

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

Definition at line 192 of file tqdbusmessage.cpp.

References d, and TQT_DBusMessagePrivate::interface.

00193 {
00194     return d->interface;
00195 }

Here is the caller graph for this function:

TQString TQT_DBusMessage::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 TQString()

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

Definition at line 197 of file tqdbusmessage.cpp.

References d, and TQT_DBusMessagePrivate::member.

00198 {
00199     return d->member;
00200 }

TQT_DBusMessage TQT_DBusMessage::methodCall	(	const TQString &	service,
		const TQString &	path,
		const TQString &	interface,
		const TQString &	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(); TQT_DBusConnection::send()

Definition at line 62 of file tqdbusmessage.cpp.

References d, TQT_DBusMessagePrivate::interface, TQT_DBusMessagePrivate::member, TQT_DBusMessagePrivate::path, TQT_DBusMessagePrivate::service, and TQT_DBusMessagePrivate::type.

00064 {
00065     TQT_DBusMessage message;
00066     message.d->type = DBUS_MESSAGE_TYPE_METHOD_CALL;
00067     message.d->service = service;
00068     message.d->path = path;
00069     message.d->interface = interface;
00070     message.d->member = method;
00071 
00072     return message;
00073 }

Here is the caller graph for this function:

TQT_DBusMessage TQT_DBusMessage::methodError	(	const TQT_DBusMessage &	other,
		const TQT_DBusError &	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(); TQT_DBusConnection::send()

Definition at line 86 of file tqdbusmessage.cpp.

References d, TQT_DBusMessagePrivate::error, TQT_DBusError::isValid(), TQT_DBusMessagePrivate::msg, TQT_DBusMessagePrivate::reply, and TQT_DBusMessagePrivate::type.

00087 {
00088     Q_ASSERT(other.d->msg);
00089 
00090     TQT_DBusMessage message;
00091     if (!error.isValid())
00092     {
00093         tqWarning("TQT_DBusMessage: error passed to methodError() is not valid!");
00094         return message;
00095     }
00096 
00097     message.d->type = DBUS_MESSAGE_TYPE_ERROR;
00098     message.d->reply = dbus_message_ref(other.d->msg);
00099     message.d->error = error;
00100 
00101     return message;
00102 }

Here is the call graph for this function:

TQT_DBusMessage TQT_DBusMessage::methodReply ( const TQT_DBusMessage & 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(); TQT_DBusConnection::send()

Definition at line 75 of file tqdbusmessage.cpp.

References d, TQT_DBusMessagePrivate::msg, TQT_DBusMessagePrivate::reply, and TQT_DBusMessagePrivate::type.

00076 {
00077     Q_ASSERT(other.d->msg);
00078 
00079     TQT_DBusMessage message;
00080     message.d->type = DBUS_MESSAGE_TYPE_METHOD_RETURN;
00081     message.d->reply = dbus_message_ref(other.d->msg);
00082 
00083     return message;
00084 }

TQT_DBusMessage & TQT_DBusMessage::operator= ( const TQT_DBusMessage & 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

Definition at line 122 of file tqdbusmessage.cpp.

References d, Atomic::deref(), Atomic::ref(), and TQT_DBusMessagePrivate::ref.

00123 {
00124     TQValueList<TQT_DBusData>::operator=(other);
00125     // FIXME-QT4 qAtomicAssign(d, other.d);
00126     if (other.d) other.d->ref.ref();
00127     TQT_DBusMessagePrivate* old = d;
00128     d = other.d;
00129     if (old && !old->ref.deref())
00130         delete old;
00131     return *this;
00132 }

Here is the call graph for this function:

TQString TQT_DBusMessage::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 TQString()

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

Definition at line 187 of file tqdbusmessage.cpp.

References d, and TQT_DBusMessagePrivate::path.

00188 {
00189     return d->path;
00190 }

Here is the caller graph for this function:

int TQT_DBusMessage::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(); TQT_DBusConnection::sendWithAsyncReply(); TQT_DBusProxy::sendWithAsyncReply()

Returns the unique serial number assigned to the message that triggered this reply message.

If this message is not a reply to another message, 0 is returned.

Definition at line 241 of file tqdbusmessage.cpp.

References d, and TQT_DBusMessagePrivate::msg.

00242 {
00243     if (!d->msg)
00244         return 0;
00245     return dbus_message_get_reply_serial(d->msg);
00246 }

Here is the caller graph for this function:

TQString TQT_DBusMessage::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 TQT_DBusConnection::uniqueName() or a name registered with TQT_DBusConnection::requestName()

Returns:: a non-empty D-Bus sender name or TQString()

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

Definition at line 202 of file tqdbusmessage.cpp.

References d, and TQT_DBusMessagePrivate::sender.

00203 {
00204     return d->sender;
00205 }

Here is the caller graph for this function:

int TQT_DBusMessage::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()

Returns the unique serial number assigned to this message or 0 if the message was not sent yet.

Definition at line 226 of file tqdbusmessage.cpp.

References d, and TQT_DBusMessagePrivate::msg.

00227 {
00228     if (!d->msg)
00229         return 0;
00230     return dbus_message_get_serial(d->msg);
00231 }

void TQT_DBusMessage::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

Definition at line 217 of file tqdbusmessage.cpp.

References d, and TQT_DBusMessagePrivate::timeout.

00218 {
00219     d->timeout = ms;
00220 }

TQT_DBusMessage TQT_DBusMessage::signal	(	const TQString &	path,
		const TQString &	interface,
		const TQString &	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:: TQT_DBusConnection::send()

Definition at line 50 of file tqdbusmessage.cpp.

References d, TQT_DBusMessagePrivate::interface, TQT_DBusMessagePrivate::member, TQT_DBusMessagePrivate::path, and TQT_DBusMessagePrivate::type.

00052 {
00053     TQT_DBusMessage message;
00054     message.d->type = DBUS_MESSAGE_TYPE_SIGNAL;
00055     message.d->path = path;
00056     message.d->interface = interface;
00057     message.d->member = member;
00058 
00059     return message;
00060 }

int TQT_DBusMessage::timeout ( ) const

Returns the message's timeout.

Returns:: the asynchronous wait timeout in milliseconds

See also:: setTimeout()

Definition at line 212 of file tqdbusmessage.cpp.

References d, and TQT_DBusMessagePrivate::timeout.

00213 {
00214     return d->timeout;
00215 }

Here is the caller graph for this function:

DBusMessage * TQT_DBusMessage::toDBusMessage ( ) const

Creates a raw D-Bus message from this TQt3-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

Definition at line 134 of file tqdbusmessage.cpp.

References d, TQT_DBusMessagePrivate::error, TQT_DBusMessagePrivate::interface, TQT_DBusMarshall::listToMessage(), TQT_DBusMessagePrivate::member, TQT_DBusError::message(), TQT_DBusError::name(), TQT_DBusMessagePrivate::path, TQT_DBusMessagePrivate::reply, TQT_DBusMessagePrivate::service, and TQT_DBusMessagePrivate::type.

00136 00137 00138 00139 00140 00141 00142 00143 00144 00145 00146 00147 00148 00149 00150 00151 00152 00153 00154     } 00155 00156 00157 00158 00159 00160 }

class="fragment">00135 { DBusMessage *msg = 0; switch (d->type) { case DBUS_MESSAGE_TYPE_METHOD_CALL: msg = dbus_message_new_method_call(d->service.utf8().data(), d->path.utf8().data(), d->interface.utf8().data(), d->member.utf8().data()); break; case DBUS_MESSAGE_TYPE_SIGNAL: msg = dbus_message_new_signal(d->path.utf8().data(), d->interface.utf8().data(), d->member.utf8().data()); break; case DBUS_MESSAGE_TYPE_METHOD_RETURN: msg = dbus_message_new_method_return(d->reply); break; case DBUS_MESSAGE_TYPE_ERROR: msg = dbus_message_new_error(d->reply, d->error.name().utf8().data(), d->error.message().utf8().data()); break; if (!msg) return 0; TQT_DBusMarshall::listToMessage(*this, msg); return msg;

Here is the call graph for this function:

Here is the caller graph for this function:

TQT_DBusMessage::MessageType TQT_DBusMessage::type ( ) const

Returns which kind of message this is.

Returns:: the message's type

Definition at line 248 of file tqdbusmessage.cpp.

References d, ErrorMessage, InvalidMessage, MethodCallMessage, ReplyMessage, SignalMessage, and TQT_DBusMessagePrivate::type.

00249 {
00250     switch (d->type) {
00251     case DBUS_MESSAGE_TYPE_METHOD_CALL:
00252         return MethodCallMessage;
00253     case DBUS_MESSAGE_TYPE_METHOD_RETURN:
00254         return ReplyMessage;
00255     case DBUS_MESSAGE_TYPE_ERROR:
00256         return ErrorMessage;
00257     case DBUS_MESSAGE_TYPE_SIGNAL:
00258         return SignalMessage;
00259     default:
00260         return InvalidMessage;
00261     }
00262 }

Friends And Related Function Documentation

friend class TQT_DBusConnection [friend]

Definition at line 117 of file tqdbusmessage.h.

Member Data Documentation

TQT_DBusMessagePrivate* TQT_DBusMessage::d [private]

Definition at line 510 of file tqdbusmessage.h.

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

TQT_DBusMessage Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation