QDBusProxy Class Reference

Client interface to a remote service object. More...

#include <qdbusproxy.h>

List of all members.

Signals

void dbusSignal (const QDBusMessage &message)
 Signal emitted for D-Bus signals from the peer.
void asyncReply (int callID, const QDBusMessage &message)
 Signal emitted for received replies to asynchronous method calls.

Public Member Functions

 QDBusProxy (QObject *parent=0, const char *name=0)
 Creates a proxy without binding it to a service or connection.
 QDBusProxy (const QDBusConnection &connection, QObject *parent=0, const char *name=0)
 Creates a proxy on a given connection without binding it to a service.
 QDBusProxy (const QString &service, const QString &path, const QString &interface, const QDBusConnection &connection, QObject *parent=0, const char *name=0)
 Creates a proxy for a given peer on a given connection.
virtual ~QDBusProxy ()
 Destroys the proxy instance.
bool setConnection (const QDBusConnection &connection)
 Sets the D-Bus connection to work on.
const QDBusConnection & connection () const
 Returns the currently used D-Bus connection.
void setService (const QString &service)
 Sets the peer's service name.
QString service () const
 Returns the peer's service name.
void setPath (const QString &path)
 Sets the peer's object path.
QString path () const
 Returns the peer's object path.
void setInterface (const QString &interface)
 Sets the name of the peer interface.
QString interface () const
 Returns the name of the peer interface.
bool canSend () const
 Returns whether the proxy can be used to send method calls.
bool send (const QString &method, const QValueList< QDBusData > &params) const
 Sends a method call to the peer object.
QDBusMessage sendWithReply (const QString &method, const QValueList< QDBusData > &params, QDBusError *error=0) const
 Sends a method call to the peer object and waits for the reply.
int sendWithAsyncReply (const QString &method, const QValueList< QDBusData > &params)
 Sends a method call to the peer object but does not wait for an answer.
QDBusError lastError () const
 Returns the last error seen by the proxy.

Protected Slots

virtual void handleDBusSignal (const QDBusMessage &message)
 Handles D-Bus signals received on the proxy's connection.
virtual void handleAsyncReply (const QDBusMessage &message)
 Handles replies to asynchronous method calls.

Detailed Description

Client interface to a remote service object.

QDBusProxy 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 QDBusProxy instance for every one your application needs to work with.

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

Examples:

example-client.cpp.

Constructor & Destructor Documentation

QDBusProxy::QDBusProxy ( QObject *  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:
parent QObject parent
name QObject name
QDBusProxy::QDBusProxy ( const QDBusConnection &  connection,
QObject *  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:
connection the D-Bus connection to work on
parent QObject parent
name QObject name
QDBusProxy::QDBusProxy ( const QString &  service,
const QString &  path,
const QString &  interface,
const QDBusConnection &  connection,
QObject *  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:
service the name the peer's host application uses on the bus
path the peer object's path within its host application
interface the interface to work with
connection the D-Bus connection to work on
parent QObject parent
name QObject name
virtual QDBusProxy::~QDBusProxy (  )  [virtual]

Destroys the proxy instance.

Member Function Documentation

void QDBusProxy::asyncReply ( int  callID,
const QDBusMessage &  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:
callID the method call's serial number as returned by sendWithAsyncReply()
message the reply's content
See also:
handleAsyncReply()
QDBusMessage::replySerialNumber()
bool QDBusProxy::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()
const QDBusConnection& QDBusProxy::connection (  )  const

Returns the currently used D-Bus connection.

See also:
setConnection()
void QDBusProxy::dbusSignal ( const QDBusMessage &  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:
message the signal's content
See also:
QDBusMessage::SignalMessage
virtual void QDBusProxy::handleAsyncReply ( const QDBusMessage &  message  )  [protected, virtual, slot]

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:
message the D-Bus reply message as received
See also:
QDBusMessage::replySerialNumber()
virtual void QDBusProxy::handleDBusSignal ( const QDBusMessage &  message  )  [protected, virtual, slot]

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:
message the D-Bus signal message as received
See also:
QDBusMessage::SignalMessage
QString QDBusProxy::interface (  )  const

Returns the name of the peer interface.

Returns:
the peer object's interface
See also:
setInterface()
QDBusError QDBusProxy::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
QString QDBusProxy::path (  )  const

Returns the peer's object path.

Returns:
the peer object's path
See also:
setPath()
bool QDBusProxy::send ( const QString &  method,
const QValueList< QDBusData > &  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:
method the name of the method to invoke
params the 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
int QDBusProxy::sendWithAsyncReply ( const QString &  method,
const QValueList< QDBusData > &  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 Qt event loop driven object, where the result of the method call is delivered later through a signal.

Note:
as with Qt's asychronous classes this needs a running event loop
Parameters:
method the name of the method to invoke
params the 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 QDBusConnection::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
QDBusMessage QDBusProxy::sendWithReply ( const QString &  method,
const QValueList< QDBusData > &  params,
QDBusError *  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:
method the name of the method to invoke
params the method parameters. Use an empty list if the method does not require parameters
error optional parameter to get any error directly
Returns:
a QDBusMessage 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
QString QDBusProxy::service (  )  const

Returns the peer's service name.

Returns:
the peer object's service name
See also:
setService()
bool QDBusProxy::setConnection ( const QDBusConnection &  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:
connection the 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()
void QDBusProxy::setInterface ( const QString &  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 QString::null 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:
interface the peer's interface to work with
See also:
interface()
setService()
setPath()
void QDBusProxy::setPath ( const QString &  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 QString::null 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:
path the peer's object path inside its host application (logical address)
See also:
path()
setService()
setInterface()
void QDBusProxy::setService ( const QString &  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 QString::null 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:
service the peer's name on the bus
See also:
service()
setPath()
setInterface()
The documentation for this class was generated from the following file:
Generated by  doxygen 1.6.2