QDBusConnection Class

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

List of all members, including inherited members

Public Types

Public Functions

Static Public Members

Detailed Description

A connection talks to a bus, usually the session bus or the system bus, or directly to one peer. Through it a program calls methods of remote objects, exports objects of its own, claims service names and receives signals:

QDBusConnection bus = QDBusConnection::sessionBus();
if (!bus.isConnected()) {
    std::fprintf(stderr, "No session bus: %s\n", qPrintable(bus.lastError().message()));
    return 1;
}
auto *clock = new Clock;
new ClockAdaptor(clock);
bus.registerObject("/clock", clock);
if (!bus.registerService("org.example.Clock")) {
    std::fprintf(stderr, "org.example.Clock is taken: %s\n", qPrintable(bus.lastError().message()));
    return 1;
}

A client calls the exported object:

QDBusConnection bus = QDBusConnection::sessionBus();
QDBusInterface clock("org.example.Clock", "/clock", "org.example.Clock", bus);
QDBusReply<QString> now = clock.call("Now");
if (!now.isValid()) {
    std::fprintf(stderr, "Cannot reach the clock: %s\n", qPrintable(now.error().message()));
    return 1;
}
std::printf("It is %s, volume %d\n", qPrintable(now.value()), clock.property("volume").toInt());

QDBusConnection is a handle to a shared connection: copies refer to the same one, and it can be used from any thread. Connections to a bus are identified by a name, so QDBusConnection(name) returns one made earlier with connectToBus().

Every connection is serviced by one thread that Nt starts. Calls to exported objects and signals for slots are delivered through the event loop of the thread that the receiving object lives in, so that thread must run an event loop. A blocking call() does not run the calling thread's event loop, except with QDBus::BlockWithGui; a blocking call to an object that this connection exports and that lives in the calling thread is delivered directly.

See also QDBusAbstractInterface, QDBusAbstractAdaptor, QDBusServer and Using Nt D-Bus.

Differences from Qt

Member Type Documentation

enum QDBusConnection::BusType

The standard buses.

typedef QDBusConnection::ConnectionCapabilities

The ConnectionCapabilities type is a typedef for QFlags<ConnectionCapability>. It stores an OR combination of ConnectionCapability values.

enum QDBusConnection::ConnectionCapability

enum QDBusConnection::RegisterOption

Selects what registerObject() exports from an object.

typedef QDBusConnection::RegisterOptions

The RegisterOptions type is a typedef for QFlags<RegisterOption>. It stores an OR combination of RegisterOption values.

enum QDBusConnection::UnregisterMode

enum QDBusConnection::VirtualObjectRegisterOption

typedef QDBusConnection::VirtualObjectRegisterOptions

The VirtualObjectRegisterOptions type is a typedef for QFlags<VirtualObjectRegisterOption>. It stores an OR combination of VirtualObjectRegisterOption values.

Member Function Documentation

[explicit] QDBusConnection::QDBusConnection(const QString &name)

Constructs a handle to the connection called name, made earlier with connectToBus() or connectToPeer(). If there is none, the handle is not connected.

QDBusConnection::QDBusConnection(const QDBusConnection &other)

Constructs a handle to the connection that other refers to.

QDBusConnection::QDBusConnection(QDBusConnection &&other)

Constructs a handle that takes the place of other.

QDBusConnection::~QDBusConnection()

Destroys the handle. The connection stays open while it has a name or other handles.

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

Sends message and returns an object that follows the call. The call fails after timeout milliseconds, or 25 seconds if it is -1.

See also QDBusPendingCallWatcher and QDBusPendingReply.

QString QDBusConnection::baseService() const

Returns the unique name that the bus gave this connection, such as :1.42. It is empty for a connection to a peer.

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

Sends message and waits as mode says for the reply, which it returns. The call fails with NoReply after timeout milliseconds, or 25 seconds if it is -1. With QDBus::NoBlock the function returns at once.

See also asyncCall() and QDBusReply.

bool QDBusConnection::callWithCallback(const QDBusMessage &message, QObject *receiver, const char *returnMethod, const char *errorMethod, int timeout = -1) const

Sends the call message and returns at once. When the reply arrives, returnMethod of receiver is called with its arguments; on an error, errorMethod is called with a QDBusError and, if it takes one, the QDBusMessage. Name the slots with SLOT(). The call fails after timeout milliseconds, or the default of 25 seconds if it is -1. Returns true if the call was sent.

bool QDBusConnection::callWithCallback(const QDBusMessage &message, QObject *receiver, const char *slot, int timeout = -1) const

This is an overloaded function.

Sends message and calls slot of receiver with the reply. Errors are ignored. timeout is in milliseconds.

bool QDBusConnection::connect(const QString &service, const QString &path, const QString &interface, const QString &name, QObject *receiver, const char *slot)

Connects the signal name of interface, emitted by the object at path of service, to slot of receiver, named with SLOT() or SIGNAL(). An empty argument matches anything. The slot receives the leading arguments of the signal that it has parameters for, and the QDBusMessage if its last parameter is one. Returns true on success.

See also disconnect().

bool QDBusConnection::connect(const QString &service, const QString &path, const QString &interface, const QString &name, const QString &signature, QObject *receiver, const char *slot)

This is an overloaded function.

Connects only to signals whose arguments have the D-Bus signature. service, path, interface, name, receiver and slot are as above.

bool QDBusConnection::connect(const QString &service, const QString &path, const QString &interface, const QString &name, const QStringList &argumentMatch, const QString &signature, QObject *receiver, const char *slot)

This is an overloaded function.

Connects only to signals whose leading string arguments equal argumentMatch; an empty string in the list matches any value. service, path, interface, name, signature, receiver and slot are as above.

ConnectionCapabilities QDBusConnection::connectionCapabilities() const

Returns what the connection can do.

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

Connects to the bus type and names the connection name. If a connection of that name exists, it is returned.

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

This is an overloaded function.

Connects to the bus at address and names the connection name.

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

Connects to the peer at address, such as a QDBusServer, and names the connection name.

bool QDBusConnection::disconnect(const QString &service, const QString &path, const QString &interface, const QString &name, QObject *receiver, const char *slot)

Removes the connection that connect() made with the same service, path, interface, name, receiver and slot. Returns true if there was one.

bool QDBusConnection::disconnect(const QString &service, const QString &path, const QString &interface, const QString &name, const QString &signature, QObject *receiver, const char *slot)

This is an overloaded function.

Removes the connection made with the same service, path, interface, name, signature, receiver and slot.

bool QDBusConnection::disconnect(const QString &service, const QString &path, const QString &interface, const QString &name, const QStringList &argumentMatch, const QString &signature, QObject *receiver, const char *slot)

This is an overloaded function.

Removes the connection made with the same service, path, interface, name, argumentMatch, signature, receiver and slot.

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

Forgets the connection called name. It is closed once no QDBusConnection refers to it.

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

Forgets the connection to a peer called name. It is closed once no QDBusConnection refers to it.

QDBusConnectionInterface * QDBusConnection::interface() const

Returns an interface to the bus itself, or nullptr for a connection to a peer. The connection owns it.

bool QDBusConnection::isConnected() const

Returns true if the connection is open.

QDBusError QDBusConnection::lastError() const

Returns the error of the last operation that failed, such as connecting or a blocking call.

[static] QByteArray QDBusConnection::localMachineId()

Returns the machine id of this computer, from /etc/machine-id.

QString QDBusConnection::name() const

Returns the name of the connection.

QObject * QDBusConnection::objectRegisteredAt(const QString &path) const

Returns the object registered at path, or nullptr.

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

Makes this handle refer to the connection of other and returns a reference to it.

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

Moves other into this handle and returns a reference to it.

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

Exports object at path. options selects what is exported; by default, the adaptors that are children of the object. Returns false if the path is taken or invalid. The object is unregistered when it is destroyed.

See also unregisterObject() and QDBusAbstractAdaptor.

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

This is an overloaded function.

Exports object at path and names the interface of its own members interface, instead of the name its class gives. options selects what is exported.

bool QDBusConnection::registerService(const QString &serviceName)

Claims the well-known name serviceName on the bus. Returns false if another connection owns it.

See also unregisterService() and QDBusConnectionInterface::registerService().

bool QDBusConnection::registerVirtualObject(const QString &path, QDBusVirtualObject *object, VirtualObjectRegisterOption options = SingleNode)

Exports object at path, where it handles calls itself. With SubPath as options it also handles every path below. Returns false if the path is taken or invalid.

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

Sends message without waiting for a reply and returns true if it was queued. A method call sent this way tells the receiver that no reply is wanted.

[static] QDBusConnection QDBusConnection::sessionBus()

Returns the connection to the session bus, opening it the first time.

void QDBusConnection::swap(QDBusConnection &other)

Swaps this handle with other.

[static] QDBusConnection QDBusConnection::systemBus()

Returns the connection to the system bus, opening it the first time.

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

Unregisters the object at path, and with UnregisterTree as mode every object below.

bool QDBusConnection::unregisterService(const QString &serviceName)

Releases the name serviceName. Returns true if this connection owned it.