CopperSpice DBUS  1.7.4
QDBusConnection Class Reference

Represents a connection to the D-Bus bus daemon. More...

Public Types

enum  BusType
 

Public Methods

 QDBusConnection (const QDBusConnection &other)
 
 QDBusConnection (const QString &name)
 
 QDBusConnection (QDBusConnection &&other) noexcept
 
 ~QDBusConnection ()
 
QDBusPendingCall asyncCall (const QDBusMessage &message, int timeout=-1) const
 
QString baseService () const
 
QDBusMessage call (const QDBusMessage &message, QDBus::CallMode mode=QDBus::Block, int timeout=-1) const
 
bool callWithCallback (const QDBusMessage &message, QObject *receiver, const QString &returnMethod, const QString &errorMethod, int timeout=-1) const
 
bool connect (const QString &serviceName, const QString &path, const QString &interfaceId, const QString &name, const QString &signature, QObject *receiver, const QString &slot)
 
bool connect (const QString &serviceName, const QString &path, const QString &interfaceId, const QString &name, const QStringList &argumentMatch, const QString &signature, QObject *receiver, const QString &slot)
 
bool connect (const QString &serviceName, const QString &path, const QString &interfaceId, const QString &name, QObject *receiver, const QString &slot)
 
ConnectionCapabilities connectionCapabilities () const
 
bool disconnect (const QString &serviceName, const QString &path, const QString &interfaceId, const QString &name, const QString &signature, QObject *receiver, const QString &slot)
 
bool disconnect (const QString &serviceName, const QString &path, const QString &interfaceId, const QString &name, const QStringList &argumentMatch, const QString &signature, QObject *receiver, const QString &slot)
 
bool disconnect (const QString &serviceName, const QString &path, const QString &interfaceId, const QString &name, QObject *receiver, const QString &slot)
 
QDBusConnectionInterfaceinterface () const
 
bool isConnected () const
 
QDBusError lastError () const
 
QString name () const
 
QObject * objectRegisteredAt (const QString &path) const
 
QDBusConnection & operator= (const QDBusConnection &other)
 
QDBusConnection & operator= (QDBusConnection &&other) noexcept
 
bool registerObject (const QString &path, const QString &interfaceId, QObject *object, RegisterOptions options=ExportAdaptors)
 
bool registerObject (const QString &path, QObject *object, RegisterOptions options=ExportAdaptors)
 
bool registerService (const QString &serviceName)
 
bool send (const QDBusMessage &message) const
 
void swap (QDBusConnection &other) noexcept
 
void unregisterObject (const QString &path, UnregisterMode mode=UnregisterNode)
 
bool unregisterService (const QString &serviceName)
 

Static Public Methods

static QDBusConnection connectToBus (BusType type, const QString &name)
 
static QDBusConnection connectToBus (const QString &address, const QString &name)
 
static QDBusConnection connectToPeer (const QString &address, const QString &name)
 
static void disconnectFromBus (const QString &name)
 
static void disconnectFromPeer (const QString &name)
 
static QByteArray localMachineId ()
 
static QDBusConnection sessionBus ()
 
static QDBusConnection systemBus ()
 

Detailed Description

The QDBusConnection class represents a connection to the D-Bus bus daemon.

This class is the initial point in a D-Bus session. Using it, you can get access to remote objects, interfaces; connect remote signals to your object's slots; register objects, etc.

D-Bus connections are created using the connectToBus() method, which opens a connection to the server daemon and does the initial handshaking, associating that connection with a name. Further attempts to connect using the same name will return the same connection.

The connection is then torn down using the disconnectFromBus() method.

Once disconnected, calling connectToBus() will not reestablish a connection, you must create a new QDBusConnection instance.

As a convenience for the two most common connection types, the sessionBus() and systemBus() methods return open connections to the session server daemon and the system server daemon, respectively. Those connections are opened when first used and are closed when the QCoreApplication destructor is run.

D-Bus also supports peer-to-peer connections, without the need for a bus server daemon. Using this facility, two applications can talk to each other and exchange messages. This can be achieved by passing an address to connectToBus() method, which was opened by another D-Bus application using QDBusServer.

See also
connectionCapabilities()

Member Enumeration Documentation

Specifies the type of the bus connection. The valid bus types are shown in the table below.

On the Session Bus, one can find other applications by the same user that are sharing the same desktop session (hence the name). On the System Bus, however, processes shared for the whole system are usually found.

Constant Value Description
QDBusConnection::SessionBus 0 Session bus, associated with the running desktop session
QDBusConnection::SystemBus 1 System bus, used to communicate with system-wide processes
QDBusConnection::ActivationBus 2 Activation bus, the "alias" for the bus that started the service

Constructor & Destructor Documentation

QDBusConnection::QDBusConnection ( const QString &  name)
explicit

Creates a QDBusConnection object attached to the connection with name name. This does not open the connection. You have to call connectToBus() to open it.

QDBusConnection::QDBusConnection ( const QDBusConnection &  other)

Copy constructs a new QDBusConnection from other.

QDBusConnection::QDBusConnection ( QDBusConnection &&  other)
inlinenoexcept

Move constructs a new QDBusConnection from other.

QDBusConnection::~QDBusConnection ( )

Disposes of this object. This does not close the connection: you have to call disconnectFromBus() to do that.

Method Documentation

QDBusPendingCall QDBusConnection::asyncCall ( const QDBusMessage message,
int  timeout = -1 
) const

Sends the message over this connection and returns immediately. This method is suitable for method calls only. It returns an object of type QDBusPendingCall which can be used to track the status of the reply.

If no reply is received within timeout milliseconds, an automatic error will be delivered indicating the expiration of the call. The default timeout is -1, which will be replaced with an implementation-defined value that is suitable for inter-process communications (generally, 25 seconds). This timeout is also the upper limit for waiting in QDBusPendingCall::waitForFinished().

Refer to QDBusInterface::asyncCall() for a more friendly way of placing calls.

QString QDBusConnection::baseService ( ) const

Returns the unique connection name for this connection, if this QDBusConnection object is connected, or an empty QString otherwise.

A Unique Connection Name is a string in the form ":x.xxx" (where x are decimal digits) that is assigned by the D-Bus server daemon upon connection. It uniquely identifies this client in the bus.

This method returns an empty QString for peer-to-peer connections.

QDBusMessage QDBusConnection::call ( const QDBusMessage message,
QDBus::CallMode  mode = QDBus::Block,
int  timeout = -1 
) const

Sends the message over this connection and blocks, waiting for a reply, for at most timeout milliseconds. This method is suitable for method calls only. It returns the reply message as its return value, which will be either of type QDBusMessage::ReplyMessage or QDBusMessage::ErrorMessage.

If no reply is received within timeout milliseconds, an automatic error will be delivered indicating the expiration of the call. The default timeout is -1, which will be replaced with an implementation-defined value that is suitable for inter-process communications (generally, 25 seconds).

Refer to QDBusInterface::call() for a more friendly way of placing calls.

Warning
If mode is QDBus::BlockWithGui, this method will reenter the event loop in order to wait for the reply. During the wait, it may deliver signals and other method calls to your application. Therefore, it must be prepared to handle a reentrancy whenever a call is placed with call().
bool QDBusConnection::callWithCallback ( const QDBusMessage message,
QObject *  receiver,
const QString &  returnMethod,
const QString &  errorMethod,
int  timeout = -1 
) const

Sends the message over this connection and returns immediately. When the reply is received, the method returnMethod is called in the receiver object. If an error occurs, the method errorMethod will be called instead.

If no reply is received within timeout milliseconds, an automatic error will be delivered indicating the expiration of the call. The default timeout is -1, which will be replaced with an implementation-defined value that is suitable for inter-process communications (generally, 25 seconds).

This method is suitable for method calls only. It is guaranteed that the slot will be called exactly once with the reply, as long as the parameter types match and no error occurs.

Returns true if the message was sent, or false if the message could not be sent.

bool QDBusConnection::connect ( const QString &  serviceName,
const QString &  path,
const QString &  interfaceId,
const QString &  name,
const QString &  signature,
QObject *  receiver,
const QString &  slot 
)

Connects the signal specified by the serviceName, path, interfaceId, and name parameters to the slot method in the receiver object.

Unlike other versions of connect(), this overload allows specifying the signature to be connected using the signature variable. The method will verify the signature can be delivered to the given slot.

Returns true if the connection was successful.

Note
This method verifies the signal signature matches the slot's parameters. It does not verify the actual signal exists with the given signature in the remote service.
bool QDBusConnection::connect ( const QString &  serviceName,
const QString &  path,
const QString &  interfaceId,
const QString &  name,
const QStringList &  argumentMatch,
const QString &  signature,
QObject *  receiver,
const QString &  slot 
)

Connects the signal specified by the serviceName, path, interfaceId, and name parameters to the slot method in the receiver object.

The argumentMatch parameter lists the string parameters to be matched, in sequential order.

Unlike other versions of connect(), this overload allows specifying the signature to be connected using the signature variable. The method will verify the signature can be delivered to the given slot.

Returns true if the connection was successful.

Note
This method verifies the signal signature matches the slot's parameters. It does not verify the actual signal exists with the given signature in the remote service.
bool QDBusConnection::connect ( const QString &  serviceName,
const QString &  path,
const QString &  interfaceId,
const QString &  name,
QObject *  receiver,
const QString &  slot 
)

Connects the signal specified by the serviceName, path, interfaceId, and name parameters to the slot method in the receiver object. The arguments service and path can be empty which denotss a connection to any signal of the (interfaceId, name) pair from any remote application.

Returns true if the connection was successful.

Warning
The signal will only be delivered to the slot if the parameters match. This verification can be done only when the signal is received, not at connection time.
ConnectionCapabilities QDBusConnection::connectionCapabilities ( ) const

Returns the capabilities of this connection as negotiated with the bus server or peer. If this QDBusConnection is not connected this method returns no capabilities.

QDBusConnection QDBusConnection::connectToBus ( BusType  type,
const QString &  name 
)
static

Opens a connection of the given type to one of the known buses and associates it with the connection name. Returns a QDBusConnection object associated with that connection.

QDBusConnection QDBusConnection::connectToBus ( const QString &  address,
const QString &  name 
)
static

Opens a connection to a private bus at the given address and associates it with the connection name. Returns a QDBusConnection object associated with that connection.

QDBusConnection QDBusConnection::connectToPeer ( const QString &  address,
const QString &  name 
)
static

Opens a peer-to-peer connection at the given address and associates it wtih the connection name. Returns a QDBusConnection object associated with that connection.

bool QDBusConnection::disconnect ( const QString &  serviceName,
const QString &  path,
const QString &  interfaceId,
const QString &  name,
const QString &  signature,
QObject *  receiver,
const QString &  slot 
)

Disconnects the signal specified by the serviceName, path, interfaceId, name, and signature parameters from the slot method in the receiver object. The arguments must be the same as what was passed to connect().

Returns true if the disconnection was successful.

bool QDBusConnection::disconnect ( const QString &  serviceName,
const QString &  path,
const QString &  interfaceId,
const QString &  name,
const QStringList &  argumentMatch,
const QString &  signature,
QObject *  receiver,
const QString &  slot 
)

Disconnects the signal specified by the serviceName, path, interfaceId, name, argumentMatch, and signature parameters from the slot method in the receiver object. The arguments must be the same as what was passed to connect().

Returns true if the disconnection was successful.

bool QDBusConnection::disconnect ( const QString &  serviceName,
const QString &  path,
const QString &  interfaceId,
const QString &  name,
QObject *  receiver,
const QString &  slot 
)

Disconnects the signal specified by the serviceName, path, interfaceId, and name parameters from the slot method in the receiver object. The arguments must be the same as what was passed to connect().

Returns true if the disconnection was successful.

void QDBusConnection::disconnectFromBus ( const QString &  name)
static

Closes the bus connection of the given name. If there are still QDBusConnection objects associated with the same connection, the connection will not be closed until all references are dropped. However, no further references can be created using the QDBusConnection constructor.

void QDBusConnection::disconnectFromPeer ( const QString &  name)
static

Closes the peer connection of the given name. If there are still QDBusConnection objects associated with the same connection, the connection will not be closed until all references are dropped. However, no further references can be created using the QDBusConnection constructor.

QDBusConnectionInterface * QDBusConnection::interface ( ) const

Returns a QDBusConnectionInterface object that represents the D-Bus server interface on this connection.

bool QDBusConnection::isConnected ( ) const

Returns true if this QDBusConnection object is connected.

QDBusError QDBusConnection::lastError ( ) const

Returns the last error that happened in this connection. This method is provided for low-level code. If you are using QDBusInterface::call(), error codes are reported by its return value.

See also
QDBusInterface, QDBusMessage
QByteArray QDBusConnection::localMachineId ( )
static

Returns the local machine ID as known to the D-Bus system. Each node or host that runs D-Bus has a unique identifier that can be used to distinguish it from other hosts if they are sharing resources like the filesystem.

Note that the local machine ID is not guaranteed to be persistent across boots of the system, so this identifier should not be stored in persistent storage (like the filesystem). It is guaranteed to remain constant only during the lifetime of this boot session.

QString QDBusConnection::name ( ) const

Returns the connection name for this connection, as given as the name parameter to connectToBus().

The connection name can be used to uniquely identify actual underlying connections to buses. Copies made from a single connection will always implicitly share the underlying connection, and hence will have the same connection name.

Inversely, two connections having different connection names will always either be connected to different buses, or have a different unique name (as returned by baseService()) on that bus.

See also
connectToBus(), disconnectFromBus()
QObject * QDBusConnection::objectRegisteredAt ( const QString &  path) const

Return the object that was registered with the registerObject() at the object path given by path.

QDBusConnection & QDBusConnection::operator= ( const QDBusConnection &  other)

Copy assigns from other and returns a reference to this object.

The connection this object referenced before the copy is not spontaneously disconnected. BROOM

See also
disconnectFromBus()
QDBusConnection & QDBusConnection::operator= ( QDBusConnection &&  other)
inlinenoexcept

Move assigns from other and returns a reference to this object.

bool QDBusConnection::registerObject ( const QString &  path,
const QString &  interfaceId,
QObject *  object,
RegisterOptions  options = ExportAdaptors 
)

Registers the object object at the given path with interface name interfaceId and returns true if the registration was successful. The options parameter specifies how much of the object will be exposed through D-Bus. This method does not replace existing objects. If there is already an object registered at path, this method will return false. Use unregisterObject() to unregister it first.

It is not possible to register an object as a child object, of an object that was registered with QDBusConnection::ExportChildObjects.

bool QDBusConnection::registerObject ( const QString &  path,
QObject *  object,
RegisterOptions  options = ExportAdaptors 
)

Registers the object object at path path and returns true if the registration was successful. The options parameter specifies how much of the object will be exposed through D-Bus. This function does not replace existing objects: if there is already an object registered at path, this method will return false. Use unregisterObject() to unregister it first.

It is not possible to register an object as a child object, of an object that was registered with QDBusConnection::ExportChildObjects.

bool QDBusConnection::registerService ( const QString &  serviceName)

Attempts to register the serviceName on the D-Bus server and returns true if the registration succeeded. The registration will fail if the name is already registered by another application.

See also
unregisterService(), QDBusConnectionInterface::registerService()
bool QDBusConnection::send ( const QDBusMessage message) const

Sends the message over this connection, without waiting for a reply. This is suitable for errors, signals, and return values as well as calls whose return values are not necessary. Returns true if the message was queued successfully, false otherwise.

QDBusConnection QDBusConnection::sessionBus ( )
static

Returns a QDBusConnection object opened with the session bus. The object reference returned by this function is valid until the application terminates, at which point the connection will be closed and the object deleted.

void QDBusConnection::swap ( QDBusConnection &  other)
inlinenoexcept

Swaps other with this object. This operation is very fast and never fails.

QDBusConnection QDBusConnection::systemBus ( )
static

Returns a QDBusConnection object opened with the system bus. The object reference returned by this function is valid until the QCoreApplication's destructor is run, when the connection will be closed and the object, deleted.

void QDBusConnection::unregisterObject ( const QString &  path,
UnregisterMode  mode = UnregisterNode 
)

Unregisters an object that was registered with the registerObject() at the object path given by path and, if mode is QDBusConnection::UnregisterTree, all of its sub-objects too.

You can not unregister objects that were not registered with registerObject().

bool QDBusConnection::unregisterService ( const QString &  serviceName)

Unregisters the service serviceName that was previously registered with registerService() and returns true if it succeeded.

See also
registerService(), QDBusConnectionInterface::unregisterService()