PySide6.QtBluetooth.QBluetoothSocket

class QBluetoothSocket

QBluetoothSocket 类允许连接到运行蓝牙服务器的蓝牙设备。更多…

PySide6.QtBluetooth.QBluetoothSocket 的继承图

概要

方法

信号

注意

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

详细描述

QBluetoothSocket 支持两种套接字类型，L2CAP 和 RFCOMM。

L2CAP 是一种低级别的面向数据报的蓝牙套接字。Android 不支持 L2CAP 用于套接字连接。

RFCOMM 是一种可靠的、面向流的套接字。RFCOMM 套接字模拟 RS-232 串行端口。

要创建与蓝牙服务的连接，请创建适当类型的套接字并调用connectToService()，传递蓝牙地址和端口号。QBluetoothSocket在连接建立时将发出connected()信号。

如果平台不支持Protocol，调用connectToService()将会发出UnsupportedProtocolError错误。

注意

QBluetoothSocket 不支持同步读写操作。诸如 waitForReadyRead() 和 waitForBytesWritten() 等函数未实现。I/O 操作应使用 readyRead()、read() 和 write() 来执行。

在iOS上，由于平台没有暴露允许访问QBluetoothSocket相关功能的API，因此无法使用此类。

注意

在macOS Monterey（12）上，当执行模态对话框或进入事件跟踪模式（例如通过长按窗口关闭按钮）时，套接字数据流会暂停。这可能会在未来的macOS版本中有所改变。

class SocketState

此枚举描述了蓝牙套接字的状态。

常量

描述

QBluetoothSocket.SocketState.UnconnectedState

Socket未连接。

QBluetoothSocket.SocketState.ServiceLookupState

Socket 正在查询连接参数。

QBluetoothSocket.SocketState.ConnectingState

Socket 正在尝试连接到设备。

QBluetoothSocket.SocketState.ConnectedState

Socket已连接到设备。

QBluetoothSocket.SocketState.BoundState

Socket已绑定到本地地址和端口。

QBluetoothSocket.SocketState.ClosingState

Socket已连接，一旦所有待处理的数据写入socket，它将被关闭。

QBluetoothSocket.SocketState.ListeningState

Socket 正在监听传入的连接。
class SocketError

此枚举描述了蓝牙套接字错误类型。

常量

描述

QBluetoothSocket.SocketError.UnknownSocketError

发生了一个未知错误。

QBluetoothSocket.SocketError.NoSocketError

没有错误。用于测试。

QBluetoothSocket.SocketError.HostNotFoundError

无法找到远程主机。

QBluetoothSocket.SocketError.ServiceNotFoundError

无法在远程主机上找到服务UUID。

QBluetoothSocket.SocketError.NetworkError

尝试从套接字读取或写入时返回错误

QBluetoothSocket.SocketError.UnsupportedProtocolError

此平台不支持Protocol。

QBluetoothSocket.SocketError.OperationError

尝试在套接字处于不允许操作的状态下执行操作。

QBluetoothSocket.SocketError.RemoteHostClosedError

远程主机关闭了连接。

QBluetoothSocket.SocketError.MissingPermissionsError

操作系统请求的权限未被用户授予。
__init__([parent=None])
Parameters:

父对象 – QObject

使用parent构建一个蓝牙套接字。

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

构建一个类型为socketType的蓝牙套接字，带有parent。

abort()

中止当前连接并重置套接字。与disconnectFromService()不同，此函数会立即关闭套接字，丢弃写缓冲区中的任何待处理数据。

注意

在Android上，中止套接字需要与Android线程进行异步交互。因此，相关的disconnected()和stateChanged()信号会延迟，直到线程完成关闭操作。

另请参阅

disconnectFromService() close()

connectToService(service[, openMode=QIODeviceBase.OpenModeFlag.ReadWrite])
Parameters:

尝试连接到由service描述的服务。

套接字在给定的openMode中打开。如果service指定了不同的socketProtocol()，则socketType()将被忽略。

套接字首先进入ConnectingState并尝试连接到提供service的设备。如果连接建立，QBluetoothSocket进入ConnectedState并发出connected()。

在任何时候，套接字都可以发出 errorOccurred() 来表明发生了错误。

请注意，大多数平台在连接到远程设备之前需要进行配对。否则，连接过程可能会失败。

在Android上，只能进行RFCOMM连接。此函数忽略任何套接字协议指示符并假定为RFCOMM。

connectToService(address, uuid[, mode=QIODeviceBase.OpenModeFlag.ReadWrite])
Parameters:
connectToService(address, uuid[, openMode=QIODeviceBase.OpenModeFlag.ReadWrite])
Parameters:

尝试与地址为address的设备上由uuid标识的服务建立连接。

套接字在给定的 openMode 中打开。

对于BlueZ，套接字首先进入ServiceLookupState并查询uuid的连接参数。如果成功检索到服务参数，套接字进入ConnectingState，并尝试连接到address。如果连接建立，QBluetoothSocket进入ConnectedState并发出connected()。

在Android上，服务连接可以直接使用远程服务的UUID建立。因此，平台不需要ServiceLookupState，并且socketType()始终设置为RfcommProtocol。

在任何时候，套接字都可以发出 errorOccurred() 来表明发生了错误。

请注意，大多数平台在连接到远程设备之前需要进行配对。否则，连接过程可能会失败。

connectToService(address, port[, openMode=QIODeviceBase.OpenModeFlag.ReadWrite])
Parameters:

尝试在给定的port上与address建立连接。

套接字在给定的 openMode 中打开。

套接字首先进入ConnectingState，并尝试连接到address。如果连接建立成功，QBluetoothSocket将进入ConnectedState并发出connected()。

在任何时候，套接字都可以发出 errorOccurred() 来表明发生了错误。

在Android和BlueZ（版本5.46或以上）上，无法使用端口建立到服务的连接。调用此函数将发出ServiceNotFoundError。

请注意，大多数平台在连接到远程设备之前需要进行配对。否则，连接过程可能会失败。

connected()

当连接建立时，会发出此信号。

disconnectFromService()

尝试关闭套接字。如果有待写入的数据，QBluetoothSocket 将进入 ClosingState 并等待所有数据写入完成。最终，它将进入 UnconnectedState 并发出 disconnected() 信号。

另请参阅

connectToService()

disconnected()

当套接字断开连接时，会发出此信号。

doDeviceDiscovery(service, openMode)
Parameters:

开始设备发现以查找service并使用openMode打开套接字。如果套接字是使用服务uuid设备地址创建的，则使用服务发现来查找要连接的端口号。

error()
Return type:

SocketError

返回最后一个错误。

errorOccurred(error)
Parameters:

错误 – SocketError

当发生error时，会发出此信号。

另请参阅

error()

localAddress()
Return type:

QBluetoothAddress

返回本地设备的地址。

尽管某些平台可能有所不同，但通常必须连接套接字以保证返回有效地址。特别是在处理支持多个本地蓝牙适配器的平台时，这一点尤为重要。

localName()
Return type:

字符串

返回本地设备的名称。

尽管某些平台可能有所不同，但通常必须连接socket以保证返回有效的名称。特别是在处理支持多个本地蓝牙适配器的平台时，这一点尤为重要。

localPort()
Return type:

整数

如果可用，返回本地套接字的端口号，否则返回0。尽管某些平台可能有所不同，但通常必须连接套接字以保证返回有效的端口号。

在Android和macOS上，此功能不受支持并返回0。

peerAddress()
Return type:

QBluetoothAddress

返回对等设备的地址。

peerName()
Return type:

字符串

返回对等设备的名称。

peerPort()
Return type:

整数

如果可用，返回对等套接字的端口号，否则返回0。在Android上，此功能不受支持。

preferredSecurityFlags()
Return type:

Security的组合

返回用于初始连接尝试的安全参数。

安全参数可能在连接建立期间或之后由双方重新协商。如果发生这种变化，它不会反映在此标志的值中。

在macOS上，此标志始终设置为Secure。

setPreferredSecurityFlags(flags)
Parameters:

flags – Security 的组合

设置连接尝试的首选安全参数为flags。此值在调用connectToService()时被纳入。因此，要更改现有连接的此参数，需要重新连接。

在Bluez上，此属性默认设置为Authorization。

在macOS上，此值被忽略，因为该平台不允许访问套接字的安全参数。默认情况下，平台更倾向于安全/加密的连接，因此此函数始终返回Secure。

Android 仅支持两种安全级别（安全和非安全）。如果此标志设置为 NoSecurity，套接字对象将不会使用任何身份验证或加密。任何其他安全标志组合都将触发安全的蓝牙连接。此标志默认设置为 Secure。

注意

安全连接需要在两个设备之间进行配对。在某些平台上，配对在建立连接期间会自动启动。其他平台则要求应用程序在尝试连接之前手动触发配对。

另请参阅

preferredSecurityFlags()

setSocketDescriptor(socketDescriptor, socketType[, socketState=QBluetoothSocket.SocketState.ConnectedState[, openMode=QIODeviceBase.OpenModeFlag.ReadWrite]])
Parameters:
Return type:

布尔

设置套接字使用socketDescriptor，类型为socketType，状态为socketState，模式为openMode。

套接字描述符由QBluetoothSocket实例拥有，一旦完成可能会关闭。

成功时返回 true。

另请参阅

socketDescriptor()

setSocketError(error)
Parameters:

错误 – SocketError

将最后发生的错误类型设置为error_。

setSocketState(state)
Parameters:

状态 – SocketState

将套接字状态设置为 state。

socketDescriptor()
Return type:

整数

返回平台特定的套接字描述符（如果可用）。如果描述符不可用或发生错误，此函数返回-1。

另请参阅

setSocketDescriptor()

socketType()
Return type:

协议

返回套接字类型。套接字会自动调整以适应远程服务提供的协议。

Android 仅支持基于 RFCOMM 的套接字。

state()
Return type:

SocketState

返回套接字的当前状态。

stateChanged(state)
Parameters:

状态 – SocketState

当套接字状态更改为 state 时，会发出此信号。