DBus-1-TQt  1.0
TQT_DBusProxy Class Reference

#include <tqdbusproxy.h>

+ Inheritance diagram for TQT_DBusProxy:
+ Collaboration diagram for TQT_DBusProxy:

Classes

class  Private
 

Signals

void dbusSignal (const TQT_DBusMessage &message)
 
void asyncReply (int callID, const TQT_DBusMessage &message)
 

Public Member Functions

 TQT_DBusProxy (TQObject *parent=0, const char *name=0)
 
 TQT_DBusProxy (const TQT_DBusConnection &connection, TQObject *parent=0, const char *name=0)
 
 TQT_DBusProxy (const TQString &service, const TQString &path, const TQString &interface, const TQT_DBusConnection &connection, TQObject *parent=0, const char *name=0)
 
virtual ~TQT_DBusProxy ()
 
bool setConnection (const TQT_DBusConnection &connection)
 
const TQT_DBusConnectionconnection () const
 
void setService (const TQString &service)
 
TQString service () const
 
void setPath (const TQString &path)
 
TQString path () const
 
void setInterface (const TQString &interface)
 
TQString interface () const
 
bool canSend () const
 
bool send (const TQString &method, const TQValueList< TQT_DBusData > &params) const
 
TQT_DBusMessage sendWithReply (const TQString &method, const TQValueList< TQT_DBusData > &params, TQT_DBusError *error=0) const
 
int sendWithAsyncReply (const TQString &method, const TQValueList< TQT_DBusData > &params)
 
TQT_DBusError lastError () const
 

Protected Slots

virtual void handleDBusSignal (const TQT_DBusMessage &message)
 
virtual void handleAsyncReply (const TQT_DBusMessage &message)
 

Private Member Functions

 TQT_DBusProxy (const TQT_DBusProxy &)
 
TQT_DBusProxyoperator= (const TQT_DBusProxy &)
 

Private Attributes

Privated
 

Detailed Description

Client interface to a remote service object.

TQT_DBusProxy provides a convenience interface for working with D-Bus services, or more precisely, interfaces of D-Bus service objects.

A D-Bus service object is identified through the name of its host application on the bus and its path (logical location) within the host application. Such a service object can implement any number of interfaces, i.e. groups methods and signals, and can create a TQT_DBusProxy instance for every one your application needs to work with.

See section Using D-Bus as a client for documentation on how to use TQT_DBusProxy

Definition at line 237 of file tqdbusproxy.h.

Constructor & Destructor Documentation

◆ TQT_DBusProxy() [1/4]

TQT_DBusProxy::TQT_DBusProxy ( TQObject *  parent = 0,
const char *  name = 0 
)

Creates a proxy without binding it to a service or connection.

This basic constructor allows to create a proxy and specify the peer object and interface later on.

Parameters
parentTQObject parent
nameTQObject name

Definition at line 51 of file tqdbusproxy.cpp.

52  : TQObject(parent, (name ? name : "TQT_DBusProxy")),
53  d(new Private())
54 {
55 }

◆ TQT_DBusProxy() [2/4]

TQT_DBusProxy::TQT_DBusProxy ( const TQT_DBusConnection connection,
TQObject *  parent = 0,
const char *  name = 0 
)

Creates a proxy on a given connection without binding it to a service.

Similar to the above constructor, it does not yet specify and details about the proxy's peer, but already specifies which connection to work on.

This can be useful to monitor all signal on a connection without filtering for a specific peer.

Parameters
connectionthe D-Bus connection to work on
parentTQObject parent
nameTQObject name

Definition at line 57 of file tqdbusproxy.cpp.

59  : TQObject(parent, (name ? name : "TQT_DBusProxy")),
60  d(new Private())
61 {
63 }

References connection(), and setConnection().

+ Here is the call graph for this function:

◆ TQT_DBusProxy() [3/4]

TQT_DBusProxy::TQT_DBusProxy ( const TQString &  service,
const TQString &  path,
const TQString &  interface,
const TQT_DBusConnection connection,
TQObject *  parent = 0,
const char *  name = 0 
)

Creates a proxy for a given peer on a given connection.

This creates a proxy for a specific peer object-interface combination It is equvalent to creating an "empty" proxy and calling setConnection(), setService(), setPath() and setInterface() manually.

Parameters
servicethe name the peer's host application uses on the bus
paththe peer object's path within its host application
interfacethe interface to work with
connectionthe D-Bus connection to work on
parentTQObject parent
nameTQObject name

Definition at line 65 of file tqdbusproxy.cpp.

68  : TQObject(parent, (name ? name : "TQT_DBusProxy")),
69  d(new Private())
70 {
72 
73  d->service = service;
74  d->path = path;
76  d->checkCanSend();
77 }

References TQT_DBusProxy::Private::checkCanSend(), connection(), d, TQT_DBusProxy::Private::interface, interface(), TQT_DBusProxy::Private::path, path(), TQT_DBusProxy::Private::service, service(), and setConnection().

+ Here is the call graph for this function:

◆ ~TQT_DBusProxy()

TQT_DBusProxy::~TQT_DBusProxy ( )
virtual

Destroys the proxy instance.

Definition at line 79 of file tqdbusproxy.cpp.

80 {
81  delete d;
82 }

References d.

◆ TQT_DBusProxy() [4/4]

TQT_DBusProxy::TQT_DBusProxy ( const TQT_DBusProxy )
private

Member Function Documentation

◆ asyncReply

void TQT_DBusProxy::asyncReply ( int  callID,
const TQT_DBusMessage message 
)
signal

Signal emitted for received replies to asynchronous method calls.

If a method invoked by using sendWithAsyncReply() send a response, e.g. method return value or errors, this signal is emitted to notify the proxy's user.

Parameters
callIDthe method call's serial number as returned by sendWithAsyncReply()
messagethe reply's content
See also
handleAsyncReply()
TQT_DBusMessage::replySerialNumber()
+ Here is the caller graph for this function:

◆ canSend()

bool TQT_DBusProxy::canSend ( ) const

Returns whether the proxy can be used to send method calls.

The capabilitly to send method calls depends on having all necessary base information:

and a working connection, see setConnection()

Returns
true if method calls can be sent, false if any of the three base information is missing or if the connection is not connected
See also
send()
sendWithReply()
sendWithAsyncReply()

Definition at line 131 of file tqdbusproxy.cpp.

132 {
133  return d->canSend && d->connection.isConnected();
134 }

References TQT_DBusProxy::Private::canSend, TQT_DBusProxy::Private::connection, d, and TQT_DBusConnection::isConnected().

+ Here is the call graph for this function:

◆ connection()

const TQT_DBusConnection & TQT_DBusProxy::connection ( ) const

Returns the currently used D-Bus connection.

See also
setConnection()

Definition at line 93 of file tqdbusproxy.cpp.

94 {
95  return d->connection;
96 }

References TQT_DBusProxy::Private::connection, and d.

+ Here is the caller graph for this function:

◆ dbusSignal

void TQT_DBusProxy::dbusSignal ( const TQT_DBusMessage message)
signal

Signal emitted for D-Bus signals from the peer.

Signals received on the proxy's connection are filtered by handleDBusSignal() for all proxy properties that are not empty.

Parameters
messagethe signal's content
See also
TQT_DBusMessage::SignalMessage
+ Here is the caller graph for this function:

◆ handleAsyncReply

void TQT_DBusProxy::handleAsyncReply ( const TQT_DBusMessage message)
protectedvirtualslot

Handles replies to asynchronous method calls.

The base implementation simply extracts the reply's error and makes it available for lastError(). It then emits asyncReply()

Parameters
messagethe D-Bus reply message as received
See also
TQT_DBusMessage::replySerialNumber()

Definition at line 202 of file tqdbusproxy.cpp.

203 {
204  d->error = message.error();
205 
206  emit asyncReply(message.replySerialNumber(), message);
207 }

References asyncReply(), d, TQT_DBusProxy::Private::error, TQT_DBusMessage::error(), and TQT_DBusMessage::replySerialNumber().

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

◆ handleDBusSignal

void TQT_DBusProxy::handleDBusSignal ( const TQT_DBusMessage message)
protectedvirtualslot

Handles D-Bus signals received on the proxy's connection.

The base implementation checks each non-empty property, i.e. service name, object path and interface, with the respective field of the signal's D-Bus message.

If all available matches succeed, the message is emitted by dbusSignal(), otherwise it is discarded.

Note
Filtering for service will only happen if service is a unique D-Bus name, i.e. if it starts with a colon ":" since D-Bus signals carry the sender's unique name and filtering by a requested name would reject all signals.
Parameters
messagethe D-Bus signal message as received
See also
TQT_DBusMessage::SignalMessage

Definition at line 185 of file tqdbusproxy.cpp.

186 {
187  if (!d->path.isEmpty() && d->path != message.path())
188  return;
189 
190  // only filter by service name if the name is a unique name
191  // because signals are always coming from a connection's unique name
192  // and filtering by a generic name would reject all signals
193  if (d->service.startsWith(":") && d->service != message.sender())
194  return;
195 
196  if (!d->interface.isEmpty() && d->interface != message.interface())
197  return;
198 
199  emit dbusSignal(message);
200 }

References d, dbusSignal(), TQT_DBusProxy::Private::interface, TQT_DBusMessage::interface(), TQT_DBusProxy::Private::path, TQT_DBusMessage::path(), TQT_DBusMessage::sender(), and TQT_DBusProxy::Private::service.

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

◆ interface()

TQString TQT_DBusProxy::interface ( ) const

Returns the name of the peer interface.

Returns
the peer object's interface
See also
setInterface()

Definition at line 126 of file tqdbusproxy.cpp.

127 {
128  return d->interface;
129 }

References d, and TQT_DBusProxy::Private::interface.

+ Here is the caller graph for this function:

◆ lastError()

TQT_DBusError TQT_DBusProxy::lastError ( ) const

Returns the last error seen by the proxy.

The last error can a connection error, e.g. sending a message failed due connection being lost, or the error of the last call to sendWithReply or the error of the last received asyncReply()

Returns
the last dbus error seen by this proxy

Definition at line 180 of file tqdbusproxy.cpp.

181 {
182  return d->error;
183 }

References d, and TQT_DBusProxy::Private::error.

◆ operator=()

TQT_DBusProxy& TQT_DBusProxy::operator= ( const TQT_DBusProxy )
private

◆ path()

TQString TQT_DBusProxy::path ( ) const

Returns the peer's object path.

Returns
the peer object's path
See also
setPath()

Definition at line 115 of file tqdbusproxy.cpp.

116 {
117  return d->path;
118 }

References d, and TQT_DBusProxy::Private::path.

+ Here is the caller graph for this function:

◆ send()

bool TQT_DBusProxy::send ( const TQString &  method,
const TQValueList< TQT_DBusData > &  params 
) const

Sends a method call to the peer object.

This is roughly equivalent to calling a C++ method with no return value or like ignoring the it.

Parameters
methodthe name of the method to invoke
paramsthe method parameters. Use an empty list if the method does not require parameters
Returns
true if sending succeeded, false if sending failed, the method name was empty or any of the conditions for successfull sending as described for canSend() are not met
See also
lastError()
sendWithReply()
sendWithAsyncReply()
Method and signal names

Definition at line 136 of file tqdbusproxy.cpp.

137 {
138  if (!d->canSend || method.isEmpty() || !d->connection.isConnected())
139  return false;
140 
142  d->interface, method);
143  message += params;
144 
145  return d->connection.send(message);
146 }

References TQT_DBusProxy::Private::canSend, TQT_DBusProxy::Private::connection, d, TQT_DBusProxy::Private::interface, TQT_DBusConnection::isConnected(), TQT_DBusMessage::methodCall(), TQT_DBusProxy::Private::path, TQT_DBusConnection::send(), and TQT_DBusProxy::Private::service.

+ Here is the call graph for this function:

◆ sendWithAsyncReply()

int TQT_DBusProxy::sendWithAsyncReply ( const TQString &  method,
const TQValueList< TQT_DBusData > &  params 
)

Sends a method call to the peer object but does not wait for an answer.

This is roughly equivalent to calling a C++ method on a local TQt event loop driven object, where the result of the method call is delivered later through a signal.

Note
as with TQt's asychronous classes this needs a running event loop
Parameters
methodthe name of the method to invoke
paramsthe method parameters. Use an empty list if the method does not require parameters
Returns
a serial number to easily identify the reply once it is received or 0 if the call is not possible, i.e. the method name is empty or any of the conditions for canSend() are not met
Warning
if a asynchronous call is followed by a synchronous call, e.g. using sendWithReply(), without returning to the event loop, is recommended to call TQT_DBusConnection::scheduleDispatch() after the synchronous call to make sure any reply received during the blocking call is delivered
See also
asyncReply()
send()
sendWithReply()
Method and signal names

Definition at line 167 of file tqdbusproxy.cpp.

168 {
169  if (!d->canSend || method.isEmpty() || !d->connection.isConnected())
170  return 0;
171 
173  d->interface, method);
174  message += params;
175 
176  return d->connection.sendWithAsyncReply(message, this,
177  TQ_SLOT(handleAsyncReply(const TQT_DBusMessage&)));
178 }

References TQT_DBusProxy::Private::canSend, TQT_DBusProxy::Private::connection, d, handleAsyncReply(), TQT_DBusProxy::Private::interface, TQT_DBusConnection::isConnected(), TQT_DBusMessage::methodCall(), TQT_DBusProxy::Private::path, TQT_DBusConnection::sendWithAsyncReply(), and TQT_DBusProxy::Private::service.

+ Here is the call graph for this function:

◆ sendWithReply()

TQT_DBusMessage TQT_DBusProxy::sendWithReply ( const TQString &  method,
const TQValueList< TQT_DBusData > &  params,
TQT_DBusError error = 0 
) const

Sends a method call to the peer object and waits for the reply.

This is roughly equivalent to calling a C++ method on a local object.

Parameters
methodthe name of the method to invoke
paramsthe method parameters. Use an empty list if the method does not require parameters
erroroptional parameter to get any error directly
Returns
a TQT_DBusMessage containing any return values of the invoked method. Will be an invalid message if an error occurs. The error can be accessed through the optional paramater error or through lastError()
See also
canSend()
send()
sendWithAsyncReply()
Method and signal names

Definition at line 148 of file tqdbusproxy.cpp.

151 {
152  if (!d->canSend || method.isEmpty() || !d->connection.isConnected())
153  return TQT_DBusMessage();
154 
156  d->interface, method);
157  message += params;
158 
159  TQT_DBusMessage reply = d->connection.sendWithReply(message, &d->error);
160 
161  if (error)
162  *error = d->error;
163 
164  return reply;
165 }

References TQT_DBusProxy::Private::canSend, TQT_DBusProxy::Private::connection, d, TQT_DBusProxy::Private::error, TQT_DBusProxy::Private::interface, TQT_DBusConnection::isConnected(), TQT_DBusMessage::methodCall(), TQT_DBusProxy::Private::path, TQT_DBusConnection::sendWithReply(), and TQT_DBusProxy::Private::service.

+ Here is the call graph for this function:

◆ service()

TQString TQT_DBusProxy::service ( ) const

Returns the peer's service name.

Returns
the peer object's service name
See also
setService()

Definition at line 104 of file tqdbusproxy.cpp.

105 {
106  return d->service;
107 }

References d, and TQT_DBusProxy::Private::service.

+ Here is the caller graph for this function:

◆ setConnection()

bool TQT_DBusProxy::setConnection ( const TQT_DBusConnection connection)

Sets the D-Bus connection to work on.

Disconnects from any previously used connection and connects to the new connection's signal distribution. If no peer information has been provided at creation time or through the other set methods, the instance's signal dbusSignal() will emit all signals received on the given connection.

Parameters
connectionthe D-Bus connection to work on
Returns
true if connecting to the new connection's signal succeeded, false if it failed, e.g. if the connection is a "null" connection
See also
connection()
setService()
setPath()
setInterface()

Definition at line 84 of file tqdbusproxy.cpp.

85 {
86  d->connection.disconnect(this, TQ_SLOT(handleDBusSignal(const TQT_DBusMessage&)));
87 
89 
90  return d->connection.connect(this, TQ_SLOT(handleDBusSignal(const TQT_DBusMessage&)));
91 }

References TQT_DBusConnection::connect(), TQT_DBusProxy::Private::connection, connection(), d, TQT_DBusConnection::disconnect(), and handleDBusSignal().

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

◆ setInterface()

void TQT_DBusProxy::setInterface ( const TQString &  interface)

Sets the name of the peer interface.

A non-empty interface name is required if the proxy is to be used for method calls. See section Interface names for details.

If a string other than TQString() is set, it will be used to filter signals, i.e. a signal received by the proxy will only be emitted if the interface name matches.

Parameters
interfacethe peer's interface to work with
See also
interface()
setService()
setPath()

Definition at line 120 of file tqdbusproxy.cpp.

121 {
122  d->interface = interface;
123  d->checkCanSend();
124 }

References TQT_DBusProxy::Private::checkCanSend(), d, TQT_DBusProxy::Private::interface, and interface().

+ Here is the call graph for this function:

◆ setPath()

void TQT_DBusProxy::setPath ( const TQString &  path)

Sets the peer's object path.

A non-empty object path is required if the proxy is to be used for method calls. See section Object paths for details.

If a string other than TQString() is set, it will be used to filter signals, i.e. a signal received by the proxy will only be emitted if the object path matches.

Parameters
paththe peer's object path inside its host application (logical address)
See also
path()
setService()
setInterface()

Definition at line 109 of file tqdbusproxy.cpp.

110 {
111  d->path = path;
112  d->checkCanSend();
113 }

References TQT_DBusProxy::Private::checkCanSend(), d, TQT_DBusProxy::Private::path, and path().

+ Here is the call graph for this function:

◆ setService()

void TQT_DBusProxy::setService ( const TQString &  service)

Sets the peer's service name.

A non-empty service name is required if the proxy is to be used for method calls. See section Service names for details.

If a string other than TQString() is set, it will be used to filter signals, i.e. a signal received by the proxy will only be emitted if the service name matches.

Parameters
servicethe peer's name on the bus
See also
service()
setPath()
setInterface()

Definition at line 98 of file tqdbusproxy.cpp.

99 {
100  d->service = service;
101  d->checkCanSend();
102 }

References TQT_DBusProxy::Private::checkCanSend(), d, TQT_DBusProxy::Private::service, and service().

+ Here is the call graph for this function:

Member Data Documentation

◆ d

Private* TQT_DBusProxy::d
private

Definition at line 576 of file tqdbusproxy.h.


The documentation for this class was generated from the following files:
TQT_DBusConnection::disconnect
bool disconnect(TQObject *object, const char *slot)
Disconnects a given receiver from the D-Bus signal handling.
Definition: tqdbusconnection.cpp:334
TQT_DBusProxy::Private::canSend
bool canSend
Definition: tqdbusproxy.cpp:46
TQT_DBusProxy::handleDBusSignal
virtual void handleDBusSignal(const TQT_DBusMessage &message)
Handles D-Bus signals received on the proxy's connection.
Definition: tqdbusproxy.cpp:185
TQT_DBusProxy::Private::connection
TQT_DBusConnection connection
Definition: tqdbusproxy.cpp:41
TQT_DBusProxy::Private::service
TQString service
Definition: tqdbusproxy.cpp:43
TQT_DBusProxy::dbusSignal
void dbusSignal(const TQT_DBusMessage &message)
Signal emitted for D-Bus signals from the peer.
TQT_DBusConnection::connect
bool connect(TQObject *object, const char *slot)
Connects an object to receive D-Bus signals.
Definition: tqdbusconnection.cpp:324
TQT_DBusMessage::sender
TQString sender() const
Returns the name of the message sender.
Definition: tqdbusmessage.cpp:202
TQT_DBusMessage::interface
TQString interface() const
Returns the message's interface name.
Definition: tqdbusmessage.cpp:192
TQT_DBusMessage::methodCall
static TQT_DBusMessage methodCall(const TQString &service, const TQString &path, const TQString &interface, const TQString &method)
Creates a message for sending a D-Bus method call.
Definition: tqdbusmessage.cpp:62
TQT_DBusProxy::Private::error
TQT_DBusError error
Definition: tqdbusproxy.cpp:48
TQT_DBusProxy::Private::path
TQString path
Definition: tqdbusproxy.cpp:44
TQT_DBusProxy::interface
TQString interface() const
Returns the name of the peer interface.
Definition: tqdbusproxy.cpp:126
TQT_DBusProxy::path
TQString path() const
Returns the peer's object path.
Definition: tqdbusproxy.cpp:115
TQT_DBusConnection::sendWithAsyncReply
int sendWithAsyncReply(const TQT_DBusMessage &message, TQObject *receiver, const char *slot) const
Sends a message over the bus, specifying a receiver object for replies.
Definition: tqdbusconnection.cpp:266
TQT_DBusProxy::asyncReply
void asyncReply(int callID, const TQT_DBusMessage &message)
Signal emitted for received replies to asynchronous method calls.
TQT_DBusProxy::Private::interface
TQString interface
Definition: tqdbusproxy.cpp:45
TQT_DBusProxy::setConnection
bool setConnection(const TQT_DBusConnection &connection)
Sets the D-Bus connection to work on.
Definition: tqdbusproxy.cpp:84
TQT_DBusProxy::d
Private * d
Definition: tqdbusproxy.h:576
TQT_DBusProxy::Private::checkCanSend
void checkCanSend()
Definition: tqdbusproxy.cpp:35
TQT_DBusMessage::replySerialNumber
int replySerialNumber() const
Returns the message's reply serial number.
Definition: tqdbusmessage.cpp:241
TQT_DBusProxy::service
TQString service() const
Returns the peer's service name.
Definition: tqdbusproxy.cpp:104
TQT_DBusProxy::connection
const TQT_DBusConnection & connection() const
Returns the currently used D-Bus connection.
Definition: tqdbusproxy.cpp:93
TQT_DBusMessage::error
TQT_DBusError error() const
Returns the error of an error message.
Definition: tqdbusmessage.cpp:207
TQT_DBusConnection::send
bool send(const TQT_DBusMessage &message) const
Sends a message over the bus.
Definition: tqdbusconnection.cpp:252
TQT_DBusConnection::isConnected
bool isConnected() const
Returns whether the connection is connected to a bus.
Definition: tqdbusconnection.cpp:370
TQT_DBusConnection::sendWithReply
TQT_DBusMessage sendWithReply(const TQT_DBusMessage &message, TQT_DBusError *error=0) const
Sends a message over the bus and waits for the reply.
Definition: tqdbusconnection.cpp:275
TQT_DBusMessage::path
TQString path() const
Returns the message's object path.
Definition: tqdbusmessage.cpp:187
TQT_DBusProxy::handleAsyncReply
virtual void handleAsyncReply(const TQT_DBusMessage &message)
Handles replies to asynchronous method calls.
Definition: tqdbusproxy.cpp:202
TQT_DBusMessage
A message converts and transports data over D-Bus.
Definition: tqdbusmessage.h:115