QLowEnergyService 类

    //PreCondition: service details already discovered
    QLowEnergyCharacteristic batteryLevel = service->characteristic(
                QBluetoothUuid::CharacteristicType::BatteryLevel);
    if (!batteryLevel.isValid())
        return;

    QLowEnergyDescriptor notification = batteryLevel.descriptor(
                QBluetoothUuid::DescriptorType::ClientCharacteristicConfiguration);
    if (!notification.isValid())
        return;

    // establish hook into notifications
    connect(service, SIGNAL(characteristicChanged(QLowEnergyCharacteristic,QByteArray)),
            this, SLOT(characteristicChanged(QLowEnergyCharacteristic,QByteArray)));

    // enable notification
    service->writeDescriptor(notification, QByteArray::fromHex("0100"));

    // disable notification
    //service->writeDescriptor(notification, QByteArray::fromHex("0000"));

    // wait until descriptorWritten() signal is emitted
    // to confirm successful write

    QLowEnergyService *first, *second;
    QLowEnergyController control(remoteDevice);
    control.connectToDevice();

    // waiting for connection

    first = control.createServiceObject(QBluetoothUuid::ServiceClassUuid::BatteryService);
    second = control.createServiceObject(QBluetoothUuid::ServiceClassUuid::BatteryService);
    Q_ASSERT(first->state() == QLowEnergyService::RemoteService);
    Q_ASSERT(first->state() == second->state());

    first->discoverDetails();

    Q_ASSERT(first->state() == QLowEnergyService::RemoteServiceDiscovering);
    Q_ASSERT(first->state() == second->state());

成员函数文档

[虚拟 noexcept] QLowEnergyService::~QLowEnergyService()

销毁QLowEnergyService实例。

QLowEnergyCharacteristic QLowEnergyService::characteristic(const QBluetoothUuid &uuid) const

返回与 uuid 匹配的特性；否则返回无效的特性。

返回的特性无效，如果这个服务实例的 discoverDetails() 尚未调用，或者没有与 uuid 匹配的特性。

另请参阅 特性。

[信号] void QLowEnergyService::characteristicChanged(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue)

如果相关控制器对象处于 中心 角色，则在 characteristic 的值由于外围/设备侧的事件而更改时发出此信号。在这种情况下，信号的发出意味着必须在外围事件更改之前通过特性的 客户端特性配置 描述符激活更改通知。有关如何实现的更多详细信息，请参见 以上内容。

如果控制器处于 外围 角色，即服务对象是通过 QLowEnergyController::addService 创建的，则当 GATT 客户端使用写入请求或命令写入特性的值时发出信号。

newValue 参数包含 characteristic 的更新值。

[信号] void QLowEnergyService::characteristicRead(const QLowEnergyCharacteristic &characteristic, const QByteArray &value)

当成功地返回 characteristic 的读取请求时，会发出此信号。该信号可能是由调用 characteristicRead() 触发的。如果读取操作不成功，将发出使用 CharacteristicReadError 标志的 errorOccurred() 信号。

另请参阅 readCharacteristic。

[信号] void QLowEnergyService::characteristicWritten(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue)

当成功地更改 characteristic 的值到 newValue 时发出此信号。更改必须是通过调用 writeCharacteristic 触发的。如果写入操作不成功，则通过使用 CharacteristicWriteError 标志的 errorOccurred() 信号发出。

接收到已写入信号的接收可以视为目标设备已接收到要写入的值并报告写入请求的状态的标志。

另请参阅 writeCharacteristic。

QListQLowEnergyCharacteristic QLowEnergyService::characteristics() const

返回与此 <인스턴스> 相关联的所有属性。

如果此服务实例的 discoverDetails() 尚未调出或不存在已知的属性，则返回的列表是空的。

另请参阅characteristic()，state() 和 discoverDetails()。

bool QLowEnergyService::contains(const QLowEnergyCharacteristic &；《characteristic》）const

如果 characteristic 属于此服务，则返回 true；否则返回 false。

如果 characteristics() 包含 characteristic，则属性属于服务。

bool QLowEnergyService::contains(const QLowEnergyDescriptor &；《descriptor》）const

如果 descriptor 属于此服务，则返回 true；否则返回 false。

[信号] void QLowEnergyService::descriptorRead(const QLowEnergyDescriptor &；《descriptor》），const QByteArray &；《value》）》）

在成功返回 descriptor 的 value 时会发出此信号。信号可能由调用 descriptorRead() 触发。如果读取操作不成功，会使用 errorOccurred() 信号通过 DescriptorReadError 标志发出。

另请参阅readDescriptor()。

[信号] void QLowEnergyService::descriptorWritten(const QLowEnergyDescriptor &；《descriptor》）），const QByteArray &；《newValue》）》）

当 descriptor 的值成功更改为 newValue 时会发出此信号。如果关联的控制器对象处于 central 角色的话，更改必须是由调用 writeDescriptor() 触发的。否则，该信号是来自 GATT 客户端到相应描述符的写入请求或命令的结果。

另请参阅writeDescriptor()。

void QLowEnergyService::discoverDetails(QLowEnergyService::DiscoveryMode mode = FullDiscovery)

启动对服务包含的服务、属性及其关联描述符的发现。

发现过程通过 stateChanged() 信号表示。创建后，服务处于 DiscoveryRequired 状态。当调用 discoverDetails() 时，它将转换为 DiscoveringService。完成详细发现后，它会转换为 ServiceDiscovered 状态。在每个转换过程中，都会发射 stateChanged() 信号。根据参数 mode，会执行 FullDiscovery 或 SkipValueDiscovery。无论如何，所有服务和特征都将被发现。一个 FullDiscovery 会继续并读取所有特征值和描述符。一个 SkipValueDiscovery 不会读取特征值和描述符。一个 SkipValueDiscovery 有两个优点。首先，它更快。其次，它可以绕过一些设备中的错误，这些设备错误地声明某些特征或描述符为可读，但仍然不允许它们的读取。这可能会触发不可预测的行为。在进行 SkipValueDiscovery 之后，必须调用 readCharacteristic() / readDescriptor()，并等待它们成功完成，然后再访问特征或描述符的值。

参数 mode 是从 Qt 6.2 中引入的。

另请参阅 state()。

QLowEnergyService::ServiceError QLowEnergyService::error() const

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

[信号，自 6.2 版起] void QLowEnergyService::errorOccurred(QLowEnergyService::ServiceError newError)

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

此函数是从 Qt 6.2 版本开始引入的。

QList<QBluetoothUuid> QLowEnergyService::includedServices() const

返回当前服务包含的所有服务的 UUID。

如果此服务实例的 discoverDetails() 尚未调出或不存在已知的属性，则返回的列表是空的。

一个包含的服务可能还包含另一个服务。这些二级包含必须通过它们相关的一级 QLowEnergyService 实例来获取。技术上，这可能会创建循环依赖。

应使用 QLowEnergyController::createServiceObject() 来获取每个 UUID 的服务实例。

另请参阅 createServiceObject。

void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

读取 characteristic 的值。如果操作成功，则发射 characteristicRead() 信号；否则设置 CharacteristicReadError。一般来说，如果其 QLowEnergyCharacteristic::Read 属性被设置，则一个 characteristic 是可读的。

所有针对同一远程设备的描述符和特征请求都是序列化的。在同时发出多个请求时，会使用队列。队列不会消除重复的读取特征请求。

如果服务处于ServiceDiscovered状态且属于该服务，则可以读取特征。如果这些条件中的任何一个不真实，则设置QLowEnergyService::OperationError。

另请参阅characteristicRead() 和 writeCharacteristic。

void QLowEnergyService::readDescriptor(const QLowEnergyDescriptor &descriptor)

读取descriptor的值。如果操作成功，则发出descriptorRead()信号；否则设置DescriptorReadError。

所有针对同一远程设备的描述符和特征请求都是序列化的。在同时发出多个请求时，会使用队列。队列不会消除重复的读取描述符请求。

只有当服务处于ServiceDiscovered状态且描述符属于该服务时，才能读取描述符。如果这些条件中的任何一个不真实，则设置QLowEnergyService::OperationError。

另请参阅descriptorRead() 和 writeDescriptor。

QString QLowEnergyService::serviceName() const

返回服务名称；否则返回空字符串。

返回的名称只能在serviceUuid()是标准的UUID时检索。

QBluetoothUuid QLowEnergyService::serviceUuid() const

返回服务的UUID；否则返回null UUID。

QLowEnergyService::ServiceState QLowEnergyService::state() const

返回服务的当前状态。

如果设备的服务是第一次实例化，则对象的当前状态是DiscoveryRequired。所有指向外围设备上同一服务的服务对象的当前状态始终相等。这是因为内部对象数据共享的性质导致的。因此，任何在第一个实例之后创建的服务对象实例的状态都将与已有实例的状态相同。

如果QLowEnergyController从远程设备断开连接，服务将无效。无效的服务保留断开事件时的内部状态。这意味着一旦发现服务详情，甚至可以从无效的服务中检索出来。这允许在设备建立连接、检索服务详情后，设备立即断开连接，以允许下一个设备连接到外围设备。

然而，在正常情况下，连接应该保持，以避免重复发现服务和它们的详细信息。发现可能需要一段时间，客户端可以订阅持续的更改通知。

参见：stateChanged()。

[信号] void QLowEnergyService::stateChanged(QLowEnergyService::ServiceState newState)

当服务状态改变时，会发出此信号。可以通过 state() 函数获取 newState。

另请参阅 state()。

QLowEnergyService::ServiceTypes QLowEnergyService::type() const

返回服务的类型。

void QLowEnergyService::writeCharacteristic(const QLowEnergyCharacteristic &characteristic, const QByteArray &newValue, QLowEnergyService::WriteMode mode = WriteWithResponse)

将 newValue 作为 characteristic 的值写入。确切的语义取决于关联控制器对象的当前角色。

中心角色

此调用会产生向远程外围设备发送的写入请求或命令。如果操作成功，会发出 characteristicWritten() 信号；否则会设置 CharacteristicWriteError。调用此函数不会触发 characteristicChanged() 信号，除非外围设备在当前写入请求后再次更改值。

mode 参数确定远程设备是否应该发送写入确认。即将写入的 characteristic 必须支持相关写入模式。特性支持的写入模式由其 QLowEnergyCharacteristic::Write 和 QLowEnergyCharacteristic::WriteNoResponse 属性指示。

对同一远程设备的所有描述符和特性写入请求都是序列化的。在同时发出多个写入请求时，会使用队列。队列不会消除针对同一特性的重复写入请求。例如，如果相同描述符先设置为值 A，然后立即设置为值 B，则两个写入请求会按顺序执行。

只有当此服务处于 ServiceDiscovered 状态且属于该服务时，才可以写入特性。如果这些条件中有一个不成立，则设置 QLowEnergyService::OperationError。

外围角色

此调用会导致特性值在本地数据库中更新。

如果一个客户端当前已连接并且启用了对特征的通告或指示，则将发送相应信息。如果一个设备已启用了对特征的通告或指示，但该设备当前未连接，但与本地设备之间存在配对关系，则通告或指示将在下次重新连接时发送。

如果对特征值的长度有约束，且新值 newValue 不符合该约束，则行为将未定义。

另请参阅QLowEnergyService::characteristicWritten() 和 QLowEnergyService::readCharacteristic。

void QLowEnergyService::writeDescriptor(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue)

将 newValue 写为 descriptor 的值。确切语意取决于相关控制器对象所扮演的角色。

中心角色

调用此函数将导致向远程设备发出写请求。如果操作成功，则发出 descriptorWritten() 信号；否则发出 DescriptorWriteError 信号。

对同一远程设备的所有描述符和特性请求都是串行的。在同时发出多个写请求时使用队列。队列不会消除对同一描述符重复的写请求。例如，如果相同的描述符首先设置为值 A，然后立即设置为 B，则两个写请求将按给定顺序执行。

只有在服务处于 ServiceDiscovered 状态、属于该服务的情况下，才可以写入描述符。如果这些条件之一不成立，则设置 QLowEnergyService::OperationError。

外围角色

将值写入本地服务数据库。如果 newValue 的内容对于 descriptor 无效，则行为将是未定义的。

另请参阅descriptorWritten() 和 readDescriptor。