PySide6.QtDBus.QDBusConnection

class QDBusConnection

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

概要

方法

静态函数

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

这个类是D-Bus会话的起点。使用它，您可以访问远程对象、接口；将远程信号连接到您的对象的插槽；注册对象等。

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

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

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

为了方便两种最常见的连接类型，sessionBus() 和 systemBus() 函数分别返回与会话服务器守护进程和系统服务器守护进程的开放连接。这些连接在首次使用时打开，并在 QCoreApplication 析构函数运行时关闭。

D-Bus 还支持点对点连接，无需总线服务器守护进程。使用此功能，两个应用程序可以相互通信并交换消息。这可以通过将地址传递给 connectToBus() 函数来实现，该地址由另一个使用 QDBusServer 的 D-Bus 应用程序打开。

class BusType

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

常量

描述

QDBusConnection.SessionBus

会话总线，与正在运行的桌面会话相关联

QDBusConnection.SystemBus

系统总线，用于与系统范围内的进程通信

QDBusConnection.ActivationBus

激活总线，启动服务的总线的“别名”

在会话总线上，可以找到同一用户共享同一桌面会话的其他应用程序（因此得名）。然而，在系统总线上，通常会找到为整个系统共享的进程。

class RegisterOption

（继承自 enum.Flag）指定用于向连接注册对象的选项。可能的值为：

常量

描述

QDBusConnection.ExportAdaptors

导出在此对象中找到的适配器的内容

QDBusConnection.ExportScriptableSlots

导出此对象的可脚本化插槽

QDBusConnection.ExportScriptableSignals

导出此对象的可脚本化信号

QDBusConnection.ExportScriptableProperties

导出此对象的可脚本化属性

QDBusConnection.ExportScriptableInvokables

导出此对象的可脚本调用的方法

QDBusConnection.ExportScriptableContents

ExportScriptableSlots | ExportScriptableSignals | ExportScriptableProperties 的简写形式

QDBusConnection.ExportNonScriptableSlots

导出此对象的非脚本插槽

QDBusConnection.ExportNonScriptableSignals

导出此对象的非脚本信号

QDBusConnection.ExportNonScriptableProperties

导出此对象的非脚本属性

QDBusConnection.ExportNonScriptableInvokables

导出此对象的非脚本可调用项

QDBusConnection.ExportNonScriptableContents

ExportNonScriptableSlots | ExportNonScriptableSignals | ExportNonScriptableProperties 的简写形式

QDBusConnection.ExportAllSlots

导出此对象的所有插槽

QDBusConnection.ExportAllSignals

导出此对象的所有信号

QDBusConnection.ExportAllProperties

导出此对象的所有属性

QDBusConnection.ExportAllInvokables

导出此对象的所有可调用项

QDBusConnection.ExportAllContents

导出此对象的所有内容

QDBusConnection.ExportChildObjects

导出此对象的子对象

另请参阅

registerObject() QDBusAbstractAdaptor 使用适配器

class UnregisterMode

取消注册对象路径的模式：

常量

描述

QDBusConnection.UnregisterNode

仅注销此节点：不注销子对象

QDBusConnection.UnregisterTree

注销此节点及其所有子树

请注意，如果此对象是使用ExportChildObjects选项注册的，UnregisterNode 也将取消注册子对象。

class VirtualObjectRegisterOption
class ConnectionCapability

(继承自 enum.Flag) 此枚举描述了 D-Bus 连接可用的功能。

常量

描述

QDBusConnection.UnixFileDescriptorPassing

允许将Unix文件描述符传递给其他进程（参见QDBusUnixFileDescriptor）

另请参阅

connectionCapabilities()

__init__(other)
Parameters:

其他 – QDBusConnection

创建other连接的副本。

__init__(name)
Parameters:

name – str

创建一个附加到名为name的连接的QDBusConnection对象。

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

asyncCall(message[, timeout=-1])
Parameters:
Return type:

QDBusPendingCall

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

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

请参阅asyncCall()函数，了解更友好的调用方式。

注意

由于实现限制，应用程序本身注册的对象的方法调用永远不会是异步的。

baseService()
Return type:

字符串

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

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

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

call(message[, mode=QDBus.Block[, timeout=-1]])
Parameters:
Return type:

QDBusMessage

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

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

请参阅call()函数，了解更友好的拨打电话方式。

警告

如果 mode 是 BlockWithGui，此函数将重新进入 Qt 事件循环以等待回复。在等待期间，它可能会向您的应用程序传递信号和其他方法调用。因此，每当使用 call() 进行调用时，必须准备好处理重入。

callWithCallback(message, receiver, slot[, timeout=-1])
Parameters:
Return type:

布尔

这是一个重载函数。

通过此连接发送message并立即返回。当收到回复时，方法returnMethod将在receiver对象中被调用。

此函数仅适用于方法调用。只要参数类型匹配且没有发生错误，保证槽将仅被调用一次以获取回复。

此函数很危险，因为它无法报告错误，包括超时过期。

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

callWithCallback(message, receiver, returnMethod, errorMethod[, timeout=-1])
Parameters:

  • 消息 – QDBusMessage

  • receiver – QObject

  • returnMethod – str

  • errorMethod – str

  • timeout – int

Return type:

布尔

通过此连接发送message并立即返回。当收到回复时，将在receiver对象中调用方法returnMethod。如果发生错误，则将调用方法errorMethod。

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

此函数仅适用于方法调用。只要参数类型匹配且没有发生错误，保证槽将仅被调用一次以获取回复。

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

connect(service, path, interface, name, receiver, slot)
Parameters:

  • service – str

  • path – 字符串

  • interface – str

  • name – str

  • receiver – QObject

  • slot – str

Return type:

布尔

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

如果连接成功，返回 true。

警告

只有当参数匹配时，信号才会传递给槽。这种验证只能在接收到信号时进行，而不是在连接时。

connect(service, path, interface, name, signature, receiver, slot)
Parameters:

  • service – str

  • path – 字符串

  • interface – str

  • name – str

  • signature – str

  • receiver – QObject

  • slot – str

Return type:

布尔

这是一个重载函数。

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

如果连接成功，返回 true。

注意

此函数验证信号签名是否与插槽的参数匹配，但它不验证远程服务中是否存在具有给定签名的实际信号。

connect(service, path, interface, name, argumentMatch, signature, receiver, slot)
Parameters:

  • service – str

  • path – 字符串

  • interface – str

  • name – str

  • argumentMatch – 字符串列表

  • signature – str

  • receiver – QObject

  • slot – str

Return type:

布尔

这是一个重载函数。

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

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

如果连接成功，返回 true。

注意

此函数验证信号签名是否与插槽的参数匹配，但它不验证远程服务中是否存在具有给定签名的实际信号。

static connectToBus(type, name)
Parameters:
Return type:

QDBusConnection

打开一个类型为type的连接到一个已知的总线，并将其与连接名称name关联。返回一个与该连接关联的QDBusConnection对象。

static connectToBus(address, name)
Parameters:

  • address – str

  • name – str

Return type:

QDBusConnection

打开一个到地址为address的私有总线的连接，并将其与连接名称name关联。返回一个与该连接关联的QDBusConnection对象。

static connectToPeer(address, name)
Parameters:

  • address – str

  • name – str

Return type:

QDBusConnection

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

connectionCapabilities()
Return type:

ConnectionCapability的组合

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

disconnect(service, path, interface, name, receiver, slot)
Parameters:

  • service – str

  • path – 字符串

  • interface – str

  • name – str

  • receiver – QObject

  • slot – str

Return type:

布尔

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

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

disconnect(service, path, interface, name, signature, receiver, slot)
Parameters:

  • service – str

  • path – 字符串

  • interface – str

  • name – str

  • signature – str

  • receiver – QObject

  • slot – str

Return type:

布尔

这是一个重载函数。

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

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

disconnect(service, path, interface, name, argumentMatch, signature, receiver, slot)
Parameters:

  • service – str

  • path – 字符串

  • interface – str

  • name – str

  • argumentMatch – 字符串列表

  • signature – str

  • receiver – QObject

  • slot – str

Return type:

布尔

这是一个重载函数。

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

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

static disconnectFromBus(name)
Parameters:

name – str

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

请注意，如果仍有与同一连接关联的QDBusConnection对象，则在所有引用被释放之前，连接将不会关闭。然而，无法再使用QDBusConnection构造函数创建进一步的引用。

static disconnectFromPeer(name)
Parameters:

name – str

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

请注意，如果仍有与同一连接关联的QDBusConnection对象，则在所有引用被释放之前，连接将不会关闭。然而，无法再使用QDBusConnection构造函数创建进一步的引用。

interface()
Return type:

QDBusConnectionInterface

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

internalPointer()
Return type:

void

isConnected()
Return type:

布尔

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

lastError()
Return type:

QDBusError

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

此函数是为低级代码提供的。如果您正在使用call()，错误代码将通过其返回值报告。

static localMachineId()
Return type:

QByteArray

返回D-Bus系统所知的本地机器ID。每个运行D-Bus的节点或主机都有一个唯一的标识符，如果它们共享像文件系统这样的资源，可以用来区分它们。

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

name()
Return type:

字符串

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

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

相反，具有不同连接名称的两个连接将始终连接到不同的总线，或者在该总线上具有不同的唯一名称（如baseService()返回的那样）。

objectRegisteredAt(path)
Parameters:

路径 – 字符串

Return type:

QObject

返回在由path给出的对象路径上使用registerObject()注册的对象。

registerObject(path, object[, options=QDBusConnection.RegisterOption.ExportAdaptors])
Parameters:
Return type:

布尔

在路径 path 注册对象 object，如果注册成功则返回 true。options 参数指定了对象 object 通过 D-Bus 暴露的程度。

此函数不会替换现有对象：如果路径 path 上已经注册了一个对象，此函数将返回 false。请先使用 unregisterObject() 取消注册。

ExportChildObjects 标志根据注册对象的路径和子对象的 QObject::objectName 在 D-Bus 上导出子对象。因此，子对象拥有一个对象名称是很重要的。

您不能将一个对象注册为已使用ExportChildObjects注册的对象的子对象。

registerObject(path, interface, object[, options=QDBusConnection.RegisterOption.ExportAdaptors])
Parameters:
Return type:

布尔

这是一个重载函数。

在路径 path 上注册对象 object，并使用接口名称 interface，如果注册成功则返回 true。options 参数指定对象 object 通过 D-Bus 暴露的程度。

此函数不会替换现有对象：如果路径 path 上已经注册了一个对象，此函数将返回 false。请先使用 unregisterObject() 取消注册。

ExportChildObjects 标志根据注册对象的路径和子对象的 QObject::objectName 导出 D-Bus 上的子对象。因此，子对象拥有一个对象名称是很重要的。

您不能将一个对象注册为已使用ExportChildObjects注册的对象的子对象。

registerService(serviceName)
Parameters:

serviceName – str

Return type:

布尔

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

registerVirtualObject(path, object[, options=QDBusConnection.VirtualObjectRegisterOption.SingleNode])
Parameters:
Return type:

布尔

send(message)
Parameters:

消息 – QDBusMessage

Return type:

布尔

通过此连接发送message，而不等待回复。这适用于错误、信号、返回值以及不需要返回值的调用。

如果消息成功排队，则返回true，否则返回false。

static sessionBus()
Return type:

QDBusConnection

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

swap(other)
Parameters:

其他 – QDBusConnection

将此QDBusConnection实例与other交换。

static systemBus()
Return type:

QDBusConnection

返回一个使用系统总线打开的QDBusConnection对象。此函数返回的对象引用在QCoreApplication的析构函数运行之前有效，当连接关闭时，对象将被删除。

unregisterObject(path[, mode=QDBusConnection.UnregisterMode.UnregisterNode])
Parameters:

注销一个通过registerObject()在path指定的对象路径上注册的对象，如果mode是UnregisterTree，则同时注销其所有子对象。

请注意，您不能注销未通过registerObject()注册的对象。

unregisterService(serviceName)
Parameters:

serviceName – str

Return type:

布尔

注销之前通过registerService()注册的服务serviceName，如果成功则返回true。