Contents

• Public Types
• Public Functions
• Static Public Members
• Related Non-Members
• Detailed Description

Detailed Description

TheQDBusConnection 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 theconnectToBus() 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 thedisconnectFromBus() function.

Once disconnected, callingconnectToBus() will not reestablish a connection, you must create a newQDBusConnection instance.

As a convenience for the two most common connection types, thesessionBus() andsystemBus() 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 theQCoreApplication 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 toconnectToBus() function, which was opened by another D-Bus application using QDBusServer.

Member Type Documentation

enum QDBusConnection::BusType

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

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.

enum QDBusConnection::ConnectionCapability
flags QDBusConnection::ConnectionCapabilities

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

This enum was introduced or modified in Qt 4.8.

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

See alsoconnectionCapabilities().

enum QDBusConnection::RegisterOption
flags QDBusConnection::RegisterOptions

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

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

See alsoregisterObject(),QDBusAbstractAdaptor, andUsing adaptors.

enum QDBusConnection::UnregisterMode

The mode for unregistering an object path:

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

Member Function Documentation

QDBusConnection::QDBusConnection(constQString & name)

Creates aQDBusConnection object attached to the connection with namename.

This does not open the connection. You have to callconnectToBus() to open it.

QDBusConnection::QDBusConnection(constQDBusConnection & other)

Creates a copy of theother connection.

QDBusConnection::~QDBusConnection()

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

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

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

If no reply is received withintimeout milliseconds, an automatic error will be delivered indicating the expiration of the call. The defaulttimeout 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 theQDBusInterface::asyncCall() function for a more friendly way of placing calls.

This function was introduced in Qt 4.5.

QString QDBusConnection::baseService() const

Returns the unique connection name for this connection, if thisQDBusConnection object is connected, or an emptyQString 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 emptyQString for peer-to-peer connections.

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

Sends themessage over this connection and blocks, waiting for a reply, for at mosttimeout milliseconds. This function is suitable for method calls only. It returns the reply message as its return value, which will be either of typeQDBusMessage::ReplyMessage orQDBusMessage::ErrorMessage.

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

See theQDBusInterface::call() function for a more friendly way of placing calls.

Warning: Ifmode isQDBus::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(constQDBusMessage & message,QObject * receiver, constchar * returnMethod, constchar * errorMethod,int timeout = -1) const

Sends themessage over this connection and returns immediately. When the reply is received, the methodreturnMethod is called in thereceiver object. If an error occurs, the methoderrorMethod will be called instead.

If no reply is received withintimeout milliseconds, an automatic error will be delivered indicating the expiration of the call. The defaulttimeout 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.

bool QDBusConnection::connect(constQString & service, constQString & path, constQString & interface, constQString & name,QObject * receiver, constchar * slot)

Connects the signal specified by theservice,path,interface andname parameters to the slotslot in objectreceiver. The argumentsservice andpath 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.

bool QDBusConnection::connect(constQString & service, constQString & path, constQString & interface, constQString & name, constQString & signature,QObject * receiver, constchar * slot)

This is an overloaded function.

Connects the signal to the slotslot in objectreceiver. Unlike the previousconnect() overload, this function allows one to specify the parameter signature to be connected using thesignature variable. The function will then verify that this signature can be delivered to the slot specified byslot 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(constQString & service, constQString & path, constQString & interface, constQString & name, constQStringList & argumentMatch, constQString & signature,QObject * receiver, constchar * slot)

This is an overloaded function.

Connects the signal to the slotslot in objectreceiver. Unlike the previousconnect() overload, this function allows one to specify the parameter signature to be connected using thesignature variable. The function will then verify that this signature can be delivered to the slot specified byslot and return false otherwise.

TheargumentMatch parameter lists the string parameters to be matched, in sequential order. Note that, to match an empty string, you need to pass aQString that is empty but not null (i.e.,QString("")). A nullQString 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.

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

Opens a connection of typetype to one of the known busses and associate with it the connection namename. Returns aQDBusConnection object associated with that connection.

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

Opens a connection to a private bus on addressaddress and associate with it the connection namename. Returns aQDBusConnection object associated with that connection.

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

Opens a peer-to-peer connection on addressaddress and associate with it the connection namename. Returns aQDBusConnection object associated with that connection.

This function was introduced in Qt 4.8.

ConnectionCapabilities QDBusConnection::connectionCapabilities() const

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

This function was introduced in Qt 4.8.

bool QDBusConnection::disconnect(constQString & service, constQString & path, constQString & interface, constQString & name,QObject * receiver, constchar * slot)

Disconnects the signal specified by theservice,path,interface andname parameters from the slotslot in objectreceiver. The arguments must be the same as passed to theconnect() function.

Returns true if the disconnection was successful.

bool QDBusConnection::disconnect(constQString & service, constQString & path, constQString & interface, constQString & name, constQString & signature,QObject * receiver, constchar * slot)

This is an overloaded function.

Disconnects the signal specified by theservice,path,interface,name, andsignature parameters from the slotslot in objectreceiver. The arguments must be the same as passed to theconnect() function.

Returns true if the disconnection was successful.

bool QDBusConnection::disconnect(constQString & service, constQString & path, constQString & interface, constQString & name, constQStringList & argumentMatch, constQString & signature,QObject * receiver, constchar * slot)

This is an overloaded function.

Disconnects the signal specified by theservice,path,interface,name,argumentMatch, andsignature parameters from the slotslot in objectreceiver. The arguments must be the same as passed to theconnect() function.

Returns true if the disconnection was successful.

This function was introduced in Qt 4.6.

[static]void QDBusConnection::disconnectFromBus(constQString & name)

Closes the bus connection of namename.

Note that if there are stillQDBusConnection 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 theQDBusConnection constructor.

[static]void QDBusConnection::disconnectFromPeer(constQString & name)

Closes the peer connection of namename.

Note that if there are stillQDBusConnection 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 theQDBusConnection constructor.

This function was introduced in Qt 4.8.

QDBusConnectionInterface * QDBusConnection::interface() const

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

bool QDBusConnection::isConnected() const

Returns true if thisQDBusConnection object is connected.

QDBusError QDBusConnection::lastError() const

Returns the last error that happened in this connection.

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

See alsoQDBusInterface andQDBusMessage.

[static]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() const

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

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 bybaseService()) on that bus.

This function was introduced in Qt 4.5.

See alsoconnectToBus() anddisconnectFromBus().

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

Return the object that was registered with theregisterObject() at the object path given bypath.

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

Registers the objectobject at pathpath and returns true if the registration was successful. Theoptions parameter specifies how much of the objectobject will be exposed through D-Bus.

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

You cannot register an object as a child object of an object that was registered withQDBusConnection::ExportChildObjects.

bool QDBusConnection::registerService(constQString & serviceName)

Attempts to register theserviceName 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 alsounregisterService() andQDBusConnectionInterface::registerService().

bool QDBusConnection::send(constQDBusMessage & message) const

Sends themessage 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.

[static]QDBusConnection QDBusConnection::sender()

Returns the connection that sent the signal, if called in a slot activated byQDBus; 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 useQDBusContext::connection() (see that class for a description on how to use it).

Warning: This function is notreentrant.

[static]QDBusConnection QDBusConnection::sessionBus()

Returns aQDBusConnection 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.

[static]QDBusConnection QDBusConnection::systemBus()

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

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

Unregisters an object that was registered with theregisterObject() at the object path given bypath and, ifmode isQDBusConnection::UnregisterTree, all of its sub-objects too.

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

bool QDBusConnection::unregisterService(constQString & serviceName)

Unregisters the serviceserviceName that was previously registered withregisterService() and returns true if it succeeded.

See alsoregisterService() andQDBusConnectionInterface::unregisterService().

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

Creates a copy of the connectionother in this object. Note that the connection this object referenced before the copy, is not spontaneously disconnected.

See alsodisconnectFromBus().

Related Non-Members

[static]QDBusConnection QDBusConnection::sessionBus()

Returns aQDBusConnection 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.

[static]QDBusConnection QDBusConnection::systemBus()

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