QDBusConnection Class

成员函数文档

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

创建一个与名为name 的连接关联的QDBusConnection对象。

这不会打开该连接。您必须调用connectToBus() 才能打开它。

QDBusConnection::QDBusConnection(const QDBusConnection &other)

创建other 连接的副本。

[noexcept] QDBusConnection::~QDBusConnection()

释放该对象。这不会关闭连接：若要关闭连接，必须调用disconnectFromBus()。

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

通过此连接发送message ，并立即返回。此函数仅适用于方法调用。它返回一个类型为QDBusPendingCall 的对象，可用于跟踪响应的状态。

如果在timeout 毫秒内未收到回复，将自动返回一个错误，表明调用已超时。 默认的timeout 为-1，该值将被替换为适合进程间通信的、由实现定义的值（通常为25秒）。此超时时间也是在QDBusPendingCall::waitForFinished()中等待的上限。

有关更便捷的调用方式，请参阅QDBusInterface::asyncCall()函数。

QString QDBusConnection::baseService() const

如果该QDBusConnection 对象已建立连接，则返回此连接的唯一连接名称；否则返回空的QString 。

唯一连接名称是一个格式为“:x.xxx”（其中 x 代表十进制数字）的字符串，由 D-Bus 服务器守护进程在建立连接时分配。它用于在总线中唯一标识此客户端。

对于点对点连接，此函数将返回一个空的QString 。

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

通过此连接发送message ，并阻塞等待响应，最多等待timeout 毫秒。此函数仅适用于方法调用。它将响应消息作为返回值，该值类型为QDBusMessage::ReplyMessage 或QDBusMessage::ErrorMessage 之一。

如果在timeout 毫秒内未收到回复，将自动发送一条错误，指示调用已超时。默认的timeout 为 -1，将被替换为适合进程间通信的、由实现定义的值（通常为 25 秒）。

有关更友好的调用方式，请参阅QDBusInterface::call() 函数。

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

通过此连接发送message ，并立即返回。收到响应后，将调用receiver 对象中的returnMethod 方法。如果发生错误，则会调用errorMethod 方法。

如果在timeout 毫秒内未收到回复，将自动返回一个错误，表明调用已超时。默认的timeout 为 -1，该值将被替换为适合进程间通信的实现定义值（通常为 25 秒）。

此函数仅适用于方法调用。只要参数类型匹配且未发生错误，则保证该插槽将随回复被调用 exactly once。

如果消息已发送，则返回true ；如果无法发送消息，则返回false。

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

将由参数service 、path 、interface 和name 指定的信号连接到对象receiver 中的插槽slot 。参数service 和path 可以为空，表示从任何远程应用程序连接到 (interface,name) 这对信号中的任意一个。

若连接成功，则返回true 。

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

将信号连接到对象 `receiver` 中的槽 `slot `。与之前的 `connect()` 重载不同，该函数允许用户通过 `signature ` 变量指定要连接的参数签名。随后，该函数将验证该签名是否能传递给由 `slot ` 指定的槽，否则返回 `false`。

如果连接成功，则返回true 。

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)

将信号连接到对象receiver 中的插槽slot 。与之前的connect()重载不同，该函数允许通过signature 变量指定要连接的参数签名。随后，该函数将验证该签名是否能传递给由slot 指定的插槽，否则返回false。

argumentMatch 参数按顺序列出了待匹配的字符串参数。请注意，若要匹配空字符串，需传入一个为空但非 null 的QString （即QString("")）。若QString 为 null，则跳过该位置的匹配。

如果连接成功，则返回true 。

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

建立一个类型为type 的连接，连接到已知的总线之一，并为其分配连接名称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)

在地址address 上建立一个点对点连接，并为其关联连接名称name 。返回一个与该连接关联的QDBusConnection 对象。

QDBusConnection::ConnectionCapabilities QDBusConnection::connectionCapabilities() const

返回与总线服务器或对等方协商确定的此连接的功能。如果该QDBusConnection 未连接，则此函数不返回任何功能。

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

将由参数service 、path 、interface 和name 指定的信号从对象receiver 中的插槽slot 中断开连接。这些参数必须与传递给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)

将由参数service 、path 、interface 、name 和signature 指定的信号从对象receiver 中的插槽slot 断开连接。这些参数必须与传递给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)

将由参数service 、path 、interface 、name 、argumentMatch 和signature 指定的信号从对象receiver 中的插槽slot 断开连接。这些参数必须与传递给connect()函数的参数相同。

若断开连接成功，则返回true 。

[static] void QDBusConnection::disconnectFromBus(const QString &name)

关闭名称为name 的总线连接。

请注意，如果仍有与该连接关联的QDBusConnection 对象，则在所有引用都被释放之前，该连接不会被关闭。但是，无法再使用QDBusConnection 构造函数创建新的引用。

[static] void QDBusConnection::disconnectFromPeer(const QString &name)

关闭名称为name 的对等连接。

请注意，如果仍有与该连接关联的QDBusConnection 对象，则在所有引用都被释放之前，该连接不会被关闭。但是，无法再使用QDBusConnection 构造函数创建新的引用。

QDBusConnectionInterface *QDBusConnection::interface() const

返回一个QDBusConnectionInterface 对象，该对象表示此连接上的D-Bus服务器接口。

bool QDBusConnection::isConnected() const

如果该QDBusConnection 对象已连接，则返回 `true `。

QDBusError QDBusConnection::lastError() const

返回此连接中发生的最后一个错误。

此函数专为低级代码设计。若使用QDBusInterface::call()，错误代码将通过其返回值返回。

另请参阅 QDBusInterface 和QDBusMessage 。

[static] QByteArray QDBusConnection::localMachineId()

返回 D-Bus 系统所识别的本地机器 ID。每个运行 D-Bus 的节点或主机都拥有一个唯一的标识符，当它们共享文件系统等资源时，该标识符可用于将其与其他主机区分开来。

请注意，本地机器 ID 不能保证在系统重启后仍然存在，因此不应将此标识符存储在持久存储（如文件系统）中。它仅在本次启动会话的生命周期内保证保持不变。

QString QDBusConnection::name() const

返回此连接的连接名称，该名称作为 name 参数传递给connectToBus()。

连接名称可用于唯一标识与总线建立的实际底层连接。从单个连接创建的副本将始终隐式共享底层连接，因此将具有相同的连接名称。

反之，两个具有不同连接名称的连接，要么始终连接到不同的总线，要么在同一总线上具有不同的唯一名称（由baseService() 返回）。

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

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

返回通过 `registerObject()` 注册的对象，该对象位于由 `path` 指定的对象路径下。

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

将对象object 注册到路径path ，如果注册成功，则返回true 。参数options 指定将通过 D-Bus 暴露对象object 的哪些部分。

此函数不会覆盖现有对象：如果路径path 上已有注册对象，则该函数将返回 false。请先使用unregisterObject() 取消其注册。

ExportChildObjects 标志会根据已注册对象的路径以及子对象的QObject::objectName ，在 D-Bus 上导出子对象。因此，子对象必须具有对象名称，这一点非常重要。

您无法将某个对象注册为已通过 `ExportChildObjects` 注册的对象的子对象。

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

将对象object 注册到路径path ，接口名称为interface ；如果注册成功，则返回true 。参数options 指定将通过 D-Bus 暴露对象object 的哪些部分。

此函数不会覆盖现有对象：如果路径path 下已有注册对象，则该函数将返回 false。请先使用unregisterObject() 取消其注册。

ExportChildObjects 标志会根据已注册对象的路径及其子对象的QObject::objectName ，在 D-Bus 上导出子对象。因此，子对象必须具有对象名称，这一点非常重要。

您无法将一个对象注册为已通过 `ExportChildObjects` 注册的对象的子对象。

bool QDBusConnection::registerService(const QString &serviceName)

尝试将serviceName 注册到D-Bus服务器上，如果注册成功，则返回true 。如果该名称已被其他应用程序注册，则注册将失败。

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

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

通过此连接发送message ，且不等待响应。这适用于错误、信号和返回值，以及那些无需返回值的调用。

如果消息成功入队，则返回 `true `；否则返回 `false`。

[static] QDBusConnection QDBusConnection::sessionBus()

返回一个通过会话总线打开的QDBusConnection 对象。该函数返回的对象引用在应用程序终止之前一直有效；此时，连接将被关闭，该对象也将被删除。

[noexcept] void QDBusConnection::swap(QDBusConnection &other)

将此连接替换为other 。此操作非常快速，且绝不会失败。

[static] QDBusConnection QDBusConnection::systemBus()

返回一个通过系统总线打开的QDBusConnection 对象。该函数返回的对象引用在QCoreApplication 的析构函数执行之前一直有效；此时连接将被关闭，对象也将被删除。

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

取消注册通过registerObject()注册的、位于path 指定的对象路径下的对象；如果mode 的值为QDBusConnection::UnregisterTree ，则同时取消注册该对象的所有子对象。

请注意，无法注销未通过registerObject() 注册的对象。

bool QDBusConnection::unregisterService(const QString &serviceName)

取消注册先前通过registerService() 注册的服务serviceName ，如果操作成功，则返回true 。

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

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

在此对象中创建连接other 的副本。请注意，该对象在复制之前引用的连接不会自动断开。

另请参阅 disconnectFromBus()。