PySide6.QtBluetooth.QBluetoothLocalDevice

class QBluetoothLocalDevice

QBluetoothLocalDevice 类允许访问本地蓝牙设备。更多

PySide6.QtBluetooth.QBluetoothLocalDevice 的继承图

概要

方法

信号

静态函数

注意

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

详细描述

QBluetoothLocalDevice 提供了获取和设置本地蓝牙设备状态的函数。

在iOS上,无法使用此类,因为该平台未公开任何可能提供本地蓝牙设备信息的数据或API。

class Pairing

此枚举描述了两个蓝牙设备之间的配对状态。

常量

描述

QBluetoothLocalDevice.Unpaired

蓝牙设备未配对。

QBluetoothLocalDevice.Paired

蓝牙设备已配对。当远程设备发起与本地设备的连接时,系统将提示用户授权。

QBluetoothLocalDevice.AuthorizedPaired

蓝牙设备已配对。当远程设备发起与本地设备的连接时,系统不会提示用户授权。

class HostMode

此枚举描述了大多数本地蓝牙设备。

常量

描述

QBluetoothLocalDevice.HostPoweredOff

关闭设备电源

QBluetoothLocalDevice.HostConnectable

远程蓝牙设备如果之前已经与本地蓝牙设备配对或知道其地址,则可以连接到本地蓝牙设备。如果设备已关闭,这将启动设备。

QBluetoothLocalDevice.HostDiscoverable

远程蓝牙设备可以发现本地蓝牙设备的存在。设备也将是可连接的,并且已开启电源。在Android上,此模式最多只能持续5分钟。

QBluetoothLocalDevice.HostDiscoverableLimitedInquiry

远程蓝牙设备在执行有限查询时可以发现本地蓝牙设备的存在。这应该用于定位仅在有限时间内可被发现的服务。这可以加快游戏设备之间的发现速度,因为可以跳过不在LimitedInquiry模式下的设备的服务发现。在此模式下,如果需要,设备将可连接并保持开机状态。此模式在Android上不受支持。

注意

在macOS上,无法设置hostMode()。报告的主机模式仅限于HostPoweredOff和HostConnectable。

注意

在Windows上,无法将hostMode()设置为HostDiscoverable或HostDiscoverableLimitedInquiry。使用这些模式等同于HostConnectable。

注意

从 Android 13(API 级别 33)开始,HostPoweredOff 状态依赖于非公开的 Android API,因为公开的 API 已被弃用,请参阅(disable())。这可能会在未来的 Android 版本中发生变化。

注意

至少在Android 12上,设备的蓝牙可见性设置可能会决定设置HostDiscoverable或HostConnectable的结果。例如,如果可见性设置为关闭,可能无法进入HostDiscoverable模式,而是会使用HostConnectable。这可能会在未来的Android版本中发生变化。

class Error

此枚举描述了可能返回的错误

常量

描述

QBluetoothLocalDevice.NoError

没有已知错误

QBluetoothLocalDevice.PairingError

配对错误

QBluetoothLocalDevice.MissingPermissionsError

操作系统请求的权限未被用户授予。

QBluetoothLocalDevice.UnknownError

未知错误

__init__([parent=None])
Parameters:

父对象QObject

使用parent构造一个QBluetoothLocalDevice

注意

从 Android 12(API 级别 31)开始,此类的构建需要 蓝牙运行时权限BLUETOOTH_SCANBLUETOOTH_CONNECT)。如果未授予权限,设备将无效。

另请参阅

isValid()

__init__(address[, parent=None])
Parameters:

address 构造新的 QBluetoothLocalDevice。如果 address 是默认构造的,则生成的本地设备将选择本地默认设备。

注意

从 Android 12(API 级别 31)开始,此类的构建需要 蓝牙运行时权限BLUETOOTH_SCANBLUETOOTH_CONNECT)。如果未授予权限,设备将无效。

另请参阅

isValid()

address()
Return type:

QBluetoothAddress

返回此蓝牙设备的MAC地址。

注意

在Android上,从Android 6.0开始,此函数始终返回常量值02:00:00:00:00:00作为本地地址。对设备本地MAC地址的程序化访问已被移除。

static allDevices()
Return type:

QBluetoothHostInfo的列表

返回所有可用的本地蓝牙设备列表。在macOS上,只有“默认”本地设备。

connectedDevices()
Return type:

QBluetoothAddress的列表

返回已连接设备的列表。此列表与当前配对设备的列表不同。

在Android和macOS上,无法检索已连接设备的列表。只能监听(断开)连接的变化。为了方便起见,此类自实例化以来会监控所有连接和断开事件,并在调用此函数时返回当前列表。因此,在创建实例后不久,此函数可能会返回一个空列表。

deviceConnected(address)
Parameters:

地址QBluetoothAddress

当本地设备与具有address的远程设备建立连接时,会发出此信号。

deviceDisconnected(address)
Parameters:

地址QBluetoothAddress

当本地设备与具有address的远程蓝牙设备断开连接时,会发出此信号。

errorOccurred(error)
Parameters:

错误Error

如果在配对过程中出现异常error,则发出信号。

hostMode()
Return type:

HostMode

返回此本地蓝牙设备的当前主机模式。在macOS上,它要么是HostPoweredOff,要么是HostConnectable

另请参阅

setHostMode()

hostModeStateChanged(state)
Parameters:

状态HostMode

主机的state已转换为不同的HostMode

isValid()
Return type:

布尔

如果QBluetoothLocalDevice代表一个可用的本地蓝牙设备,则返回true;否则返回false。

如果由该类的实例表示的本地蓝牙适配器从系统中移除(例如移除底层蓝牙适配器),则该实例将变为无效。即使相同的蓝牙适配器返回到系统,已经无效的QBluetoothLocalDevice实例仍然保持无效。

注意

从 Android 12(API 级别 31)开始,此类的构建需要 蓝牙运行时权限BLUETOOTH_SCANBLUETOOTH_CONNECT)。如果未授予权限,设备将无效。

另请参阅

allDevices()

name()
Return type:

字符串

返回用户为此蓝牙设备分配的名称。

pairingFinished(address, pairing)
Parameters:

配对或取消配对已完成,使用address。当前配对状态为pairing。如果配对请求未成功,则不会发出此信号。如果配对请求失败,则会发出errorOccurred()信号。该信号仅针对之前通过调用当前对象实例的requestPairing()请求的配对请求发出。

pairingStatus(address)
Parameters:

地址QBluetoothAddress

Return type:

配对

返回address的当前蓝牙配对状态,如果它未配对、已配对或已配对并授权。

powerOn()

如果设备已关闭电源,则在将其返回到hostMode()状态后,开启设备电源。

注意

由于支持平台上的安全策略不同,此方法在不同平台上可能有不同的行为。例如,系统可能会在打开或关闭蓝牙之前要求用户确认。在macOS上,无法打开/关闭蓝牙。详情请参阅特定平台的蓝牙文档。

requestPairing(address, pairing)
Parameters:

设置与addresspairing状态。结果通过信号pairingFinished()返回。

在Android和macOS上,AuthorizedPaired是不可能的,其行为将与Paired相同。在Windows上,具体的配对模式决定由操作系统决定。

在macOS上,无法取消配对设备。如果请求取消配对,尽管设备仍然保持配对状态,pairingFinished() 会立即发出。可以请求为之前未配对的设备进行配对。此外,AuthorizedPaired 的行为与 Paired 相同。

注意:创建配对可能需要几分钟,并且可能需要用户确认。

setHostMode(mode)
Parameters:

modeHostMode

将此本地蓝牙设备的主机模式设置为mode

一些转换,例如打开或关闭设备,可能需要一些时间。因此,只有在hostModeStateChanged()信号完成前一个请求后,才能进行后续调用。如果忽略这一点,这一系列调用的结果将无法明确定义。

注意

由于支持平台上的安全策略不同,此方法在不同平台上可能具有不同的行为。例如,系统可能会在打开或关闭蓝牙之前要求用户确认,并且可能不支持所有主机模式。在macOS上,无法通过编程方式更改hostMode()。用户只能在系统偏好设置中切换蓝牙的开关。在Windows上,此方法必须从UI线程调用,因为它可能需要用户确认。请参阅特定平台的蓝牙文档以获取详细信息。

另请参阅

hostMode()