QDBusConnection Class Reference

Provides access to a specific D-Bus bus. More...

#include <qdbusconnection.h>

List of all members.

Public Types

enum  BusType { SessionBus, SystemBus, ActivationBus }
enum  NameRequestMode { NoReplace = 0, AllowReplace = 1, ReplaceExisting = 2 }
 

Flags for controlling the behavior name collision handling.

More...

Public Member Functions

 QDBusConnection ()
 Creates an empty/disconnected connection handle.
 QDBusConnection (const QString &name)
 Creates a connection handle to a named connection.
 QDBusConnection (const QDBusConnection &other)
 Creates a shallow copy of the given connection.
 ~QDBusConnection ()
 Destroys the connection handle.
QDBusConnection & operator= (const QDBusConnection &other)
 Creates a shallow copy of the given connection.
bool isConnected () const
 Returns whether the connection is connected to a bus.
QDBusError lastError () const
 Returns the last error seen by the connection.
bool requestName (const QString &name, int modeFlags=NoReplace)
 Requests to be addressable on the bus by a given name.
QString uniqueName () const
 Returns the connection identifier assigned at connect.
bool send (const QDBusMessage &message) const
 Sends a message over the bus.
QDBusMessage sendWithReply (const QDBusMessage &message, QDBusError *error=0) const
 Sends a message over the bus and waits for the reply.
int sendWithAsyncReply (const QDBusMessage &message, QObject *receiver, const char *slot) const
 Sends a message over the bus, specifying a receiver object for replies.
void flush () const
 Flushes buffered outgoing message.
void dispatch () const
 Processes buffered inbound messages.
void scheduleDispatch () const
 Request a delayed check for inbound buffer processing.
bool connect (QObject *object, const char *slot)
 Connects an object to receive D-Bus signals.
bool disconnect (QObject *object, const char *slot)
 Disconnects a given receiver from the D-Bus signal handling.
bool registerObject (const QString &path, QDBusObjectBase *object)
 Registers a service object for a given path.
void unregisterObject (const QString &path)
 Unregister a service object on a given path.

Static Public Member Functions

static QDBusConnection sessionBus ()
 Gets a connection to the session bus.
static QDBusConnection systemBus ()
 Gets a connection to the system bus.
static QDBusConnection addConnection (BusType type, const QString &name=default_connection_name)
 Add a connection to a bus with a specific bus type.
static QDBusConnection addConnection (const QString &address, const QString &name=default_connection_name)
 Add a connection to a bus at a specific address.
static void closeConnection (const QString &name=default_connection_name)
 Closes a connection with a given name.

Public Attributes

QT_STATIC_CONST char * default_connection_name

Detailed Description

Provides access to a specific D-Bus bus.

In order to access a D-Bus message bus an application has to connect to it. This is very similar to connecting to an FTP server using QFtp, where any number of commands can be sent in sequence over the same connection.

Additionally to the asynchronous command execution provided by QFtp a QDBusConnection can also execute synchronous (blocking) calls so the code around those calls stays closer to in-process method incovations.

However it is recommended to only perform blocking calls on D-Bus service methods that are likely to be processed fast.

QDBusConnection implements a shared resource, i.e. if you create a connection with a specific name in one part of your code and then create one with the same name somewhere else, the second creation will actually return the same shared connection object the first caller created.

The application can be connected to more than one message bus simultaniously using one or more connections per bus, however the most common case is to have one connection per bus.

The two main bus types are:

While QDBusConnection provides the basic API to access D-Bus services it is more convenient to use QDBusProxy on top of the connection.

See sections Using D-Bus as a client and Providing services over D-Bus for examples

Examples:

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

Member Enumeration Documentation

enum QDBusConnection::BusType

DBus bus types

Enumerator:
SessionBus 

The session bus is a user and user session specific message channel. It will usually be started by a login script or a session manager.

SystemBus 

The system bus is a message channel bridging user level and system level process boundaries, e.g. it can allow a user process with normal user access restrictions to perform a limited subset of operations on a process running with elevated rights.

Warning:
if an applications exposed services on the system bus, i.e. registers objects using registerObject(), it should be carefully examined on potential security issues
enum QDBusConnection::NameRequestMode

Flags for controlling the behavior name collision handling.

See also:
requestName()
Enumerator:
NoReplace 

Do not allow others to take over a name requested by this application

AllowReplace 

Allow other applications that request the same name to get it, i.e. allow the bus to transfer the name from this application to the one requesting it

ReplaceExisting 

Try to get the name transferred from the current owner to this application. This will only work if the other application as requested the name using the AllowReplace flag

Constructor & Destructor Documentation

QDBusConnection::QDBusConnection (  ) 

Creates an empty/disconnected connection handle.

This is mainly used for initializing variables of this type, i.e. like the default QString constructor.

A variable set to such an empty connection can be assigned a working connection at any time.

QDBusConnection::QDBusConnection ( const QString &  name  ) 

Creates a connection handle to a named connection.

This will result in an disconnected connection handle if no connection with that name has been created by addConnection before.

Therefore it is recommended to use addConnection() instead to get a connection handle.

Parameters:
name identifier of the shared connection object
QDBusConnection::QDBusConnection ( const QDBusConnection &  other  ) 

Creates a shallow copy of the given connection.

Allows to pass connection handles around by value, similar to QString thus avoiding problems like dangling pointers in application code

Parameters:
other the connection to copy from
QDBusConnection::~QDBusConnection (  ) 

Destroys the connection handle.

If this handle is the last one referencing the shared connection object it will delete it, disconnecting it from any objects it was collaborating with

Member Function Documentation

static QDBusConnection QDBusConnection::addConnection ( const QString &  address,
const QString &  name = default_connection_name 
) [static]

Add a connection to a bus at a specific address.

This is a factory method as it will create a connection for the given name if its not available yet, but return a previously created connection for that name if available.

Note:
this requires to know the address of a D-Bus daemon to connect to
Parameters:
address the address of the D-Bus daemon. Usually a Unix domain socket address
name the name to use for QDBusConnection's connection sharing
Returns:
a connection handle. Check isConnected() to find out if the connection attempt has been successfull
See also:
closeConnection()
static QDBusConnection QDBusConnection::addConnection ( BusType  type,
const QString &  name = default_connection_name 
) [static]

Add a connection to a bus with a specific bus type.

This is a factory method as it will create a connection for the given name if its not available yet, but return a previously created connection for that name if available.

Depending on the BusType the D-Bus library will connect to the address configured for that type, so this is the recommended way to create connection to D-Bus.

   // Associate the default connection name with a connection to the user's
   // session bus
   QDBusConnection con = QDBusConnection::addConnection(QDBusConnection::SessionBus);

   // check if we are connected and which uniqueName we got
   if (con.isConnected())
   {
       qDebug("Connected to session bus. We got uniqueName %s",
              con.uniqueName().local8Bit().data());
   }

For the common use cases see also sessionBus() and systemBus()

Parameters:
type the BusType of the bus to connect to
name the name to use for QDBusConnection's connection sharing
Returns:
a connection handle. Check isConnected() to find out if the connection attempt has been successfull
See also:
closeConnection()
static void QDBusConnection::closeConnection ( const QString &  name = default_connection_name  )  [static]

Closes a connection with a given name.

Removes the name from the pool of shared connections, i.e. a call to addConnection() with the same name afterwards will create a new connection.

Parameters:
name the connection name as used in addConnection()
bool QDBusConnection::connect ( QObject *  object,
const char *  slot 
)

Connects an object to receive D-Bus signals.

This provides a basic access to all D-Bus signals received on this connection. For every D-Bus signal processed by the connection object a Qt signal is emitted and thus delivered to all receiver objects connected through this method.

The required slot signature is 

   void slotname(const QDBusMessage&);

so a suitable receiver could look like this 

   class DBusSignalReceiver : public QObject
   {
       Q_OBJECT
   public slots:
       void dbusSignal(const QDBusMessage&);
   };

and would be connected like this 

    // assuming the following variables
    QDBusConnection connection;
    DBusSignalReceiver* receiver;

    connection.connect(receiver, SLOT(dbusSignal(const QDBusMessage&)));

See QDBusProxy::dbusSignal() for a more obvious way of connecting slots.

Parameters:
object the receiver object
slot the receiver slot (or signal for signal->signal connections)
Returns:
true if the connection was successfull, otherwise false
See also:
disconnect()
bool QDBusConnection::disconnect ( QObject *  object,
const char *  slot 
)

Disconnects a given receiver from the D-Bus signal handling.

Parameters:
object the receiver object to disconnect from
slot the receiver slot (or signal for signal->signal connections)
Returns:
true if the disconnect was successfull, otherwise false
See also:
connect()
void QDBusConnection::dispatch (  )  const

Processes buffered inbound messages.

Attempts to process all enqueued inbound messages, e.g. replies to method calls or received signals.

Warning:
dispatching message can result in Qt signals being emitted before this method returns. In case you just want to make sure no inbound message is forgotten, call scheduleDispatch() which will execute the dispatch delayed through the event loop.
void QDBusConnection::flush (  )  const

Flushes buffered outgoing message.

Attempts to send all enqueued outgoing messages before returning.

bool QDBusConnection::isConnected (  )  const

Returns whether the connection is connected to a bus.

Returns:
true if the connection can be used, false if the handle does not have access to a shared connection object or if the connection to the bus could not be established or broke
Examples:
example-client.cpp, and example-service.cpp.
QDBusError QDBusConnection::lastError (  )  const

Returns the last error seen by the connection.

This can be a connection error, e.g. attempt to connect failed, or a transmission error or an error reported by a method call

Returns:
the last error seen by the connection
QDBusConnection& QDBusConnection::operator= ( const QDBusConnection &  other  ) 

Creates a shallow copy of the given connection.

Allows to pass connection handles around by value, similar to QString thus avoiding problems like dangling pointers in application code

Parameters:
other the connection to copy from
Returns:
a reference to this instance as required by assigment operator semantics
bool QDBusConnection::registerObject ( const QString &  path,
QDBusObjectBase *  object 
)

Registers a service object for a given path.

In order to receive method calls over the D-Bus connection the service objects path within its host application has to be registered with the connection. See section Object paths for details.

Only one objects can be registered for a single object path, i.e. the path -> object mapping is unambiguous, similar to mapping of filesystem paths to files.

If a service object offers more than one interface it is up to the service implementation if all are implemented in the object path to this method or if the passed object is just another demultiplexer which relays the message to the interface implementor.

Parameters:
path the object path to register the object for
object the service implementation object for that path
Returns:
true if the given object is now registered for the given path or false if path is empty, object is null or another object is already registered for this path
See also:
unregisterObject()
bool QDBusConnection::requestName ( const QString &  name,
int  modeFlags = NoReplace 
)

Requests to be addressable on the bus by a given name.

Each connection to a bus gets a unique name once the connection is established. This is similar to getting an IP address when connecting to the Internet.

If an application's purpose is to provide services to other applications the other applications require to know how to address the service provider. Similar to a domain name on the Internet D-Bus allows to register names on the bus and be addressed through those names instead of the connection identifier.

Note:
this is not required if the application only needs to acccess services or only implements generic service APIs

If more than one application request the same name, D-Bus will try to resolve this conflict as good as possible. The NameRequestMode flags allow to control how an application prefers to be treated in such a conflict.

Parameters:
name the name the connection should be addressable with. See section Service names
modeFlags an OR'ed combination of NameRequestMode flags
Returns:
true if the name request was successfull, false if the connection is not connected to a bus or the name is already taken and cannot be tranferred
See also:
uniqueName()
Examples:
example-service.cpp.
void QDBusConnection::scheduleDispatch (  )  const

Request a delayed check for inbound buffer processing.

Similar to dispatch() but delayed by a single shot timer to ensure the method has returned before the processing is started.

If a asynchronous method call is followed by a synchronous call without returning to the event loop in between, a call to scheduleDispatch() ensures that a pending reply to the asynchronous call is processed as soon as possible

bool QDBusConnection::send ( const QDBusMessage &  message  )  const

Sends a message over the bus.

Sends a message composed through the QDBusMessage API to the bus. This is the main method for service objects (see QDBusObjectBase) to send replies and errors for method calls they accepted or for sending D-Bus signals.

Note:
for doing method calls it is more convenient to use QDBusProxy, see QDBusProxy::send()
Parameters:
message the message to send
Returns:
true if sending succeeded, false if the connection is not connected, if the message lacks information about the recepient or if sending fails a at a lower level in the communication stack
See also:
lastError()
int QDBusConnection::sendWithAsyncReply ( const QDBusMessage &  message,
QObject *  receiver,
const char *  slot 
) const

Sends a message over the bus, specifying a receiver object for replies.

Sends a message composed through the QDBusMessage API to the bus and returns an identifier number to associate with the reply once it is received by the given receiver. See QDBusMessage::replySerialNumber()

The required slot signature is 

   void slotname(const QDBusMessage&);
Note:
for doing method calls it is more convenient to use QDBusProxy, see QDBusProxy::sendWithAsyncReply()
Parameters:
message the message to send
receiver the QObject to relay the reply to
slot the slot to invoke for the reply
Returns:
a numeric identifier for association with the reply or 0 if sending failed
See also:
lastError()
QDBusMessage QDBusConnection::sendWithReply ( const QDBusMessage &  message,
QDBusError *  error = 0 
) const

Sends a message over the bus and waits for the reply.

Sends a message composed through the QDBusMessage API to the bus. It then blocks and waits until the associated reply is received. Any message received in between is stored and can be processed by calling dispatch() or scheduleDispatch()

Note:
for doing method calls it is more convenient to use QDBusProxy, see QDBusProxy::sendWithReply()
Parameters:
message the message to send
error an optional parameter to directly get any error that might occur during processing of the call
Returns:
a message containing either the call's reply or an invalid message in case the call failed
See also:
lastError()
static QDBusConnection QDBusConnection::sessionBus (  )  [static]

Gets a connection to the session bus.

Convenience overload for creating the default shared connection to the D-Bus session bus.

Equivalent to calling addConnection(SessionBus);

Returns:
a connection handle. Check isConnected() to find out if the connection attempt has been successfull
See also:
addConnection(BusType,const QString&);
Examples:
example-client.cpp, and example-service.cpp.
static QDBusConnection QDBusConnection::systemBus (  )  [static]

Gets a connection to the system bus.

Convenience overload for creating the default shared connection to the D-Bus system bus.

Equivalent to calling addConnection(SystemBus);

Returns:
a connection handle. Check isConnected() to find out if the connection attempt has been successfull
See also:
addConnection(BusType,const QString&);
QString QDBusConnection::uniqueName (  )  const

Returns the connection identifier assigned at connect.

The unique name is the connection address or identifier the bus assigned to this connection when it got established.

Returns:
the connection's unique bus identifier
See also:
requestName()
Examples:
example-client.cpp, and example-service.cpp.
void QDBusConnection::unregisterObject ( const QString &  path  ) 

Unregister a service object on a given path.

Removes any mapping of object path to service object previously registered by registerObject(). See section Object paths for details.

Warning:
always(!) unregister a service object before deleting it
Parameters:
path the object path of the object to unregister
See also:
registerObject()

Member Data Documentation

QT_STATIC_CONST char* QDBusConnection::default_connection_name

String used as the default parameter for connection names

The documentation for this class was generated from the following file:
Generated by  doxygen 1.6.2