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 XML 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)

该信号在服务状态发生变化时发出。newState 也可通过state() 获取。

另请参阅 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()。