QLowEnergyController 类

成员函数文档

[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外围后端，远程设备在第一次读取/写入特征或描述符时被认为已连接。

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

此信号在连接参数更改时发出。这可能是因为调用requestConnectionUpdate()或其他原因，例如，因为连接的另一端请求了新的参数。可以从newParameters获取新值。

另请参阅 requestConnectionUpdate。

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

返回一个新对象，该对象具有CentralRole并且具有父对象parent。remoteDevice指的是稍后将要建立连接的设备。

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

另请参阅 QLowEnergyController::CentralRole。

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

返回具有parent的新实例。

remoteDevice必须包含要将对象稍后试图连接的远程蓝牙低功耗设备的地址。

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

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

[静态，自6.2以来] QLowEnergyController *QLowEnergyController::createPeripheral(const QBluetoothAddress &localDevice, QObject *parent = nullptr)

返回一个新的对象，该对象属于 PeripheralRole，并具有父对象 parent 和使用 localDevice。通常，后续步骤是添加一些服务，最后在返回的对象上调用 startAdvertising()。

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

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

此功能是在 Qt 6.2 中引入的。

另请参阅 QLowEnergyController::PeripheralRole。

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

返回一个新的对象，该对象属于 PeripheralRole 并具有父对象 parent。通常，后续步骤是添加一些服务，最后在返回的对象上调用 startAdvertising()。

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

另请参阅 QLowEnergyController::PeripheralRole。

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

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

调用者拥有返回的指针，并且可以传递一个 parent 参数作为默认所有者。

如果没有在远程设备上找到具有 serviceUuid 的服务或控制器已断开连接，则此函数返回空指针。

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

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

另请参阅 services。

void QLowEnergyController::disconnectFromDevice()

断开与远程设备的连接。

由当前连接产生的任何 QLowEnergyService、QLowEnergyCharacteristic 或 QLowEnergyDescriptor 实例都将自动无效。一旦这些对象变得无效，即使此控制器对象重新连接，它们也保持无效。

如果控制器处于 UnconnectedState，则此函数不执行任何操作。

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

也请参见connectToDevice。

[信号] void QLowEnergyController::disconnected()

此信号在控制器从远程低功耗设备或反之断开连接时发出。在iOS和macOS上，如果控制器处于PeripheralRole，则该信号不可靠。在Android上，最后一个已连接的设备断开连接时发出信号。在BlueZ DBus后端，当最后一个访问属性的客户端断开连接时，认为控制器已断开连接。

void QLowEnergyController::discoverServices()

开始服务发现过程。

通过serviceDiscovered()信号指示发现进度。当过程完成时发出discoveryFinished()信号。

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

[信号] void QLowEnergyController::discoveryFinished()

此信号在运行的服务发现完成后发出。如果发现过程因错误而完成，则不会发出此信号。

此信号只能在控制器处于CentralRole时发出。

也请参见discoverServices()和error。

QLowEnergyController::Error QLowEnergyController::error() const

返回最后发生的错误或NoError。

[信号，自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实例时确定。

[信号，自6.5以来] void QLowEnergyController::rssiRead(qint16 rssi)

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

此函数是在Qt 6.5中引入的。

另请参阅readRssi。

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

每当找到新的服务时，都会发出此信号。参数newService包含了所查找到的服务的UUID。

只有当控制器处于中心角色时，该信号才能被发出。

另请参阅discoverServices() 和 discoveryFinished。

QList<QBluetoothUuid> QLowEnergyController::services() const

返回远程设备提供的服务列表，如果控制器处于中心角色。否则，结果未定义。

列表包含所有主服务及其相关服务。

另请参阅createServiceObject。

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

设置远程地址类型。连接到远程蓝牙低功耗设备需要此类型。

此属性仅在Linux/BlueZ系统和较老的Linux内核（v3.3或更低）上或者如果可执行文件未设置CAP_NET_ADMIN时需要设置。默认值为RandomAddress。

另请参阅remoteAddressType。

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

使用参数parameters设置的数据在advertisingData和scanResponseData中开始广告，控制器必须处于外围角色。如果parameters指示广告应该是可连接的，则此函数也会开始监听传入的客户端连接。

提供scanResponseData不是必须的，因为对于某些parameters配置来说它不适用。 advertisingData和scanResponseData限制为最多31字节的用户数据。例如，如果在advertisingData中添加了多个128bit uuid，则广告包可能不会包含所有uuid。现有的限制可能已导致uuid的截断。在这种情况下，可以使用scanResponseData提供更多信息。

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

如果此对象当前不在形容词状态未连接状态，则不会发生任何操作。

另请参阅形容词()。

QLowEnergyController::ControllerState形容词state() const

返回控制器的当前状态。

另请参阅形容词()。

[信号] void形容词stateChanged(形容词QLowEnergyController::ControllerState形容词state)

当控制器的状态改变时，会发出此信号。也可以通过形容词()获取新的形容词state。

另请参阅形容词()。

void形容词stopAdvertising()

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

控制器必须处于形容词状态外围设备状态才能执行此功能。它不会使通过形容词()先前添加的服务失效。

另请参阅形容词()。