QtBase
v6.3.1
|
The QDBusConnection class represents a connection to the D-Bus bus daemon. More...
#include <qdbusconnection.h>
Static Public Member Functions | |
static QDBusConnection | connectToBus (BusType type, const QString &name) |
static QDBusConnection | connectToBus (const QString &address, const QString &name) |
static QDBusConnection | connectToPeer (const QString &address, const QString &name) |
static void | disconnectFromBus (const QString &name) |
static void | disconnectFromPeer (const QString &name) |
static QByteArray | localMachineId () |
static QDBusConnection | sessionBus () |
static QDBusConnection | systemBus () |
Protected Member Functions | |
QDBusConnection (QDBusConnectionPrivate *dd) | |
Friends | |
class | QDBusConnectionPrivate |
The QDBusConnection class represents a connection to the D-Bus bus daemon.
\inmodule QtDBus
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 77 of file qdbusconnection.h.
Specifies the type of the bus connection. The valid bus types are:
\value SessionBus the session bus, associated with the running desktop session \value SystemBus the system bus, used to communicate with system-wide processes \value 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 83 of file qdbusconnection.h.
This enum describes the available capabilities for a D-Bus connection.
\value UnixFileDescriptorPassing enables passing of Unix file descriptors to other processes (see QDBusUnixFileDescriptor)
Enumerator | |
---|---|
UnixFileDescriptorPassing |
Definition at line 129 of file qdbusconnection.h.
Specifies the options for registering objects with the connection. The possible values are:
\value ExportAdaptors export the contents of adaptors found in this object
\value ExportScriptableSlots export this object's scriptable slots \value ExportScriptableSignals export this object's scriptable signals \value ExportScriptableProperties export this object's scriptable properties \value ExportScriptableInvokables export this object's scriptable invokables \value ExportScriptableContents shorthand form for ExportScriptableSlots | ExportScriptableSignals | ExportScriptableProperties
\value ExportNonScriptableSlots export this object's non-scriptable slots \value ExportNonScriptableSignals export this object's non-scriptable signals \value ExportNonScriptableProperties export this object's non-scriptable properties \value ExportNonScriptableInvokables export this object's non-scriptable invokables \value ExportNonScriptableContents shorthand form for ExportNonScriptableSlots | ExportNonScriptableSignals | ExportNonScriptableProperties
\value ExportAllSlots export all of this object's slots \value ExportAllSignals export all of this object's signals \value ExportAllProperties export all of this object's properties \value ExportAllInvokables export all of this object's invokables \value ExportAllContents export all of this object's contents \value ExportChildObjects export this object's child objects
Definition at line 85 of file qdbusconnection.h.
The mode for unregistering an object path:
\value UnregisterNode unregister this node only: do not unregister child objects \value 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 116 of file qdbusconnection.h.
Enumerator | |
---|---|
SingleNode | |
SubPath |
Definition at line 122 of file qdbusconnection.h.
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 407 of file qdbusconnection.cpp.
QDBusConnection::QDBusConnection | ( | const QDBusConnection & | other | ) |
Creates a copy of the other connection.
Definition at line 422 of file qdbusconnection.cpp.
|
inlinenoexcept |
QDBusConnection::~QDBusConnection | ( | ) |
Disposes of this object. This does not close the connection: you have to call disconnectFromBus() to do that.
Definition at line 444 of file qdbusconnection.cpp.
|
explicitprotected |
Definition at line 433 of file qdbusconnection.cpp.
QDBusPendingCall QDBusConnection::asyncCall | ( | const QDBusMessage & | message, |
int | timeout = -1 |
||
) | const |
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 685 of file qdbusconnection.cpp.
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 1087 of file qdbusconnection.cpp.
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.
Definition at line 648 of file qdbusconnection.cpp.
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 588 of file qdbusconnection.cpp.
bool QDBusConnection::callWithCallback | ( | const QDBusMessage & | message, |
QObject * | receiver, | ||
const char * | returnMethod, | ||
int | timeout = -1 |
||
) | const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
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 619 of file qdbusconnection.cpp.
bool QDBusConnection::connect | ( | const QString & | service, |
const QString & | path, | ||
const QString & | interface, | ||
const QString & | name, | ||
const QString & | signature, | ||
QObject * | receiver, | ||
const char * | slot | ||
) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
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.
Definition at line 729 of file qdbusconnection.cpp.
bool QDBusConnection::connect | ( | const QString & | service, |
const QString & | path, | ||
const QString & | interface, | ||
const QString & | name, | ||
const QStringList & | argumentMatch, | ||
const QString & | signature, | ||
QObject * | receiver, | ||
const char * | slot | ||
) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
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.
Definition at line 759 of file qdbusconnection.cpp.
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.
Definition at line 706 of file qdbusconnection.cpp.
QDBusConnection::ConnectionCapabilities QDBusConnection::connectionCapabilities | ( | ) | const |
Returns the capabilities of this connection as negotiated with the bus server or peer. If this QDBusConnection is not connected, this function returns no capabilities.
Definition at line 1121 of file qdbusconnection.cpp.
|
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 472 of file qdbusconnection.cpp.
|
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 485 of file qdbusconnection.cpp.
|
static |
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.
Definition at line 500 of file qdbusconnection.cpp.
bool QDBusConnection::disconnect | ( | const QString & | service, |
const QString & | path, | ||
const QString & | interface, | ||
const QString & | name, | ||
const QString & | signature, | ||
QObject * | receiver, | ||
const char * | slot | ||
) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
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.
Definition at line 813 of file qdbusconnection.cpp.
bool QDBusConnection::disconnect | ( | const QString & | service, |
const QString & | path, | ||
const QString & | interface, | ||
const QString & | name, | ||
const QStringList & | argumentMatch, | ||
const QString & | signature, | ||
QObject * | receiver, | ||
const char * | slot | ||
) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
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.
Definition at line 831 of file qdbusconnection.cpp.
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 797 of file qdbusconnection.cpp.
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 518 of file qdbusconnection.cpp.
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.
Definition at line 539 of file qdbusconnection.cpp.
QDBusConnectionInterface * QDBusConnection::interface | ( | ) | const |
Returns a QDBusConnectionInterface object that represents the D-Bus server interface on this connection.
Definition at line 1033 of file qdbusconnection.cpp.
void * QDBusConnection::internalPointer | ( | ) | const |
Definition at line 1050 of file qdbusconnection.cpp.
bool QDBusConnection::isConnected | ( | ) | const |
Returns true
if this QDBusConnection object is connected.
Definition at line 1058 of file qdbusconnection.cpp.
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.
Definition at line 1072 of file qdbusconnection.cpp.
|
static |
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 1215 of file qdbusconnection.cpp.
QString QDBusConnection::name | ( | ) | const |
Returns the connection name for this connection, as given as the name parameter to connectToBus().
The connection name can be used to uniquely identify actual underlying connections to buses. Copies made from a single connection will always implicitly share the underlying connection, and hence will have the same connection name.
Inversely, two connections having different connection names will always either be connected to different buses, or have a different unique name (as returned by baseService()) on that bus.
Definition at line 1109 of file qdbusconnection.cpp.
Return the object that was registered with the registerObject() at the object path given by path.
Definition at line 994 of file qdbusconnection.cpp.
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.
Definition at line 457 of file qdbusconnection.cpp.
|
inlinenoexcept |
bool QDBusConnection::registerObject | ( | const QString & | path, |
const QString & | interface, | ||
QObject * | object, | ||
RegisterOptions | options = ExportAdaptors |
||
) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Registers the object object at path path with interface name interface 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.
The ExportChildObjects flag exports child objects on D-Bus based on the path of the registered objects and the QObject::objectName of the child. Therefore, it is important for the child object to have an object name.
You cannot register an object as a child object of an object that was registered with ExportChildObjects.
Definition at line 885 of file qdbusconnection.cpp.
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.
The ExportChildObjects flag exports child objects on D-Bus based on the path of the registered objects and the QObject::objectName of the child. Therefore, it is important for the child object to have an object name.
You cannot register an object as a child object of an object that was registered with ExportChildObjects.
Definition at line 861 of file qdbusconnection.cpp.
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.
Definition at line 1133 of file qdbusconnection.cpp.
bool QDBusConnection::registerVirtualObject | ( | const QString & | path, |
QDBusVirtualObject * | object, | ||
VirtualObjectRegisterOption | options = SingleNode |
||
) |
Definition at line 968 of file qdbusconnection.cpp.
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 557 of file qdbusconnection.cpp.
|
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 1165 of file qdbusconnection.cpp.
|
inlinenoexcept |
Swaps this QDBusConnection instance with other.
Definition at line 141 of file qdbusconnection.h.
|
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 1179 of file qdbusconnection.cpp.
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 981 of file qdbusconnection.cpp.
Unregisters the service serviceName that was previously registered with registerService() and returns true
if it succeeded.
Definition at line 1149 of file qdbusconnection.cpp.
|
friend |
Definition at line 209 of file qdbusconnection.h.