QLowEnergyController Class

成员函数文档

[virtual noexcept] QLowEnergyController::~QLowEnergyController()

销毁QLowEnergyController 实例。

QLowEnergyService *QLowEnergyController::addService(const QLowEnergyServiceData &service, QObject *parent = nullptr)

构造并返回一个QLowEnergyService 对象，其中parent 来自service 。控制器必须在PeripheralRole 和UnconnectedState 中。service 对象必须有效。

另请参阅 stopAdvertising(),disconnectFromDevice() 和QLowEnergyServiceData::addIncludedService 。

void QLowEnergyController::connectToDevice()

连接远程蓝牙低功耗设备。

如果控制器的state() 不等于UnconnectedState ，则该函数不会执行任何操作。一旦连接成功建立，就会发出connected() 信号。

在 Linux/BlueZ 系统上，无法使用该类的两个实例连接到同一个远程设备。对该函数的第二次调用可能会出错。这一限制可能会在今后的版本中取消。

另请参见 disconnectFromDevice()。

[signal] void QLowEnergyController::connected()

当控制器成功连接到远程低能耗设备（如果控制器位于CentralRole 中）或远程低能耗设备连接到控制器（如果控制器位于PeripheralRole 中）时，就会发出该信号。在 iOS、macOS 和 Android 系统中，如果控制器位于PeripheralRole ，则此信号不可靠。在 iOS 和 macOS 系统中，控制器只会在某个中心设备尝试写入/读取特征/描述符时猜测该中心设备连接到了我们的外设。在 Android 上，控制器会监控所有连接的 GATT 设备。在 Linux BlueZ DBus 外围设备后端，远程设备在首次读取/写入特性或描述符时被视为已连接。

[signal] void QLowEnergyController::connectionUpdated(const QLowEnergyConnectionParameters &newParameters)

该信号在连接参数发生变化时发出。这可能是调用requestConnectionUpdate() 的结果，也可能是由于其他原因，例如连接的另一方请求新参数。新值可从newParameters 获取。

另请参见 requestConnectionUpdate()。

[static] QLowEnergyController *QLowEnergyController::createCentral(const QBluetoothDeviceInfo &remoteDevice, QObject *parent = nullptr)

返回该类的一个新对象，该对象位于CentralRole 中，其父对象为parent 。remoteDevice 指的是稍后将建立连接的设备。

控制器使用本地默认蓝牙适配器进行连接管理。

另请参阅 QLowEnergyController::CentralRole 。

[static] QLowEnergyController *QLowEnergyController::createCentral(const QBluetoothDeviceInfo &remoteDevice, const QBluetoothAddress &localDevice, QObject *parent = nullptr)

返回该类的一个新实例parent 。

remoteDevice 必须包含远程蓝牙低功耗设备的地址，该对象稍后应尝试与之连接。

连接通过localDevice 建立。如果localDevice 无效，则会自动选择本地默认设备。如果localDevice 指定的本地设备不是本地蓝牙适配器，调用connectToDevice() 后，error() 将被设置为InvalidBluetoothAdapterError 。

请注意，只有在使用 BlueZ 时才能指定用于连接的本地设备。所有其他平台都不支持此功能。

[static] QLowEnergyController *QLowEnergyController::createPeripheral(QObject *parent = nullptr)

返回该类的一个新对象，该对象位于PeripheralRole 中，其父对象为parent 。通常，接下来的步骤是添加一些服务，最后在返回的对象上调用startAdvertising() 。

控制器使用本地默认蓝牙适配器进行连接管理。

另请参见 QLowEnergyController::PeripheralRole 。

[static, since 6.2] QLowEnergyController *QLowEnergyController::createPeripheral(const QBluetoothAddress &localDevice, QObject *parent = nullptr)

返回该类的一个新对象，该对象位于PeripheralRole 中，其父对象为parent ，并正在使用localDevice 。通常，接下来的步骤是添加一些服务，最后在返回的对象上调用startAdvertising() 。

外围设备在localDevice 上创建。如果localDevice 无效，则会自动选择本地默认设备。如果localDevice 指定的本地设备不是本地蓝牙适配器，error() 将被设置为InvalidBluetoothAdapterError 。

仅 Linux 支持选择localDevice 。在其他平台上，该参数将被忽略。

此函数在 Qt 6.2 中引入。

另请参阅 QLowEnergyController::PeripheralRole 。

QLowEnergyService *QLowEnergyController::createServiceObject(const QBluetoothUuid &serviceUuid, QObject *parent = nullptr)

创建serviceUuid 所代表服务的实例。serviceUuid 参数必须是通过services() 获取的。

调用者拥有返回指针的所有权，并可通过parent 参数作为默认所有者。

如果在远程设备上找不到serviceUuid 的服务或控制器已断开连接，该函数将返回一个空指针。

该函数还可以返回辅助服务的实例。服务之间的包含关系可通过QLowEnergyService::includedServices() 表示。

如果使用相同的服务 UUID 多次调用此函数，返回的QLowEnergyService 实例将共享其内部数据。因此，如果其中一个实例启动了服务详细信息的发现，其他实例也会自动过渡到发现状态。

另请参见 services()。

void QLowEnergyController::disconnectFromDevice()

断开与远程设备的连接。

当前连接产生的任何QLowEnergyService 、QLowEnergyCharacteristic 或QLowEnergyDescriptor 实例都将自动失效。一旦这些对象中的任何一个失效，即使该控制器对象重新连接，它们也将继续失效。

如果控制器处于UnconnectedState 角色，则此函数不起任何作用。

如果控制器处于外围角色，则会停止广告并删除之前通过addService() 添加的所有服务。要重新使用QLowEnergyController 实例，应用程序必须重新添加服务，并通过调用startAdvertising() 重新启动广告模式。

另请参阅 connectToDevice()。

[signal] void QLowEnergyController::disconnected()

当控制器与远程低能耗设备断开连接或反向断开连接时，就会发出该信号。在 iOS 和 macOS 上，如果控制器在PeripheralRole 中，则此信号不可靠。在 Android 上，当最后一个连接的设备断开连接时，就会发出此信号。在 BlueZ DBus 后端，当访问属性的最后一个客户端断开连接时，控制器将被视为断开连接。

void QLowEnergyController::discoverServices()

启动服务发现进程。

发现进程通过serviceDiscovered() 信号显示。进程结束时会发出discoveryFinished() 信号。

如果控制器实例未连接或控制器已执行服务发现，则此函数不会执行任何操作。

[signal] void QLowEnergyController::discoveryFinished()

运行中的服务发现结束时会发出该信号。如果发现过程结束时出现错误，则不会发出该信号。

该信号只有在控制器处于CentralRole 时才会发出。

另请参阅 discoverServices() 和error()。

QLowEnergyController::Error QLowEnergyController::error() const

返回上次发生的错误或NoError 。

[signal, since 6.2] void QLowEnergyController::errorOccurred(QLowEnergyController::Error newError)

该信号在发生错误时发出。newError 参数描述了发生的错误。

该函数在 Qt 6.2 中引入。

另请参阅 error() 和errorString()。

QString QLowEnergyController::errorString() const

返回上次发生错误的文本表示。字符串已翻译。

QBluetoothAddress QLowEnergyController::localAddress() const

返回用于通信的本地蓝牙适配器的地址。

如果要求该类实例使用默认适配器，但在创建该类实例时没有默认适配器，则返回的QBluetoothAddress 将为空。

另请参阅 QBluetoothAddress::isNull()。

[since 6.2] int QLowEnergyController::mtu() const

返回 MTU 大小。

在连接设置期间，ATT MTU 大小是协商确定的。本方法提供协商结果。在某些情况下，它可用于优化数据包大小。单个数据包可传输的最大数据量为mtu-3字节。ATT 协议头需要 3 个字节。

在连接设置和 MTU 协商之前，将返回默认值23 。

并非每个平台都公开 MTU 值。在这些平台上（如 Linux），该函数总是返回-1 。

如果控制器位于PeripheralRole 中，则可能有多个中央设备与之相连。在这种情况下，该函数将返回最后协商的连接的 MTU。

此函数在 Qt 6.2 中引入。

[signal] void QLowEnergyController::mtuChanged(int mtu)

mtu 表示新值。

另请参阅 mtu() 。

[since 6.5] void QLowEnergyController::readRssi()

readRssi() 读取已连接远程设备的 RSSI（接收信号强度指示器）。如果读取成功，则通过rssiRead() 信号报告 RSSI。

该函数在 Qt 6.5 中引入。

另请参阅 rssiRead()、connectToDevice()、state()、createCentral() 和errorOccurred()。

QBluetoothAddress QLowEnergyController::remoteAddress() const

返回远程蓝牙低功耗设备的地址。

对于CentralRole 中的控制器，该值始终是创建控制器对象时传入的值。对于PeripheralRole 中的控制器，该值是当前连接的客户端设备地址之一。如果控制器当前不在ConnectedState 中，则此地址无效。

QLowEnergyController::RemoteAddressType QLowEnergyController::remoteAddressType() const

返回remoteAddress() 的类型。默认情况下，该值初始化为PublicAddress 。

另请参阅 setRemoteAddressType()。

QBluetoothUuid QLowEnergyController::remoteDeviceUuid() const

返回远程蓝牙低功耗设备的唯一标识符。

在 macOS/iOS/tvOS 上，CoreBluetooth 不会公开/接受低功耗蓝牙设备的硬件地址；相反，开发人员应该使用由 CoreBluetooth 生成的唯一 128 位 UUID。这些 UUIDS 将在同一中心 <-> 外围设备配对中保持不变，我们在连接远程设备时会使用它们。对于CentralRole 中的控制器，该值将始终是创建控制器对象时传入的值。对于PeripheralRole 中的控制器，该值无效。

QString QLowEnergyController::remoteName() const

如果控制器位于CentralRole 中，则返回远程蓝牙低功耗设备的名称。否则结果未指定。

void QLowEnergyController::requestConnectionUpdate(const QLowEnergyConnectionParameters &parameters)

请求控制器根据parameters 更新连接。如果请求成功，将发出带有实际新参数的connectionUpdated() 信号。有关连接参数的更多信息，请参阅QLowEnergyConnectionParameters 类。

Android 仅间接允许调整该参数集。连接参数分为三类（高优先级、低优先级和平衡优先级）。每个类别都意味着QLowEnergyConnectionParameters::minimumInterval(),QLowEnergyConnectionParameters::maximumInterval() 和QLowEnergyConnectionParameters::latency() 的一组预设值。虽然连接请求是异步操作，但 Android 并不提供说明请求结果的回调。这是一个公认的 Android Bug。由于这个错误，Android 不会发出connectionUpdated() 信号。

另请参阅 connectionUpdated().

QLowEnergyController::Role QLowEnergyController::role() const

返回此控制器对象所处的角色。

角色在使用createCentral() 或createPeripheral() 构建QLowEnergyController 实例时确定。

[signal, since 6.5] void QLowEnergyController::rssiRead(qint16 rssi)

该信号在成功读取所连接远程设备的 RSSI（接收信号强度指示器）后发出。rssi 参数代表新值。

此函数在 Qt 6.5 中引入。

另请参阅 readRssi().

[signal] void QLowEnergyController::serviceDiscovered(const QBluetoothUuid &newService)

每次发现新服务时都会发出该信号。newService 参数包含已发现服务的 UUID。

只有当控制器位于CentralRole 时才能发出该信号。

另请参阅 discoverServices() 和discoveryFinished()。

QList<QBluetoothUuid> QLowEnergyController::services() const

如果控制器在CentralRole 中，则返回远程设备提供的服务列表。否则，结果未指定。

该列表包含所有主要和次要服务。

另请参阅 createServiceObject() 。

void QLowEnergyController::setRemoteAddressType(QLowEnergyController::RemoteAddressType type)

设置远程地址type 。连接远程蓝牙低功耗设备时需要使用该类型。

只有在使用旧版 Linux 内核（v3.3 或更低版本）的 Linux/BlueZ 系统上，或未为可执行文件设置 CAP_NET_ADMIN 时，才需要设置该属性。该属性的默认值为RandomAddress 。

另请参阅 remoteAddressType()。

void QLowEnergyController::startAdvertising(const QLowEnergyAdvertisingParameters &parameters, const QLowEnergyAdvertisingData &advertisingData, const QLowEnergyAdvertisingData &scanResponseData = QLowEnergyAdvertisingData())

使用parameters 中设置的参数，开始发布advertisingData 和scanResponseData 中给出的数据。控制器必须位于PeripheralRole 中。如果parameters 表明广告应可连接，则该函数也会开始监听传入的客户端连接。

不需要提供scanResponseData ，因为它不适用于parameters 的某些配置。advertisingData 和scanResponseData 的用户数据限制为 31 字节。例如，如果在advertisingData 中添加了多个 128 位 uuids，则广告数据包可能不包含所有 uuids。现有的限制可能会导致 uuids 被截断。在这种情况下，scanResponseData ，以获取更多信息。

在 BlueZ DBus 后端，BlueZ 会决定是否以及在扫描响应中使用哪些数据。因此，建议在主advertisingData 参数中设置所有广告数据。如果同时设置了广告数据和扫描响应数据，则扫描响应数据优先。

如果该对象当前不在UnconnectedState 中，则不会发生任何操作。

另请参阅 stopAdvertising().

QLowEnergyController::ControllerState QLowEnergyController::state() const

返回控制器的当前状态。

另请参阅 stateChanged()。

[signal] void QLowEnergyController::stateChanged(QLowEnergyController::ControllerState state)

控制器状态发生变化时会发出该信号。新的state 也可通过state() 获取。

另请参阅 state() 。

void QLowEnergyController::stopAdvertising()

如果该对象当前处于广告状态，则停止广告。

控制器必须位于PeripheralRole 中，此函数才会起作用。它不会使之前通过addService() 添加的服务失效。

另请参阅 startAdvertising()。