QLowEnergyController Class

成员函数文档

[virtual noexcept] QLowEnergyController::~QLowEnergyController()

销毁该QLowEnergyController 实例。

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

根据service 中的parent 信息，构建并返回一个QLowEnergyService 对象。控制器必须位于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 。

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

该函数在 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 ` 将为 `null`。

另请参阅 QBluetoothAddress::isNull()。

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

返回 MTU 大小。

在建立连接期间，会协商ATT的MTU大小。此方法提供该协商的结果。在某些情况下，可利用该结果优化数据包大小。单个数据包中可传输的最大数据量为mtu减去3字节。其中3字节用于ATT协议头。

在建立连接和进行 MTU 协商之前，该函数将返回默认值23 。

并非所有平台都会公开 MTU 值。在这些平台（例如 Linux）上，该函数始终返回-1 。

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

该函数于 Qt 6.2 中引入。

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

该信号是在 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 不公开也不接受 LE 设备的硬件地址；相反，开发者应使用由 CoreBluetooth 生成的唯一 128 位 UUID。对于同一中央设备 <-> 外围设备对，这些 UUID 将保持不变，我们在连接远程设备时会使用它们。 对于位于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 漏洞。由于此漏洞，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())

开始广播advertisingData 和scanResponseData 中给出的数据，并使用parameters 中设置的参数。控制器必须位于PeripheralRole 中。如果parameters 指定该广播应处于可连接状态，则此函数还会开始监听传入的客户端连接。

无需提供scanResponseData ，因为它不适用于parameters 的某些配置。advertisingData 和scanResponseData 的用户数据长度限制为 31 字节。例如，如果向advertisingData 中添加了多个 128 位 UUID，则广播数据包可能无法包含所有 UUID。 现有限制可能导致 UUID 被截断。在这种情况下，可使用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()。