QDBusConnection Class Reference

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

#include <qdbusconnection.h>

Inheritance diagram for QDBusConnection:

Public Types
enum	BusType { SessionBus, SystemBus, ActivationBus }
	Specifies the type of the bus connection. More...
enum	ConnectionCapability { UnixFileDescriptorPassing = 0x0001 }
	This enum describes the available capabilities for a D-Bus connection. More...
enum	RegisterOption {   ExportAdaptors = 0x01, ExportScriptableSlots = 0x10, ExportScriptableSignals = 0x20, ExportScriptableProperties = 0x40,   ExportScriptableInvokables = 0x80, ExportScriptableContents = 0xf0, ExportNonScriptableSlots = 0x100, ExportNonScriptableSignals = 0x200,   ExportNonScriptableProperties = 0x400, ExportNonScriptableInvokables = 0x800, ExportNonScriptableContents = 0xf00, ExportAllSlots = ExportScriptableSlots|ExportNonScriptableSlots,   ExportAllSignals = ExportScriptableSignals|ExportNonScriptableSignals, ExportAllProperties = ExportScriptableProperties|ExportNonScriptableProperties, ExportAllInvokables = ExportScriptableInvokables|ExportNonScriptableInvokables, ExportAllContents = ExportScriptableContents|ExportNonScriptableContents,   ExportChildObjects = 0x1000 }
	Specifies the options for registering objects with the connection. More...
enum	UnregisterMode { UnregisterNode, UnregisterTree }
	The mode for unregistering an object path: More...
enum	VirtualObjectRegisterOption { SingleNode = 0x0, SubPath = 0x1 }
	Specifies the options for registering virtual objects with the connection. More...

Public Functions
QDBusPendingCall	asyncCall (const QDBusMessage &message, int timeout=-1) const
	Sends the message over this connection and returns immediately. More...
QString	baseService () const
	Returns the unique connection name for this connection, if this QDBusConnection object is connected, or an empty QString otherwise. More...
QDBusMessage	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. More...
bool	callWithCallback (const QDBusMessage &message, QObject *receiver, const char *returnMethod, const char *errorMethod, int timeout=-1) const
	Sends the message over this connection and returns immediately. More...
bool	callWithCallback (const QDBusMessage &message, QObject *receiver, const char *slot, int timeout=-1) const
	Sends the message over this connection and returns immediately. More...
bool	connect (const QString &service, const QString &path, const QString &interface, const QString &name, QObject *receiver, const char *slot)
	Connects the signal specified by the service, path, interface and name parameters to the slot slot in object receiver. More...
bool	connect (const QString &service, const QString &path, const QString &interface, const QString &name, const QString &signature, QObject *receiver, const char *slot)
	Connects the signal to the slot slot in object receiver. More...
bool	connect (const QString &service, const QString &path, const QString &interface, const QString &name, const QStringList &argumentMatch, const QString &signature, QObject *receiver, const char *slot)
	Connects the signal to the slot slot in object receiver. More...
ConnectionCapabilities	connectionCapabilities () const
	Returns the capabilities of this connection as negotiated with the bus server or peer. More...
bool	disconnect (const QString &service, const QString &path, const QString &interface, const QString &name, QObject *receiver, const char *slot)
	Disconnects the signal specified by the service, path, interface and name parameters from the slot slot in object receiver. More...
bool	disconnect (const QString &service, const QString &path, const QString &interface, const QString &name, const QString &signature, QObject *receiver, const char *slot)
	Disconnects the signal specified by the service, path, interface, name, and signature parameters from the slot slot in object receiver. More...
bool	disconnect (const QString &service, const QString &path, const QString &interface, const QString &name, const QStringList &argumentMatch, const QString &signature, QObject *receiver, const char *slot)
	Disconnects the signal specified by the service, path, interface, name, argumentMatch, and signature parameters from the slot slot in object receiver. More...
QDBusConnectionInterface *	interface () const
	Returns a QDBusConnectionInterface object that represents the D-Bus server interface on this connection. More...
void *	internalPointer () const
bool	isConnected () const
	Returns true if this QDBusConnection object is connected. More...
QDBusError	lastError () const
	Returns the last error that happened in this connection. More...
QString	name () const
	Returns the connection name for this connection, as given as the name parameter to connectToBus(). More...
QObject *	objectRegisteredAt (const QString &path) const
	Return the object that was registered with the registerObject() at the object path given by path. More...
QDBusConnection &	operator= (const QDBusConnection &other)
	Creates a copy of the connection other in this object. More...
	QDBusConnection (const QString &name)
	Creates a QDBusConnection object attached to the connection with name name. More...
	QDBusConnection (const QDBusConnection &other)
	Creates a copy of the other connection. More...
bool	registerObject (const QString &path, QObject *object, RegisterOptions options=ExportAdaptors)
	Registers the object object at path path and returns true if the registration was successful. More...
bool	registerService (const QString &serviceName)
	Attempts to register the serviceName on the D-Bus server and returns true if the registration succeeded. More...
bool	registerVirtualObject (const QString &path, QDBusVirtualObject *object, VirtualObjectRegisterOption options=SingleNode)
	Registers a QDBusTreeNode for a path. More...
bool	send (const QDBusMessage &message) const
	Sends the message over this connection, without waiting for a reply. More...
void	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. More...
bool	unregisterService (const QString &serviceName)
	Unregisters the service serviceName that was previously registered with registerService() and returns true if it succeeded. More...
	~QDBusConnection ()
	Disposes of this object. More...

Static Public Functions
static QDBusConnection	connectToBus (BusType type, const QString &name)
	Opens a connection of type type to one of the known busses and associate with it the connection name name. More...
static QDBusConnection	connectToBus (const QString &address, const QString &name)
	Opens a connection to a private bus on address address and associate with it the connection name name. More...
static QDBusConnection	connectToPeer (const QString &address, const QString &name)
	Opens a peer-to-peer connection on address address and associate with it the connection name name. More...
static void	disconnectFromBus (const QString &name)
	Closes the bus connection of name name. More...
static void	disconnectFromPeer (const QString &name)
	Closes the peer connection of name name. More...
static QByteArray	localMachineId ()
	Returns the local machine ID as known to the D-Bus system. More...
static QDBusConnection	sender ()
	Returns the connection that sent the signal, if called in a slot activated by QDBus; otherwise it returns 0. More...
static QDBusConnection	sessionBus ()
	Returns a QDBusConnection object opened with the session bus. More...
static QDBusConnection	systemBus ()
	Returns a QDBusConnection object opened with the system bus. More...

Protected Functions
	QDBusConnection (QDBusConnectionPrivate *dd)
	Creates a connection object with the given dd as private object. More...

Properties
QDBusConnectionPrivate *	d

Friends
class	QDBusConnectionPrivate

Detailed Description

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

Attention

Module: QtDBus

Since

4.2

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.

Definition at line 76 of file qdbusconnection.h.

Enumerations

BusType

enum QDBusConnection::BusType

Specifies the type of the bus connection.

The valid bus types are:

• SessionBus the session bus, associated with the running desktop session
• SystemBus the system bus, used to communicate with system-wide processes
• ActivationBus 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.

Enumerator
SessionBus
SystemBus
ActivationBus

Definition at line 82 of file qdbusconnection.h.

{ SessionBus, SystemBus, ActivationBus };

ConnectionCapability

enum QDBusConnection::ConnectionCapability

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

Since

4.8

• UnixFileDescriptorPassing enables passing of Unix file descriptors to other processes (see QDBusUnixFileDescriptor)

See also

connectionCapabilities()

Enumerator
UnixFileDescriptorPassing

Definition at line 126 of file qdbusconnection.h.

                              {
        UnixFileDescriptorPassing = 0x0001
    };

RegisterOption

enum QDBusConnection::RegisterOption

Specifies the options for registering objects with the connection.

The possible values are:

• ExportAdaptors export the contents of adaptors found in this object

• ExportScriptableSlots export this object's scriptable slots
• ExportScriptableSignals export this object's scriptable signals
• ExportScriptableProperties export this object's scriptable properties
• ExportScriptableInvokables export this object's scriptable invokables
• ExportScriptableContents shorthand form for ExportScriptableSlots | ExportScriptableSignals | ExportScriptableProperties

• ExportNonScriptableSlots export this object's non-scriptable slots
• ExportNonScriptableSignals export this object's non-scriptable signals
• ExportNonScriptableProperties export this object's non-scriptable properties
• ExportNonScriptableInvokables export this object's non-scriptable invokables
• ExportNonScriptableContents shorthand form for ExportNonScriptableSlots | ExportNonScriptableSignals | ExportNonScriptableProperties

• ExportAllSlots export all of this object's slots
• ExportAllSignals export all of this object's signals
• ExportAllProperties export all of this object's properties
• ExportAllInvokables export all of this object's invokables
• ExportAllContents export all of this object's contents
• ExportChildObjects export this object's child objects

See also

registerObject(), QDBusAbstractAdaptor, {usingadaptors.html}{Using adaptors}

Enumerator
ExportAdaptors
ExportScriptableSlots
ExportScriptableSignals
ExportScriptableProperties
ExportScriptableInvokables
ExportScriptableContents
ExportNonScriptableSlots
ExportNonScriptableSignals
ExportNonScriptableProperties
ExportNonScriptableInvokables
ExportNonScriptableContents
ExportAllSlots
ExportAllSignals
ExportAllProperties
ExportAllInvokables
ExportAllContents
ExportChildObjects

Definition at line 83 of file qdbusconnection.h.

                        {
        ExportAdaptors = 0x01,

        ExportScriptableSlots = 0x10,
        ExportScriptableSignals = 0x20,
        ExportScriptableProperties = 0x40,
        ExportScriptableInvokables = 0x80,
        ExportScriptableContents = 0xf0,

        ExportNonScriptableSlots = 0x100,
        ExportNonScriptableSignals = 0x200,
        ExportNonScriptableProperties = 0x400,
        ExportNonScriptableInvokables = 0x800,
        ExportNonScriptableContents = 0xf00,

        ExportAllSlots = ExportScriptableSlots|ExportNonScriptableSlots,
        ExportAllSignals = ExportScriptableSignals|ExportNonScriptableSignals,
        ExportAllProperties = ExportScriptableProperties|ExportNonScriptableProperties,
        ExportAllInvokables = ExportScriptableInvokables|ExportNonScriptableInvokables,
        ExportAllContents = ExportScriptableContents|ExportNonScriptableContents,

#ifndef Q_QDOC
        // Qt 4.2 had a misspelling here
        ExportAllSignal = ExportAllSignals,
#endif
        ExportChildObjects = 0x1000
        // Reserved = 0xff000000
    };

UnregisterMode

enum QDBusConnection::UnregisterMode

The mode for unregistering an object path:

• UnregisterNode unregister this node only: do not unregister child objects
• UnregisterTree 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.

Enumerator
UnregisterNode
UnregisterTree

Definition at line 111 of file qdbusconnection.h.

                        {
        UnregisterNode,
        UnregisterTree
    };

VirtualObjectRegisterOption

enum QDBusConnection::VirtualObjectRegisterOption

Specifies the options for registering virtual objects with the connection.

Warning

This function is not part of the public interface.

Since

4.8

The possible values are:

• SingleNode register a virtual object to handle one path only
• SubPath register a virtual object so that it handles all sub paths

See also

registerVirtualObject(), QDBusVirtualObject

Enumerator
SingleNode
SubPath

Definition at line 117 of file qdbusconnection.h.

                                     {
        SingleNode = 0x0,
        SubPath = 0x1
        // Reserved = 0xff000000
    };

Constructors and Destructors

QDBusConnection() [1/3]

QDBusConnection::QDBusConnection

(

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

Definition at line 289 of file qdbusconnection.cpp.

{
    if (name.isEmpty()) {
        d = 0;
    } else {
        QMutexLocker locker(&_q_manager()->mutex);
        d = _q_manager()->connection(name);
        if (d)
            d->ref.ref();
    }
}

QDBusConnection() [2/3]

QDBusConnection::QDBusConnection

(

const QDBusConnection &

other

)

Creates a copy of the other connection.

Definition at line 304 of file qdbusconnection.cpp.

{
    d = other.d;
    if (d)
        d->ref.ref();
}

~QDBusConnection()

QDBusConnection::~QDBusConnection

(

)

Disposes of this object.

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

Definition at line 329 of file qdbusconnection.cpp.

{
    if (d && !d->ref.deref())
        d->deleteYourself();
}

QDBusConnection() [3/3]

QDBusConnection::QDBusConnection ( QDBusConnectionPrivate *  dd )

explicitprotected

Creates a connection object with the given dd as private object.

Warning

This function is not part of the public interface.

Definition at line 318 of file qdbusconnection.cpp.

{
    d = dd;
    if (d)
        d->ref.ref();
}

Functions

asyncCall()

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

Sends the message over this connection and returns immediately.

Since

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

Definition at line 662 of file qdbusconnection.cpp.

{
    if (!d || !d->connection) {
        return QDBusPendingCall(0); // null pointer -> disconnected
    }

    QDBusPendingCallPrivate *priv = d->sendWithReplyAsync(message, 0, 0, 0, timeout);
    return QDBusPendingCall(priv);
}

baseService()

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

Definition at line 1083 of file qdbusconnection.cpp.

{
    return d ? d->baseService : QString();
}

call()

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

Definition at line 622 of file qdbusconnection.cpp.

Referenced by do_dbus_call(), and QDBusAbstractInterfacePrivate::property().

{
    if (!d || !d->connection) {
        QDBusError err = QDBusError(QDBusError::Disconnected,
                                    QLatin1String("Not connected to D-Bus server"));
        if (d)
            d->lastError = err;

        return QDBusMessage::createError(err);
    }

    if (mode != QDBus::NoBlock)
        return d->sendWithReply(message, mode, timeout);

    d->send(message);
    QDBusMessage retval;
    retval << QVariant(); // add one argument (to avoid .at(0) problems)
    return retval;
}

callWithCallback() [1/2]

bool QDBusConnection::callWithCallback	(	const QDBusMessage &	message,
		QObject *	receiver,
		const char *	returnMethod,
		const char *	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 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.

Definition at line 559 of file qdbusconnection.cpp.

{
    if (!d || !d->connection) {
        QDBusError err = QDBusError(QDBusError::Disconnected,
                                    QLatin1String("Not connected to D-BUS server"));
        if (d)
            d->lastError = err;
        return false;
    }
    return d->sendWithReplyAsync(message, receiver, returnMethod, errorMethod, timeout) != 0;
}

callWithCallback() [2/2]

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

Sends the message over this connection and returns immediately.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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.

Definition at line 593 of file qdbusconnection.cpp.

{
    return callWithCallback(message, receiver, returnMethod, 0, timeout);
}

connect() [1/3]

bool QDBusConnection::connect	(	const QString &	service,
		const QString &	path,
		const QString &	interface,
		const QString &	name,
		QObject *	receiver,
		const char *	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.

Definition at line 683 of file qdbusconnection.cpp.

Referenced by QOfonoManagerInterface::connectNotify(), QConnmanManagerInterface::connectNotify(), QOfonoModemInterface::connectNotify(), QConnmanProfileInterface::connectNotify(), QOfonoNetworkRegistrationInterface::connectNotify(), QOfonoNetworkOperatorInterface::connectNotify(), QConnmanServiceInterface::connectNotify(), QOfonoSimInterface::connectNotify(), QConnmanTechnologyInterface::connectNotify(), QOfonoDataConnectionManagerInterface::connectNotify(), QOfonoPrimaryDataContextInterface::connectNotify(), QOfonoSmsInterface::connectNotify(), QNetworkSessionPrivateImpl::QNetworkSessionPrivateImpl(), QIcdEngine::requestUpdate(), QNetworkManagerInterface::setConnections(), QNetworkManagerInterfaceAccessPoint::setConnections(), QNetworkManagerInterfaceDevice::setConnections(), QNetworkManagerInterfaceDeviceWired::setConnections(), QNetworkManagerInterfaceDeviceWireless::setConnections(), QNetworkManagerSettings::setConnections(), QNetworkManagerSettingsConnection::setConnections(), QNetworkManagerConnectionActive::setConnections(), and QIcdEngine::startListeningStateSignalsForAllConnections().

{
    return connect(service, path, interface, name, QStringList(), QString(), receiver, slot);
}

connect() [2/3]

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

Connects the signal to the slot slot in object receiver.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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.

Definition at line 709 of file qdbusconnection.cpp.

{
    return connect(service, path, interface, name, QStringList(), signature, receiver, slot);
}

connect() [3/3]

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
	)

Connects the signal to the slot slot in object receiver.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Since

4.6

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.

Definition at line 742 of file qdbusconnection.cpp.

{

    if (!receiver || !slot || !d || !d->connection)
        return false;
    if (interface.isEmpty() && name.isEmpty())
        return false;
    if (!interface.isEmpty() && !QDBusUtil::isValidInterfaceName(interface)) {
#ifndef QT_NO_DEBUG
        qWarning("QDBusConnection::connect: interface name '%s' is not valid", interface.toLatin1().constData());
#endif
        return false;
    }
    if (!service.isEmpty() && !QDBusUtil::isValidBusName(service)) {
#ifndef QT_NO_DEBUG
        qWarning("QDBusConnection::connect: service name '%s' is not valid", service.toLatin1().constData());
#endif
        return false;
    }
    if (!path.isEmpty() && !QDBusUtil::isValidObjectPath(path)) {
#ifndef QT_NO_DEBUG
        qWarning("QDBusConnection::connect: object path '%s' is not valid", path.toLatin1().constData());
#endif
        return false;
    }

    QDBusWriteLocker locker(ConnectAction, d);
    return d->connectSignal(service, path, interface, name, argumentMatch, signature, receiver, slot);
}

connectionCapabilities()

QDBusConnection::ConnectionCapabilities QDBusConnection::connectionCapabilities

(

)

const

Returns the capabilities of this connection as negotiated with the bus server or peer.

Since

4.8

If this QDBusConnection is not connected, this function returns no capabilities.

Definition at line 1123 of file qdbusconnection.cpp.

{
    return d ? d->capabilities : ConnectionCapabilities(0);
}

connectToBus() [1/2]

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

static

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.

Definition at line 357 of file qdbusconnection.cpp.

Referenced by QDBusConnectionConstructor::connectToBus(), and QNetworkSessionPrivateImpl::QNetworkSessionPrivateImpl().

{
//    Q_ASSERT_X(QCoreApplication::instance(), "QDBusConnection::addConnection",
//               "Cannot create connection without a Q[Core]Application instance");
    if (!qdbus_loadLibDBus()) {
        QDBusConnectionPrivate *d = 0;
        return QDBusConnection(d);
    }

    QMutexLocker locker(&_q_manager()->mutex);

    QDBusConnectionPrivate *d = _q_manager()->connection(name);
    if (d || name.isEmpty())
        return QDBusConnection(d);

    d = new QDBusConnectionPrivate;
    DBusConnection *c = 0;
    QDBusErrorInternal error;
    switch (type) {
        case SystemBus:
            c = q_dbus_bus_get_private(DBUS_BUS_SYSTEM, error);
            break;
        case SessionBus:
            c = q_dbus_bus_get_private(DBUS_BUS_SESSION, error);
            break;
        case ActivationBus:
            c = q_dbus_bus_get_private(DBUS_BUS_STARTER, error);
            break;
    }
    d->setConnection(c, error); //setConnection does the error handling for us

    _q_manager()->setConnection(name, d);

    QDBusConnection retval(d);

    // create the bus service
    // will lock in QDBusConnectionPrivate::connectRelay()
    d->setBusService(retval);

    return retval;
}

connectToBus() [2/2]

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

static

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.

Definition at line 403 of file qdbusconnection.cpp.

{
//    Q_ASSERT_X(QCoreApplication::instance(), "QDBusConnection::addConnection",
//               "Cannot create connection without a Q[Core]Application instance");
    if (!qdbus_loadLibDBus()) {
        QDBusConnectionPrivate *d = 0;
        return QDBusConnection(d);
    }

    QMutexLocker locker(&_q_manager()->mutex);

    QDBusConnectionPrivate *d = _q_manager()->connection(name);
    if (d || name.isEmpty())
        return QDBusConnection(d);

    d = new QDBusConnectionPrivate;
    // setConnection does the error handling for us
    QDBusErrorInternal error;
    DBusConnection *c = q_dbus_connection_open_private(address.toUtf8().constData(), error);
    if (c) {
        if (!q_dbus_bus_register(c, error)) {
            q_dbus_connection_unref(c);
            c = 0;
        }
    }
    d->setConnection(c, error);
    _q_manager()->setConnection(name, d);

    QDBusConnection retval(d);

    // create the bus service
    // will lock in QDBusConnectionPrivate::connectRelay()
    d->setBusService(retval);

    return retval;
}

connectToPeer()

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

static

Opens a peer-to-peer connection on address address and associate with it the connection name name.

Since

4.8

Returns a QDBusConnection object associated with that connection.

Definition at line 449 of file qdbusconnection.cpp.

{
//    Q_ASSERT_X(QCoreApplication::instance(), "QDBusConnection::addConnection",
//               "Cannot create connection without a Q[Core]Application instance");
    if (!qdbus_loadLibDBus()) {
        QDBusConnectionPrivate *d = 0;
        return QDBusConnection(d);
    }

    QMutexLocker locker(&_q_manager()->mutex);

    QDBusConnectionPrivate *d = _q_manager()->connection(name);
    if (d || name.isEmpty())
        return QDBusConnection(d);

    d = new QDBusConnectionPrivate;
    // setPeer does the error handling for us
    QDBusErrorInternal error;
    DBusConnection *c = q_dbus_connection_open_private(address.toUtf8().constData(), error);

    d->setPeer(c, error);
    _q_manager()->setConnection(name, d);

    QDBusConnection retval(d);

    return retval;
}

disconnect() [1/3]

bool QDBusConnection::disconnect	(	const QString &	service,
		const QString &	path,
		const QString &	interface,
		const QString &	name,
		QObject *	receiver,
		const char *	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.

Definition at line 781 of file qdbusconnection.cpp.

Referenced by QIcdEngine::cancelAsyncConfigurationUpdate().

{
    return disconnect(service, path, interface, name, QStringList(), QString(), receiver, slot);
}

disconnect() [2/3]

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

Disconnects the signal specified by the service, path, interface, name, and signature parameters from the slot slot in object receiver.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

The arguments must be the same as passed to the connect() function.

Returns true if the disconnection was successful.

Definition at line 800 of file qdbusconnection.cpp.

{
    return disconnect(service, path, interface, name, QStringList(), signature, receiver, slot);
}

disconnect() [3/3]

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
	)

Disconnects the signal specified by the service, path, interface, name, argumentMatch, and signature parameters from the slot slot in object receiver.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Since

4.6

The arguments must be the same as passed to the connect() function.

Returns true if the disconnection was successful.

Definition at line 821 of file qdbusconnection.cpp.

{
    if (!receiver || !slot || !d || !d->connection)
        return false;
    if (!interface.isEmpty() && !QDBusUtil::isValidInterfaceName(interface))
        return false;
    if (interface.isEmpty() && name.isEmpty())
        return false;

    QDBusWriteLocker locker(DisconnectAction, d);
    return d->disconnectSignal(service, path, interface, name, argumentMatch, signature, receiver, slot);
}

disconnectFromBus()

void QDBusConnection::disconnectFromBus ( const QString &  name )

static

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.

Definition at line 486 of file qdbusconnection.cpp.

Referenced by QDBusConnectionConstructor::disconnectFromBus(), and QNetworkSessionPrivateImpl::~QNetworkSessionPrivateImpl().

{
    if (_q_manager()) {
        QMutexLocker locker(&_q_manager()->mutex);
        QDBusConnectionPrivate *d = _q_manager()->connection(name);
        if (d && d->mode != QDBusConnectionPrivate::ClientMode)
            return;
        _q_manager()->removeConnection(name);
    }
}

disconnectFromPeer()

void QDBusConnection::disconnectFromPeer ( const QString &  name )

static

Closes the peer connection of name name.

Since

4.8

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.

Definition at line 510 of file qdbusconnection.cpp.

{
    if (_q_manager()) {
        QMutexLocker locker(&_q_manager()->mutex);
        QDBusConnectionPrivate *d = _q_manager()->connection(name);
        if (d && d->mode != QDBusConnectionPrivate::PeerMode)
            return;
        _q_manager()->removeConnection(name);
    }
}

interface()

QDBusConnectionInterface * QDBusConnection::interface

(

)

const

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

Definition at line 1029 of file qdbusconnection.cpp.

Referenced by QScriptDBusConnection::QScriptDBusConnection().

{
    if (!d)
        return 0;
    return d->busService;
}

internalPointer()

void * QDBusConnection::internalPointer

(

)

const

Warning

This function is not part of the public interface.

Since

4.8

Returns the internal, implementation-defined pointer for this connection. Currently, this returns a DBusConnection* pointer, without changing the reference count. It is the responsibility of the caller to call dbus_connection_ref if it wants to store the pointer.

Definition at line 1046 of file qdbusconnection.cpp.

{
    return d ? d->connection : 0;
}

isConnected()

bool QDBusConnection::isConnected

(

)

const

Returns true if this QDBusConnection object is connected.

Definition at line 1054 of file qdbusconnection.cpp.

Referenced by QDBusAbstractInterface::QDBusAbstractInterface(), QDBusAbstractInterfacePrivate::QDBusAbstractInterfacePrivate(), and QDBusInterfacePrivate::QDBusInterfacePrivate().

{
    return d && d->connection && q_dbus_connection_get_is_connected(d->connection);
}

lastError()

QDBusError QDBusConnection::lastError

(

)

const

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, QDBusMessage

Definition at line 1068 of file qdbusconnection.cpp.

Referenced by QNetworkManagerSettingsConnection::setConnections().

{
    return d ? d->lastError : QDBusError();
}

localMachineId()

QByteArray QDBusConnection::localMachineId ( )

static

Returns the local machine ID as known to the D-Bus system.

Since

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

Definition at line 1256 of file qdbusconnection.cpp.

{
    char *dbus_machine_id = q_dbus_get_local_machine_id();
    QByteArray result = dbus_machine_id;
    q_dbus_free(dbus_machine_id);
    return result;
}

name()

QString QDBusConnection::name

(

)

const

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

Since

4.5

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

Definition at line 1108 of file qdbusconnection.cpp.

Referenced by QDBusServiceWatcher::setConnection().

{
    return d ? d->name : QString();
}

objectRegisteredAt()

QObject * QDBusConnection::objectRegisteredAt

(

const QString &

path

)

const

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

Definition at line 990 of file qdbusconnection.cpp.

{
    Q_ASSERT_X(QDBusUtil::isValidObjectPath(path), "QDBusConnection::registeredObject",
               "Invalid object path given");
    if (!d || !d->connection || !QDBusUtil::isValidObjectPath(path))
        return 0;

    QStringList pathComponents = path.split(QLatin1Char('/'));
    if (pathComponents.last().isEmpty())
        pathComponents.removeLast();

    // lower-bound search for where this object should enter in the tree
    QDBusReadLocker lock(ObjectRegisteredAtAction, d);
    const QDBusConnectionPrivate::ObjectTreeNode *node = &d->rootNode;

    int i = 1;
    while (node) {
        if (pathComponents.count() == i)
            return node->obj;
        if ((node->flags & QDBusConnectionPrivate::VirtualObject) && (node->flags & QDBusConnection::SubPath))
            return node->obj;

        QDBusConnectionPrivate::ObjectTreeNode::DataList::ConstIterator it =
            qLowerBound(node->children.constBegin(), node->children.constEnd(), pathComponents.at(i));
        if (it == node->children.constEnd() || it->name != pathComponents.at(i))
            break;              // node not found

        node = it;
        ++i;
    }
    return 0;
}

operator=()

QDBusConnection & QDBusConnection::operator=

(

const QDBusConnection &

other

)

Creates a copy of the connection other in this object.

Note that the connection this object referenced before the copy, is not spontaneously disconnected.

See also

disconnectFromBus()

Definition at line 342 of file qdbusconnection.cpp.

{
    if (other.d)
        other.d->ref.ref();
    if (d && !d->ref.deref())
        d->deleteYourself();
    d = other.d;
    return *this;
}

registerObject()

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

Definition at line 848 of file qdbusconnection.cpp.

{
    Q_ASSERT_X(QDBusUtil::isValidObjectPath(path), "QDBusConnection::registerObject",
               "Invalid object path given");
    if (!d || !d->connection || !object || !options || !QDBusUtil::isValidObjectPath(path))
        return false;

    QStringList pathComponents = path.split(QLatin1Char('/'));
    if (pathComponents.last().isEmpty())
        pathComponents.removeLast();
    QDBusWriteLocker locker(RegisterObjectAction, d);

    // lower-bound search for where this object should enter in the tree
    QDBusConnectionPrivate::ObjectTreeNode *node = &d->rootNode;
    int i = 1;
    while (node) {
        if (pathComponents.count() == i) {
            // this node exists
            // consider it free if there's no object here and the user is not trying to
            // replace the object sub-tree
            if (node->obj)
                return false;

            if (options & QDBusConnectionPrivate::VirtualObject) {
                // technically the check for children needs to go even deeper
                if (options & SubPath) {
                    foreach (const QDBusConnectionPrivate::ObjectTreeNode &child, node->children) {
                        if (child.obj)
                            return false;
                    }
                }
            } else {
                if ((options & ExportChildObjects && !node->children.isEmpty()))
                    return false;
            }
            // we can add the object here
            node->obj = object;
            node->flags = options;

            d->registerObject(node);
            //qDebug("REGISTERED FOR %s", path.toLocal8Bit().constData());
            return true;
        }

        // if a virtual object occupies this path, return false
        if (node->obj && (node->flags & QDBusConnectionPrivate::VirtualObject) && (node->flags & QDBusConnection::SubPath)) {
            qDebug("Cannot register object at %s because QDBusVirtualObject handles all sub-paths.",
                   qPrintable(path));
            return false;
        }

        // find the position where we'd insert the node
        QDBusConnectionPrivate::ObjectTreeNode::DataList::Iterator it =
            qLowerBound(node->children.begin(), node->children.end(), pathComponents.at(i));
        if (it != node->children.end() && it->name == pathComponents.at(i)) {
            // match: this node exists
            node = it;

            // are we allowed to go deeper?
            if (node->flags & ExportChildObjects) {
                // we're not
                qDebug("Cannot register object at %s because %s exports its own child objects",
                       qPrintable(path), qPrintable(pathComponents.at(i)));
                return false;
            }
        } else {
            // add entry
            node = node->children.insert(it, pathComponents.at(i));
        }

        // iterate
        ++i;
    }

    Q_ASSERT_X(false, "QDBusConnection::registerObject", "The impossible happened");
    return false;
}

registerService()

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

Definition at line 1135 of file qdbusconnection.cpp.

{
    if (interface() && interface()->registerService(serviceName)) {
        if (d) d->registerService(serviceName);
        return true;
    }
    return false;
}

registerVirtualObject()

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

Registers a QDBusTreeNode for a path.

Warning

This function is not part of the public interface.

Since

4.8 It can handle a path including all child paths, thus handling multiple DBus nodes.

To unregister a QDBusTreeNode use the unregisterObject() function with its path.

Definition at line 937 of file qdbusconnection.cpp.

{
    int opts = options | QDBusConnectionPrivate::VirtualObject;
    return registerObject(path, (QObject*) treeNode, (RegisterOptions) opts);
}

send()

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.

Definition at line 528 of file qdbusconnection.cpp.

Referenced by QDBusContext::sendErrorReply().

{
    if (!d || !d->connection) {
        QDBusError err = QDBusError(QDBusError::Disconnected,
                                    QLatin1String("Not connected to D-BUS server"));
        if (d)
            d->lastError = err;
        return false;
    }
    return d->send(message) != 0;
}

sender()

QDBusConnection QDBusConnection::sender ( )

static

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

Note

This class or function is not reentrant.

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

Definition at line 1213 of file qdbusconnection.cpp.

{
    return QDBusConnection(_q_manager()->sender());
}

sessionBus()

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

Definition at line 1189 of file qdbusconnection.cpp.

Referenced by QDBusConnectionConstructor::QDBusConnectionConstructor(), and QScriptDBusInterfaceConstructor::qscript_call().

{
    return *_q_sessionBus();
}

systemBus()

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.

Definition at line 1194 of file qdbusconnection.cpp.

Referenced by QIcdEngine::ensureDBusConnection(), and QDBusConnectionConstructor::QDBusConnectionConstructor().

{
    return *_q_systemBus();
}

unregisterObject()

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.

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

Definition at line 950 of file qdbusconnection.cpp.

{
    if (!d || !d->connection || !QDBusUtil::isValidObjectPath(path))
        return;

    QStringList pathComponents = path.split(QLatin1Char('/'));
    QDBusWriteLocker locker(UnregisterObjectAction, d);
    QDBusConnectionPrivate::ObjectTreeNode *node = &d->rootNode;
    int i = 1;

    // find the object
    while (node) {
        if (pathComponents.count() == i || !path.compare(QLatin1String("/"))) {
            // found it
            node->obj = 0;
            node->flags = 0;

            if (mode == UnregisterTree) {
                // clear the sub-tree as well
                node->children.clear();  // can't disconnect the objects because we really don't know if they can
                                // be found somewhere else in the path too
            }

            return;
        }

        QDBusConnectionPrivate::ObjectTreeNode::DataList::Iterator it =
            qLowerBound(node->children.begin(), node->children.end(), pathComponents.at(i));
        if (it == node->children.end() || it->name != pathComponents.at(i))
            break;              // node not found

        node = it;
        ++i;
    }
}

unregisterService()

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

Definition at line 1151 of file qdbusconnection.cpp.

{
    if (interface()->unregisterService(serviceName)) {
        if (d) d->unregisterService(serviceName);
        return true;
    }
    return false;
}

Friends and Related Functions

QDBusConnectionPrivate

friend class QDBusConnectionPrivate

friend

Definition at line 203 of file qdbusconnection.h.

Properties

d

QDBusConnectionPrivate* QDBusConnection::d

private

Definition at line 204 of file qdbusconnection.h.

Referenced by QDBusConnectionPrivate::d(), operator=(), and QDBusConnection().

---

The documentation for this class was generated from the following files:

• /src/dbus/qdbusconnection.h
• /src/dbus/qdbusconnection.cpp