QDBusConnection 类

QDBusConnection 类表示到 D-Bus 总线守护程序的连接。 更多...

头: #include <QDBusConnection>
CMake: find_package(Qt6 REQUIRED COMPONENTS DBus)
target_link_libraries(mytarget PRIVATE Qt6::DBus)
qmake: QT += dbus

公共类型

enum BusType { SessionBus, SystemBus, ActivationBus }
flags ConnectionCapabilities
enum ConnectionCapability { UnixFileDescriptorPassing }
enum RegisterOption { ExportAdaptors, ExportScriptableSlots, ExportScriptableSignals, ExportScriptableProperties, ExportScriptableInvokables, …, ExportChildObjects }
flags RegisterOptions
enum UnregisterMode { UnregisterNode, UnregisterTree }
flags VirtualObjectRegisterOptions

公共函数

QDBusConnection (const QString & name )
QDBusConnection (const QDBusConnection & other )
~QDBusConnection ()
QDBusPendingCall asyncCall (const QDBusMessage & message , int timeout = -1) const
QString baseService () const
QDBusMessage call (const QDBusMessage & message , QDBus::CallMode mode = QDBus::Block, int timeout = -1) const
bool callWithCallback (const QDBusMessage & message , QObject * receiver , const char * returnMethod , const char * errorMethod , int timeout = -1) const
bool connect (const QString & service , const QString & path , const QString & interface , const QString & name , QObject * receiver , const char * slot )
bool connect (const QString & service , const QString & path , const QString & interface , const QString & name , const QString & signature , QObject * receiver , const char * slot )
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 )
QDBusConnection::ConnectionCapabilities connectionCapabilities () const
bool disconnect (const QString & service , const QString & path , const QString & interface , const QString & name , QObject * receiver , const char * slot )
bool disconnect (const QString & service , const QString & path , const QString & interface , const QString & name , const QString & signature , QObject * receiver , const char * slot )
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 )
QDBusConnectionInterface * interface () const
bool isConnected () const
QDBusError lastError () const
QString name () const
QObject * objectRegisteredAt (const QString & path ) const
bool registerObject (const QString & path , QObject * object , QDBusConnection::RegisterOptions options = ExportAdaptors)
bool registerObject (const QString & path , const QString & interface , QObject * object , QDBusConnection::RegisterOptions options = ExportAdaptors)
bool registerService (const QString & serviceName )
bool send (const QDBusMessage & message ) const
void swap (QDBusConnection & other )
void unregisterObject (const QString & path , QDBusConnection::UnregisterMode mode = UnregisterNode)
bool unregisterService (const QString & serviceName )
QDBusConnection & operator= (const QDBusConnection & other )

静态公共成员

QDBusConnection connectToBus (QDBusConnection::BusType type , const QString & name )
QDBusConnection connectToBus (const QString & address , const QString & name )
QDBusConnection connectToPeer (const QString & address , const QString & name )
void disconnectFromBus (const QString & name )
void disconnectFromPeer (const QString & name )
QByteArray localMachineId ()
QDBusConnection sessionBus ()
QDBusConnection systemBus ()

详细描述

此类是 D-Bus 会话的初始点。使用它,可以获得对远程对象、接口的访问;将远程信号连接到对象槽;注册对象、等。

D-Bus 连接的创建是使用 connectToBus () 函数,打开到服务器守护程序的连接和做初始握手,关联该连接与名称。进一步,试图使用相同的名称进行连接,将返回相同连接。

然后断开连接使用 disconnectFromBus () 函数。

一旦断开连接,调用 connectToBus () 就不会重新建立连接,必须创建新的 QDBusConnection 实例。

为了方便,对于 2 种最常见连接类型, sessionBus () 和 systemBus () 函数分别返回到会话服务器守护程序和系统服务器守护程序的打开连接。这些连接在首次使用时打开,和被关闭当 QCoreApplication 析构函数运行。

D-Bus 还支持点对点连接,无需总线服务器守护程序。使用此设施,2 应用程序可以相互交谈和交换消息。这可以达成通过将地址传递给 connectToBus () 函数,其被打开通过另一 D-Bus 应用程序使用 QDBusServer .

成员类型文档编制

enum QDBusConnection:: BusType

指定总线连接的类型。有效总线类型:

常量 描述
QDBusConnection::SessionBus 0 会话总线,关联在运行的桌面会话
QDBusConnection::SystemBus 1 系统总线,用于与系统范围进程通信
QDBusConnection::ActivationBus 2 激活总线,用于启动服务的总线别名

在会话总线,可以找到由同一用户共享的相同桌面会话 (因此得名) 的其它应用程序。不管怎样,在系统总线,通常可以找到整个系统的共享进程。

enum QDBusConnection:: ConnectionCapability
flags QDBusConnection:: ConnectionCapabilities

此枚举描述用于 D-Bus 连接的可用能力。

常量 描述
QDBusConnection::UnixFileDescriptorPassing 0x0001 使将 Unix 文件描述符能够传递给其它进程 (见 QDBusUnixFileDescriptor )

ConnectionCapabilities 类型是 typedef 对于 QFlags <ConnectionCapability>。它存储 ConnectionCapability 值的 OR 组合。

另请参阅 connectionCapabilities ().

enum QDBusConnection:: RegisterOption
flags QDBusConnection:: RegisterOptions

采用连接指定注册对象的选项。可能的值:

常量 描述
QDBusConnection::ExportAdaptors 0x01 导出在此对象中找到的适配器内容
QDBusConnection::ExportScriptableSlots 0x10 导出此对象的可编写脚本槽
QDBusConnection::ExportScriptableSignals 0x20 导出此对象的可编写脚本信号
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 导出此对象的所有信号
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 导出此对象的子级对象

RegisterOptions 类型是 typedef 对于 QFlags <RegisterOption>。它存储 RegisterOption 值的 OR 组合。

另请参阅 registerObject (), QDBusAbstractAdaptor ,和 使用适配器 .

enum QDBusConnection:: UnregisterMode

取消对象路径注册的方式:

常量 描述
QDBusConnection::UnregisterNode 0 仅取消此节点的注册:不取消子级对象的注册
QDBusConnection::UnregisterTree 1 取消注册此节点及其所有子树

注意,不管怎样,若此对象被注册采用 ExportChildObjects 选项,UnregisterNode 也会取消子级对象的注册。

成员函数文档编制

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

Creates a QDBusConnection object attached to the connection with name name .

这不会打开连接。必须调用 connectToBus () 以打开它。

QDBusConnection:: QDBusConnection (const QDBusConnection & other )

创建副本为 other 连接。

QDBusConnection:: ~QDBusConnection ()

处置此对象。这不会关闭连接:必须调用 disconnectFromBus () 以做到这点。

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

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

QDBusInterface::asyncCall () 函数了解放置调用的更友好方式。

QString QDBusConnection:: baseService () const

Returns the unique connection name for this connection, if this QDBusConnection object is connected, or an empty QString 否则。

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.

此函数返回空 QString for peer-to-peer connections.

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

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

QDBusInterface::call () 函数了解放置调用的更友好方式。

警告: 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 (const QDBusMessage & message , QObject * receiver , const char * returnMethod , const char * errorMethod , int timeout = -1) const

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

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

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

连接信号指定通过 service , path , interface and name 参数用于槽 slot 在对象 receiver 。自变量 service and path 可以为空,表示连接到任何信号为 ( interface , name ) 对,从任何远程应用程序。

返回 true 若连接成功。

警告: 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 (const QString & service , const QString & path , const QString & interface , const QString & name , const QString & signature , QObject * receiver , const char * slot )

这是重载函数。

将信号连接到槽 slot 在对象 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.

返回 true 若连接成功。

注意: 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 (const QString & service , const QString & path , const QString & interface , const QString & name , const QStringList & argumentMatch , const QString & signature , QObject * receiver , const char * slot )

这是重载函数。

将信号连接到槽 slot 在对象 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.

返回 true 若连接成功。

注意: 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.

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

打开连接为类型 type to one of the known buses and associate with it the connection name name 。返回 QDBusConnection 对象关联该连接。

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

打开到私有总线的连接按地址 address 并关联它采用连接名称 name 。返回 QDBusConnection 对象关联该连接。

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

Opens a peer-to-peer connection on address address 并关联它采用连接名称 name 。返回 QDBusConnection 对象关联该连接。

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.

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 在对象 receiver . The arguments must be the same as passed to the connect () 函数。

返回 true 若断开连接成功。

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 ,和 signature parameters from the slot slot 在对象 receiver . The arguments must be the same as passed to the connect () 函数。

返回 true 若断开连接成功。

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 ,和 signature parameters from the slot slot 在对象 receiver . The arguments must be the same as passed to the connect () 函数。

返回 true 若断开连接成功。

[static] void QDBusConnection:: disconnectFromBus (const QString & 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 构造函数。

[static] void QDBusConnection:: disconnectFromPeer (const QString & 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 构造函数。

QDBusConnectionInterface *QDBusConnection:: interface () const

返回 QDBusConnectionInterface object that represents the D-Bus server interface on this connection.

bool QDBusConnection:: isConnected () const

返回 true 若此 QDBusConnection 对象被连接。

QDBusError QDBusConnection:: lastError () const

返回在此连接发生的最后错误。

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

另请参阅 QDBusInterface and QDBusMessage .

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

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.

另请参阅 connectToBus () 和 disconnectFromBus ().

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

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

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

注册对象 object 在路径 path 并返回 true 若注册成功。 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 .

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

这是重载函数。

注册对象 object 在路径 path 采用接口名称 interface 并返回 true 若注册成功。 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 .

bool QDBusConnection:: registerService (const QString & serviceName )

试图注册 serviceName 在 D-Bus 服务器并返回 true if the registration succeeded. The registration will fail if the name is already registered by another application.

另请参阅 unregisterService () 和 QDBusConnectionInterface::registerService ().

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

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

返回 true 若消息队列成功,否则 false。

[static] QDBusConnection QDBusConnection:: sessionBus ()

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

void QDBusConnection:: swap ( QDBusConnection & other )

交换此 QDBusConnection 实例与 other .

[static] QDBusConnection QDBusConnection:: systemBus ()

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

void QDBusConnection:: unregisterObject (const QString & path , QDBusConnection::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 ().

bool QDBusConnection:: unregisterService (const QString & serviceName )

Unregisters the service serviceName that was previously registered with registerService () 并返回 true 若成功。

另请参阅 registerService () 和 QDBusConnectionInterface::unregisterService ().

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

创建副本为连接 other 在此对象。注意,此对象引用的连接在拷贝之前,不会自发断开连接。

另请参阅 disconnectFromBus ().