|  | Home · All Classes · Modules

# QDBusConnection Class Reference
[QtDBus module]

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

### Types

- enum BusType { SessionBus, SystemBus, ActivationBus }
- class ConnectionCapabilities
- enum ConnectionCapability { UnixFileDescriptorPassing }
- enum RegisterOption { ExportAdaptors, ExportScriptableSlots, ExportScriptableSignals, ExportScriptableProperties, ..., ExportChildObjects }
- class RegisterOptions
- enum UnregisterMode { UnregisterNode, UnregisterTree }

### Methods

- __init__ (self, QString name)
- __init__ (self, QDBusConnection other)
- QDBusPendingCall asyncCall (self, QDBusMessage message, int timeout = -1)
- QString baseService (self)
- QDBusMessage call (self, QDBusMessage message, QDBus.CallMode mode = QDBus.Block, int timeout = -1)
- bool callWithCallback (self, QDBusMessage message, QObject receiver, SLOT() returnMethod, SLOT() errorMethod, int timeout = -1)
- object callWithCallback (self, QDBusMessage message, callable returnMethod, callable errorMethod, int timeout = -1)
- bool callWithCallback (self, QDBusMessage message, QObject receiver, SLOT() slot, int timeout = -1)
- object callWithCallback (self, QDBusMessage message, callable slot, int timeout = -1)
- bool connect (self, QString service, QString path, QString interface, QString name, QObject receiver, SLOT() slot)
- object connect (self, QString service, QString path, QString interface, QString name, callable slot)
- bool connect (self, QString service, QString path, QString interface, QString name, QString signature, QObject receiver, SLOT() slot)
- object connect (self, QString service, QString path, QString interface, QString name, QString signature, callable slot)
- bool connect (self, QString service, QString path, QString interface, QString name, QStringList argumentMatch, QString signature, QObject receiver, SLOT() slot)
- object connect (self, QString service, QString path, QString interface, QString name, QStringList argumentMatch, QString signature, callable slot)
- ConnectionCapabilities connectionCapabilities (self)
- bool disconnect (self, QString service, QString path, QString interface, QString name, QObject receiver, SLOT() slot)
- object disconnect (self, QString service, QString path, QString interface, QString name, callable slot)
- bool disconnect (self, QString service, QString path, QString interface, QString name, QString signature, QObject receiver, SLOT() slot)
- object disconnect (self, QString service, QString path, QString interface, QString name, QString signature, callable slot)
- bool disconnect (self, QString service, QString path, QString interface, QString name, QStringList argumentMatch, QString signature, QObject receiver, SLOT() slot)
- object disconnect (self, QString service, QString path, QString interface, QString name, QStringList argumentMatch, QString signature, callable slot)
- QDBusConnectionInterface interface (self)
- bool isConnected (self)
- QDBusError lastError (self)
- QString name (self)
- QObject objectRegisteredAt (self, QString path)
- bool registerObject (self, QString path, QObject object, RegisterOptions options = QDBusConnection.ExportAdaptors)
- bool registerService (self, QString serviceName)
- bool send (self, QDBusMessage message)
- unregisterObject (self, QString path, UnregisterMode mode = QDBusConnection.UnregisterNode)
- bool unregisterService (self, QString serviceName)

### Static Methods

- QDBusConnection connectToBus (BusType type, QString name)
- QDBusConnection connectToBus (QString address, QString name)
- QDBusConnection connectToPeer (QString address, QString name)
- disconnectFromBus (QString name)
- disconnectFromPeer (QString name)
- QByteArray localMachineId ()
- QDBusConnection sender ()
- QDBusConnection sessionBus ()
- 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() function, 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() function.

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() functions 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() function, which was opened by another D-Bus application using QDBusServer.

## Type Documentation

### QDBusConnection.BusType

Specifies the type of the bus connection. The valid bus types are:

Constant | Value | Description
--- | --- | ---
`QDBusConnection.SessionBus` | `0` | the session bus, associated with the running desktop session
`QDBusConnection.SystemBus` | `1` | the system bus, used to communicate with system-wide processes
`QDBusConnection.ActivationBus` | `2` | the activation bus, the "alias" for the bus that started the service

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.

### QDBusConnection.ConnectionCapability

This enum describes the available capabilities for a D-Bus connection.

Constant | Value | Description
--- | --- | ---
`QDBusConnection.UnixFileDescriptorPassing` | `0x0001` | enables passing of Unix file descriptors to other processes (see QDBusUnixFileDescriptor)

This enum was introduced or modified in Qt 4.8.

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

See also connectionCapabilities().

### QDBusConnection.RegisterOption

Specifies the options for registering objects with the connection. The possible values are:

Constant | Value | Description
--- | --- | ---
`QDBusConnection.ExportAdaptors` | `0x01` | export the contents of adaptors found in this object
`QDBusConnection.ExportScriptableSlots` | `0x10` | export this object's scriptable slots
`QDBusConnection.ExportScriptableSignals` | `0x20` | export this object's scriptable signals
`QDBusConnection.ExportScriptableProperties` | `0x40` | export this object's scriptable properties
`QDBusConnection.ExportScriptableInvokables` | `0x80` | export this object's scriptable invokables
`QDBusConnection.ExportScriptableContents` | `0xf0` | shorthand form for ExportScriptableSlots | ExportScriptableSignals | ExportScriptableProperties
`QDBusConnection.ExportNonScriptableSlots` | `0x100` | export this object's non-scriptable slots
`QDBusConnection.ExportNonScriptableSignals` | `0x200` | export this object's non-scriptable signals
`QDBusConnection.ExportNonScriptableProperties` | `0x400` | export this object's non-scriptable properties
`QDBusConnection.ExportNonScriptableInvokables` | `0x800` | export this object's non-scriptable invokables
`QDBusConnection.ExportNonScriptableContents` | `0xf00` | shorthand form for ExportNonScriptableSlots | ExportNonScriptableSignals | ExportNonScriptableProperties
`QDBusConnection.ExportAllSlots` | `ExportScriptableSlots | ExportNonScriptableSlots` | export all of this object's slots
`QDBusConnection.ExportAllSignals` | `ExportScriptableSignals | ExportNonScriptableSignals` | export all of this object's signals
`QDBusConnection.ExportAllProperties` | `ExportScriptableProperties | ExportNonScriptableProperties` | export all of this object's properties
`QDBusConnection.ExportAllInvokables` | `ExportScriptableInvokables | ExportNonScriptableInvokables` | export all of this object's invokables
`QDBusConnection.ExportAllContents` | `ExportScriptableContents | ExportNonScriptableContents` | export all of this object's contents
`QDBusConnection.ExportChildObjects` | `0x1000` | export this object's child objects

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

See also registerObject(), QDBusAbstractAdaptor, and Using adaptors.

### QDBusConnection.UnregisterMode

The mode for unregistering an object path:

Constant | Value | Description
--- | --- | ---
`QDBusConnection.UnregisterNode` | `0` | unregister this node only: do not unregister child objects
`QDBusConnection.UnregisterTree` | `1` | unregister this node and all its sub-tree

Note, however, if this object was registered with the ExportChildObjects option, UnregisterNode will unregister the child objects too.

## Method Documentation

### QDBusConnection.__init__ (self, QString name)

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.__init__ (self, QDBusConnection other)

Creates a copy of the other connection.

### QDBusPendingCall QDBusConnection.asyncCall (self, QDBusMessage message, int timeout = -1)

Sends the message over this connection and returns immediately. This function 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().

See the QDBusInterface.asyncCall() function for a more friendly way of placing calls.

This function was introduced in Qt 4.5.

### QString QDBusConnection.baseService (self)

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 function returns an empty QString for peer-to-peer connections.

### QDBusMessage QDBusConnection.call (self, QDBusMessage message, QDBus.CallMode mode = QDBus.Block, int timeout = -1)

Sends the message over this connection and blocks, waiting for a reply, for at most timeout milliseconds. This function 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).

See the QDBusInterface.call() function for a more friendly way of placing calls.

Warning: If mode is QDBus.BlockWithGui, this function will reenter the Qt 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 (self, QDBusMessage message, QObject receiver, SLOT() returnMethod, SLOT() errorMethod, int timeout = -1)

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 function 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.

### object QDBusConnection.callWithCallback (self, QDBusMessage message, callable returnMethod, callable errorMethod, int timeout = -1)

This function is deprecated.

This is an overloaded function.

Sends the message over this connection and returns immediately. When the reply is received, the method returnMethod is called in the receiver object.

This function 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.

This function is dangerous because it cannot report errors, including the expiration of the timeout.

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

### bool QDBusConnection.callWithCallback (self, QDBusMessage message, QObject receiver, SLOT() slot, int timeout = -1)

### object QDBusConnection.callWithCallback (self, QDBusMessage message, callable slot, int timeout = -1)

### bool QDBusConnection.connect (self, QString service, QString path, QString interface, QString name, QObject receiver, SLOT() slot)

Connects the signal specified by the service, path, interface and name parameters to the slot slot in object receiver. The arguments service and path can be empty, denoting a connection to any signal of the (interface, 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.

### object QDBusConnection.connect (self, QString service, QString path, QString interface, QString name, callable slot)

This is an overloaded function.

Connects the signal to the slot slot in object receiver. Unlike the previous connect() overload, this function allows one to specify the parameter signature to be connected using the signature variable. The function will then verify that this signature can be delivered to the slot specified by slot and return false otherwise.

Returns true if the connection was successful.

Note: This function verifies that the signal signature matches the slot's parameters, but it does not verify that the actual signal exists with the given signature in the remote service.

### bool QDBusConnection.connect (self, QString service, QString path, QString interface, QString name, QString signature, QObject receiver, SLOT() slot)

This is an overloaded function.

Connects the signal to the slot slot in object receiver. Unlike the previous connect() overload, this function allows one to specify the parameter signature to be connected using the signature variable. The function will then verify that this signature can be delivered to the slot specified by slot and return false otherwise.

The argumentMatch parameter lists the string parameters to be matched, in sequential order. Note that, to match an empty string, you need to pass a QString that is empty but not null (i.e., QString("")). A null QString skips matching at that position.

Returns true if the connection was successful.

Note: This function verifies that the signal signature matches the slot's parameters, but it does not verify that the actual signal exists with the given signature in the remote service.

This function was introduced in Qt 4.6.

### object QDBusConnection.connect (self, QString service, QString path, QString interface, QString name, QString signature, callable slot)

### bool QDBusConnection.connect (self, QString service, QString path, QString interface, QString name, QStringList argumentMatch, QString signature, QObject receiver, SLOT() slot)

### object QDBusConnection.connect (self, QString service, QString path, QString interface, QString name, QStringList argumentMatch, QString signature, callable slot)

### ConnectionCapabilities QDBusConnection.connectionCapabilities (self)

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

This function was introduced in Qt 4.8.

### QDBusConnection QDBusConnection.connectToBus (BusType type, QString name)

Opens a connection of type type to one of the known busses and associate with it the connection name name. Returns a QDBusConnection object associated with that connection.

### QDBusConnection QDBusConnection.connectToBus (QString address, QString name)

Opens a connection to a private bus on address address and associate with it the connection name name. Returns a QDBusConnection object associated with that connection.

### QDBusConnection QDBusConnection.connectToPeer (QString address, QString name)

Opens a peer-to-peer connection on address address and associate with it the connection name name. Returns a QDBusConnection object associated with that connection.

This function was introduced in Qt 4.8.

### bool QDBusConnection.disconnect (self, QString service, QString path, QString interface, QString name, QObject receiver, SLOT() slot)

Disconnects the signal specified by the service, path, interface and name parameters from the slot slot in object receiver. The arguments must be the same as passed to the connect() function.

Returns true if the disconnection was successful.

### object QDBusConnection.disconnect (self, QString service, QString path, QString interface, QString name, callable slot)

This is an overloaded function.

Disconnects the signal specified by the service, path, interface, name, and signature parameters from the slot slot in object receiver. The arguments must be the same as passed to the connect() function.

Returns true if the disconnection was successful.

### bool QDBusConnection.disconnect (self, QString service, QString path, QString interface, QString name, QString signature, QObject receiver, SLOT() slot)

This is an overloaded function.

Disconnects the signal specified by the service, path, interface, name, argumentMatch, and signature parameters from the slot slot in object receiver. The arguments must be the same as passed to the connect() function.

Returns true if the disconnection was successful.

This function was introduced in Qt 4.6.

### object QDBusConnection.disconnect (self, QString service, QString path, QString interface, QString name, QString signature, callable slot)

### bool QDBusConnection.disconnect (self, QString service, QString path, QString interface, QString name, QStringList argumentMatch, QString signature, QObject receiver, SLOT() slot)

### object QDBusConnection.disconnect (self, QString service, QString path, QString interface, QString name, QStringList argumentMatch, QString signature, callable slot)

### QDBusConnection.disconnectFromBus (QString name)

Closes the bus connection of name name.

Note that 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.

### QDBusConnection.disconnectFromPeer (QString name)

Closes the peer connection of name name.

Note that 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.

This function was introduced in Qt 4.8.

### QDBusConnectionInterface QDBusConnection.interface (self)

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

### bool QDBusConnection.isConnected (self)

Returns true if this QDBusConnection object is connected.

### QDBusError QDBusConnection.lastError (self)

Returns the last error that happened in this connection.

This function is provided for low-level code. If you're using QDBusInterface.call(), error codes are reported by its return value.

See also QDBusInterface and QDBusMessage.

### QByteArray QDBusConnection.localMachineId ()

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.

This function was introduced in Qt 4.8.

### QString QDBusConnection.name (self)

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.

This function was introduced in Qt 4.5.

See also connectToBus() and disconnectFromBus().

### QObject QDBusConnection.objectRegisteredAt (self, QString path)

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

### bool QDBusConnection.registerObject (self, QString path, QObject object, RegisterOptions options = QDBusConnection.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 object will be exposed through D-Bus.

This function does not replace existing objects: if there is already an object registered at path path, this function will return false. Use unregisterObject() to unregister it first.

You cannot register an object as a child object of an object that was registered with QDBusConnection.ExportChildObjects.

### bool QDBusConnection.registerService (self, 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() and QDBusConnectionInterface.registerService().

### bool QDBusConnection.send (self, QDBusMessage message)

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.sender ()

Returns the connection that sent the signal, if called in a slot activated by QDBus; otherwise it returns 0.

Note: Please avoid this function. This function is not thread-safe, so if there's any other thread delivering a D-Bus call, this function may return the wrong connection. In new code, please use QDBusContext.connection() (see that class for a description on how to use it).

Warning: This function is not reentrant.

### QDBusConnection QDBusConnection.sessionBus ()

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.

### QDBusConnection QDBusConnection.systemBus ()

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.

### QDBusConnection.unregisterObject (self, QString path, UnregisterMode mode = QDBusConnection.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.

Note that you cannot unregister objects that were not registered with registerObject().

### bool QDBusConnection.unregisterService (self, QString serviceName)

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

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