QLowEnergyService Class

    //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());

成员函数文档

[virtual noexcept] QLowEnergyService::~QLowEnergyService()

销毁该QLowEnergyService 实例。

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

返回与uuid 匹配的特征；否则返回一个无效的特征。

如果该服务实例尚未调用discoverDetails() 方法，或者不存在具有匹配uuid 的特征，则返回的特征无效。

另请参阅 characteristics()。

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

如果关联的控制器对象处于“central ”角色，当外设/设备侧的某个事件导致characteristic 的值发生变化时，将发出此信号。在这种情况下，信号的发出意味着在外设发生变化事件之前，必须已通过该特性的ClientCharacteristicConfiguration 描述符启用了变化通知。 有关如何实现此功能的更多详细信息，请参阅above 。

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

newValue 参数包含characteristic 的更新值。

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

当对characteristic 的读取请求成功返回其value 时，将发出此信号。该信号可能由调用characteristicRead()触发。如果读取操作未成功，则会通过CharacteristicReadError 标志发出errorOccurred()信号。

另请参阅 readCharacteristic()。

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

当characteristic 的值成功更改为newValue 时，将发出此信号。该更改必须是由调用writeCharacteristic()触发的。如果写入操作未成功，则将使用CharacteristicWriteError 标志发出errorOccurred()信号。

接收到该写入信号可视为目标设备已接收待写入值，并回报了写入请求的状态。

另请参阅 writeCharacteristic()。

QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const

返回与该QLowEnergyService 实例关联的所有特征。

如果该服务实例的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 。

[signal] void QLowEnergyService::descriptorRead(const QLowEnergyDescriptor &descriptor, const QByteArray &value)

当对descriptor 的读取请求成功返回其value 时，将发出此信号。该信号可能由调用descriptorRead()触发。如果读取操作未成功，则会通过DescriptorReadError 标志发出errorOccurred()信号。

另请参阅 readDescriptor()。

[signal] 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 。

[signal, since 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 。通常，如果characteristic 的QLowEnergyCharacteristic::Read 属性已设置，则该 可被读取。

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

只有当服务处于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；否则返回空 UUID。

QLowEnergyService::ServiceState QLowEnergyService::state() const

返回服务的当前状态。

如果设备的服务是首次实例化，则该对象的状态为DiscoveryRequired 。所有指向外设设备上同一服务的服务对象的状态始终相同。这是由于内部对象数据的共享特性所致。因此，在第一个实例之后创建的任何服务对象实例，其状态都与已存在的实例相同。

如果QLowEnergyController 与远程设备断开连接，则该服务将失效。 无效的服务会保留断开连接事件发生时的内部状态。这意味着，一旦服务详细信息被发现，即使从无效的服务中也能检索到这些信息。这允许以下场景：设备建立连接后，检索服务详细信息，随后立即断开连接，以便下一台设备连接到外围设备。

不过，在正常情况下应保持连接，以避免重复发现服务及其详细信息。发现过程可能需要一段时间，客户端可以订阅持续的变更通知。

另请参阅 stateChanged()。

[signal] 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()。