QBluetoothSocket Class

成员函数文档

[explicit] QBluetoothSocket::QBluetoothSocket(QObject *parent = nullptr)

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

[explicit] QBluetoothSocket::QBluetoothSocket(QBluetoothServiceInfo::Protocol socketType, QObject *parent = nullptr)

创建一个类型为socketType 的蓝牙套接字，其parent 。

[virtual noexcept] QBluetoothSocket::~QBluetoothSocket()

销毁蓝牙套接字。

void QBluetoothSocket::abort()

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

另请参阅 disconnectFromService() 和close()。

[override virtual] qint64 QBluetoothSocket::bytesAvailable() const

重写了：QIODevice::bytesAvailable() const。

返回等待读取的传入字节数。

另请参阅 bytesToWrite() 和read()。

[override virtual] qint64 QBluetoothSocket::bytesToWrite() const

重写：QIODevice::bytesToWrite() const。

返回待写入的字节数。当控制权返回事件循环时，这些字节将被写入。

[override virtual] bool QBluetoothSocket::canReadLine() const

重写：QIODevice::canReadLine() const。

如果能够从设备中读取至少一行，则返回 true

[override virtual] void QBluetoothSocket::close()

重写了：QIODevice::close()。

断开套接字与设备的连接。

void QBluetoothSocket::connectToService(const QBluetoothServiceInfo &service, QIODeviceBase::OpenMode openMode = ReadWrite)

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

已在指定的openMode 中打开套接字。如果service 指定的QBluetoothServiceInfo::socketProtocol() 与当前不同，则socketType() 将被忽略。

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

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

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

在 Android 上，仅支持 RFCOMM 连接。此函数会忽略任何套接字协议指示符，并默认使用 RFCOMM。

另请参阅 state() 和disconnectFromService()。

void QBluetoothSocket::connectToService(const QBluetoothAddress &address, const QBluetoothUuid &uuid, QIODeviceBase::OpenMode openMode = ReadWrite)

尝试连接到地址为address 的设备上，由uuid 标识的服务。

在指定的openMode 中打开了套接字。

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

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

在任何时候，套接字都可以调用errorOccurred() 来指示发生了错误。

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

另请参阅 state() 和disconnectFromService()。

void QBluetoothSocket::connectToService(const QBluetoothAddress &address, quint16 port, QIODeviceBase::OpenMode openMode = ReadWrite)

尝试通过给定的port 与address 建立连接。

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

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

在任何时候，套接字均可发出errorOccurred() 来指示发生了错误。

在 Android 和 BlueZ（5.46 及以上版本）上，无法通过端口与服务建立连接。调用此函数将触发ServiceNotFoundError 。

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

另请参阅 state() 和disconnectFromService()。

[signal] void QBluetoothSocket::connected()

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

另请参阅 QBluetoothSocket::SocketState::ConnectedState 和stateChanged()。

void QBluetoothSocket::disconnectFromService()

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

另请参阅 connectToService()。

[signal] void QBluetoothSocket::disconnected()

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

另请参阅 QBluetoothSocket::SocketState::UnconnectedState 和stateChanged()。

[protected] void QBluetoothSocket::doDeviceDiscovery(const QBluetoothServiceInfo &service, QIODeviceBase::OpenMode openMode)

启动service 的设备发现功能，并使用openMode 打开套接字。如果套接字是使用服务UUID设备地址创建的，请使用服务发现功能查找要连接的端口号。

QBluetoothSocket::SocketError QBluetoothSocket::error() const

返回最后一次出现的错误。

[signal, since 6.2] void QBluetoothSocket::errorOccurred(QBluetoothSocket::SocketError error)

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

该函数在 Qt 6.2 中引入。

另请参阅 error()。

QString QBluetoothSocket::errorString() const

返回该错误的用户可视文本字符串。

[override virtual] bool QBluetoothSocket::isSequential() const

重新实现了：QIODevice::isSequential() const。

QBluetoothAddress QBluetoothSocket::localAddress() const

返回本地设备的地址。

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

QString QBluetoothSocket::localName() const

返回本地设备的名称。

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

quint16 QBluetoothSocket::localPort() const

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

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

QBluetoothAddress QBluetoothSocket::peerAddress() const

返回对等设备的地址。

QString QBluetoothSocket::peerName() const

返回对等设备的名称。

quint16 QBluetoothSocket::peerPort() const

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

QBluetooth::SecurityFlags QBluetoothSocket::preferredSecurityFlags() const

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

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

在 macOS 上，该标志始终设置为 `QBluetooth::Security::Secure`。

另请参阅 setPreferredSecurityFlags()。

[override virtual protected] qint64 QBluetoothSocket::readData(char *data, qint64 maxSize)

重写了：QIODevice::readData(char *data, qint64 maxSize)。

void QBluetoothSocket::setPreferredSecurityFlags(QBluetooth::SecurityFlags flags)

将连接尝试的首选安全参数设置为flags 。该值会在调用connectToService()时被采用。因此，若要更改现有连接的此参数，必须重新建立连接。

在 Linux BlueZ 后端中，这些标志与内核安全级别对应：

• QBluetooth::Security::Authorization 映射到BT_SECURITY_LOW ；
• QBluetooth::Security::Encryption 映射到BT_SECURITY_MEDIUM ；
• QBluetooth::Security::Secure 映射到BT_SECURITY_HIGH ；
• QBluetooth::Security::Authentication 该标志未被内核使用，将被忽略。

默认值为QBluetooth::Security::Authorization 。

在采用 BlueZ D-Bus 后端的 Linux 系统以及 Windows 系统上，不支持此标志，且会被忽略。

在 macOS 上，由于该平台不允许访问套接字的安全参数，因此该值会被忽略。不过，默认情况下该平台优先采用安全/加密连接，因此该函数始终返回 `QBluetooth::Security::Secure`。

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

另请参阅 preferredSecurityFlags()。

bool QBluetoothSocket::setSocketDescriptor(int socketDescriptor, QBluetoothServiceInfo::Protocol socketType, QBluetoothSocket::SocketState socketState = SocketState::ConnectedState, QIODeviceBase::OpenMode openMode = ReadWrite)

将套接字配置为使用类型为socketType 的socketDescriptor ，该 处于socketState 状态，且模式为openMode 。

该套接字描述符由QBluetoothSocket 实例拥有，并在操作完成后可能被关闭。

成功时返回true 。

另请参阅 socketDescriptor()。

[protected] void QBluetoothSocket::setSocketError(QBluetoothSocket::SocketError error_)

将上次发生的错误类型设置为error_ 。

[protected] void QBluetoothSocket::setSocketState(QBluetoothSocket::SocketState state)

将套接字状态设置为state 。

int QBluetoothSocket::socketDescriptor() const

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

另请参阅 ` setSocketDescriptor()`。

QBluetoothServiceInfo::Protocol QBluetoothSocket::socketType() const

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

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

QBluetoothSocket::SocketState QBluetoothSocket::state() const

返回套接字的当前状态。

[signal] void QBluetoothSocket::stateChanged(QBluetoothSocket::SocketState state)

当套接字状态变为“state ”时，会发出此信号。

另请参阅 connected()、disconnected()、state() 以及QBluetoothSocket::SocketState 。

[override virtual protected] qint64 QBluetoothSocket::writeData(const char *data, qint64 maxSize)

重新实现了：QIODevice::writeData(const char *data, qint64 maxSize)。