DBus-1-TQt 1.0
Loading...
Searching...
No Matches
TQT_DBusMessage Class Reference

#include <tqdbusmessage.h>

+ Inheritance diagram for TQT_DBusMessage:
+ 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_DBusMessageoperator= (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_DBusMessagePrivated
 

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:

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:

// 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
}
Provides access to a specific D-Bus bus.
static TQT_DBusConnection sessionBus()
Gets a connection to the session bus.
TQString path() const
Returns the message's object path.

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";
reply << TQT_DBusData::fromList(result);
connection.send(reply);
return true;
}
static TQT_DBusData fromList(const TQT_DBusDataList &list)
Creates a data object for the given list.
A message converts and transports data over D-Bus.
static TQT_DBusMessage methodReply(const TQT_DBusMessage &other)
Creates a message for replying to a D-Bus method call.

Definition at line 115 of file tqdbusmessage.h.

Member Enumeration Documentation

◆ anonymous enum

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.

126 {
130 DefaultTimeout = -1,
131
135 NoTimeout = INT_MAX
136 };

◆ 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.

Constructor & Destructor Documentation

◆ TQT_DBusMessage() [1/2]

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.

105{
106 d = new TQT_DBusMessagePrivate(this);
107}
TQT_DBusMessagePrivate * d

References d.

◆ TQT_DBusMessage() [2/2]

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
otherthe message to copy

Definition at line 109 of file tqdbusmessage.cpp.

111{
112 d = other.d;
113 d->ref.ref();
114}

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

+ Here is the call graph for this function:

◆ ~TQT_DBusMessage()

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.

117{
118 if (!d->ref.deref())
119 delete d;
120}

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

+ Here is the call graph for this function:

Member Function Documentation

◆ error()

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.

208{
209 return d->error;
210}

References d, and TQT_DBusMessagePrivate::error.

+ Here is the caller graph for this function:

◆ fromDBusMessage()

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
dmsga 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.

163{
164 TQT_DBusMessage message;
165 if (!dmsg)
166 return message;
167
168 message.d->type = dbus_message_get_type(dmsg);
169 message.d->path = TQString::fromUtf8(dbus_message_get_path(dmsg));
170 message.d->interface = TQString::fromUtf8(dbus_message_get_interface(dmsg));
171 message.d->member = TQString::fromUtf8(dbus_message_get_member(dmsg));
172 message.d->sender = TQString::fromUtf8(dbus_message_get_sender(dmsg));
173 message.d->msg = dbus_message_ref(dmsg);
174
175 DBusError dbusError;
176 dbus_error_init(&dbusError);
177 if (dbus_set_error_from_message(&dbusError, dmsg))
178 {
179 message.d->error = TQT_DBusError(&dbusError);
180 }
181
182 TQT_DBusMarshall::messageToList(message, dmsg);
183
184 return message;
185}
Class for transporting D-Bus errors.
Definition tqdbuserror.h:41
static void messageToList(TQValueList< TQT_DBusData > &list, DBusMessage *message)

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.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ interface()

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:

Returns
a non-empty interface name or TQString()
See also
path()
member()
sender()

Definition at line 192 of file tqdbusmessage.cpp.

193{
194 return d->interface;
195}

References d, and TQT_DBusMessagePrivate::interface.

+ Here is the caller graph for this function:

◆ member()

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:

Returns
a non-empty member name or TQString()
See also
path()
interface()
sender()

Definition at line 197 of file tqdbusmessage.cpp.

198{
199 return d->member;
200}

References d, and TQT_DBusMessagePrivate::member.

+ Here is the caller graph for this function:

◆ methodCall()

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
servicethe D-Bus name of the application hosting the service object
paththe object path of the service object
interfacethe object's interface to which the method belongs
methodthe 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.

64{
65 TQT_DBusMessage message;
66 message.d->type = DBUS_MESSAGE_TYPE_METHOD_CALL;
67 message.d->service = service;
68 message.d->path = path;
69 message.d->interface = interface;
70 message.d->member = method;
71
72 return message;
73}
TQString interface() const
Returns the message's interface name.

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

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ methodError()

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
otherthe method call message it is replying to
errorthe 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.

87{
88 Q_ASSERT(other.d->msg);
89
90 TQT_DBusMessage message;
91 if (!error.isValid())
92 {
93 tqWarning("TQT_DBusMessage: error passed to methodError() is not valid!");
94 return message;
95 }
96
97 message.d->type = DBUS_MESSAGE_TYPE_ERROR;
98 message.d->reply = dbus_message_ref(other.d->msg);
99 message.d->error = error;
100
101 return message;
102}
bool isValid() const
Returns whether the error object is valid.
TQT_DBusError error() const
Returns the error of an error message.

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

+ Here is the call graph for this function:

◆ methodReply()

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
otherthe 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.

76{
77 Q_ASSERT(other.d->msg);
78
79 TQT_DBusMessage message;
80 message.d->type = DBUS_MESSAGE_TYPE_METHOD_RETURN;
81 message.d->reply = dbus_message_ref(other.d->msg);
82
83 return message;
84}

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

◆ operator=()

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
otherthe message to copy
Returns
a reference to this instance as required by assignment operator semantics

Definition at line 122 of file tqdbusmessage.cpp.

123{
125 // FIXME-QT4 qAtomicAssign(d, other.d);
126 if (other.d) other.d->ref.ref();
128 d = other.d;
129 if (old && !old->ref.deref())
130 delete old;
131 return *this;
132}

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

+ Here is the call graph for this function:

◆ path()

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:

Returns
a non-empty object path or TQString()
See also
interface()
member()
sender()

Definition at line 187 of file tqdbusmessage.cpp.

188{
189 return d->path;
190}

References d, and TQT_DBusMessagePrivate::path.

+ Here is the caller graph for this function:

◆ replySerialNumber()

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.

242{
243 if (!d->msg)
244 return 0;
245 return dbus_message_get_reply_serial(d->msg);
246}

References d, and TQT_DBusMessagePrivate::msg.

+ Here is the caller graph for this function:

◆ sender()

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.

203{
204 return d->sender;
205}

References d, and TQT_DBusMessagePrivate::sender.

+ Here is the caller graph for this function:

◆ serialNumber()

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.

227{
228 if (!d->msg)
229 return 0;
230 return dbus_message_get_serial(d->msg);
231}

References d, and TQT_DBusMessagePrivate::msg.

◆ setTimeout()

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
mstimeout in milliseconds
See also
timeout()
DefaultTimeout
NoTimeout

Definition at line 217 of file tqdbusmessage.cpp.

218{
219 d->timeout = ms;
220}

References d, and TQT_DBusMessagePrivate::timeout.

◆ signal()

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
paththe object path of the service object
interfacethe object's interface to which the signal belongs
memberthe 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.

52{
53 TQT_DBusMessage message;
54 message.d->type = DBUS_MESSAGE_TYPE_SIGNAL;
55 message.d->path = path;
56 message.d->interface = interface;
57 message.d->member = member;
58
59 return message;
60}
TQString member() const
Returns the message's member name.

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

+ Here is the call graph for this function:

◆ timeout()

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.

213{
214 return d->timeout;
215}

References d, and TQT_DBusMessagePrivate::timeout.

+ Here is the caller graph for this function:

◆ toDBusMessage()

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.

135{
136 DBusMessage *msg = 0;
137 switch (d->type) {
138 case DBUS_MESSAGE_TYPE_METHOD_CALL:
139 msg = dbus_message_new_method_call(d->service.utf8().data(),
140 d->path.utf8().data(), d->interface.utf8().data(),
141 d->member.utf8().data());
142 break;
143 case DBUS_MESSAGE_TYPE_SIGNAL:
144 msg = dbus_message_new_signal(d->path.utf8().data(),
145 d->interface.utf8().data(), d->member.utf8().data());
146 break;
147 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
148 msg = dbus_message_new_method_return(d->reply);
149 break;
150 case DBUS_MESSAGE_TYPE_ERROR:
151 msg = dbus_message_new_error(d->reply, d->error.name().utf8().data(),
152 d->error.message().utf8().data());
153 break;
154 }
155 if (!msg)
156 return 0;
157
159 return msg;
160}
TQString name() const
Returns the D-Bus error name.
TQString message() const
Returns a string describing the error.
static void listToMessage(const TQValueList< TQT_DBusData > &list, DBusMessage *message)

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.

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ type()

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.

249{
250 switch (d->type) {
251 case DBUS_MESSAGE_TYPE_METHOD_CALL:
252 return MethodCallMessage;
253 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
254 return ReplyMessage;
255 case DBUS_MESSAGE_TYPE_ERROR:
256 return ErrorMessage;
257 case DBUS_MESSAGE_TYPE_SIGNAL:
258 return SignalMessage;
259 default:
260 return InvalidMessage;
261 }
262}

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

Friends And Related Symbol Documentation

◆ TQT_DBusConnection

friend class TQT_DBusConnection
friend

Definition at line 117 of file tqdbusmessage.h.

Member Data Documentation

◆ d

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: