Класс QLowEnergyService

Класс QLowEnergyService представляет отдельный сервис на устройстве Bluetooth Low Energy. Подробнее...

• Список всех членов, включая унаследованные

Открытые типы

Открытые функции

Сигналы

Подробное описание

QLowEnergyService предоставляет доступ к данным о Bluetooth Low Energy-сервисах. Класс упрощает обнаружение и публикацию данных о сервисах, позволяет читать и записывать содержащиеся данные и оповещает об изменениях данных.

Структура сервиса

Устройство периферийного Bluetooth Low Energy может содержать несколько служб. В свою очередь, каждая служба может включать дополнительные службы. Этот класс представляет собой отдельную службу устройства периферии и создается с помощью QLowEnergyController::createServiceObject(). Свойство type() указывает, является ли эта служба основной (верхнего уровня) или частью другой службы. Каждая служба может содержать одну или несколько характеристик, а каждая характеристика может содержать описатели. Результирующая структура может выглядеть следующим образом:

Характеристика является основным носителем информации. Она имеет свойство value() и properties(), описывающие разрешения доступа к значению. Основное назначение содержащегося описателя — более детальное определение характера характеристики. Например, он может указать, как должно интерпретироваться значение или может ли он уведомлять потребителя значения об изменениях значения.

Взаимодействие со службой

После первоначального создания объекта службы его детали еще предстоит обнаружить. Это указывается текущим состоянием state(), которое равно DiscoveryRequired. Возможно только получение serviceUuid() и serviceName().

Обнаружение включенных служб, характеристик и описателей запускается при вызове discoverDetails(). Во время обнаружения состояние state() переходит от DiscoveryRequired через DiscoveringService к конечному состоянию ServiceDiscovered. Этот переход объявляется через сигнал stateChanged(). После того, как детали известны, все содержащиеся характеристики, описатели и включенные службы известны и могут быть прочитаны или записаны.

Значения характеристик и описателей можно получить с помощью QLowEnergyCharacteristic и QLowEnergyDescriptor соответственно. Однако для прямого чтения или записи этих атрибутов требуется объект службы. Функция readCharacteristic() пытается повторно прочитать значение характеристики. Хотя при первоначальном обнаружении службы значение могло быть уже получено, этот вызов может потребоваться в случаях, когда значение характеристики постоянно изменяется, не предоставляя никаких уведомлений. Примером может служить характеристика времени, которая предоставляет непрерывное значение. Если попытка чтения была успешной, излучается сигнал characteristicRead(). Неудача при чтении значения вызывает CharacteristicReadError. Функция writeCharacteristic() пытается записать новое значение в заданную характеристику. Если попытка записи была успешной, излучается сигнал characteristicWritten(). Неудача при записи вызывает CharacteristicWriteError. Чтение и запись описателей следуют той же схеме.

Делаются все возможные попытки прочитать или записать значение описателя или характеристики на оборудовании. Это означает, что метаинформация, такая как QLowEnergyCharacteristic::properties(), обычно игнорируется при чтении и записи. Например, можно вызвать writeCharacteristic() , несмотря на то, что характеристика является только для чтения на основе её метаданных. Результирующий запрос записи передается подключенному устройству, и от устройства зависит, как оно отреагирует на потенциально некорректный запрос. В этом случае результатом является излучение CharacteristicWriteError в ответ на возвращённую ошибку устройства. Это поведение упрощает взаимодействие с устройствами, которые сообщают неправильную метаинформацию. Если запрос невозможно переслать удалённому устройству, устанавливается OperationError. Возможной причиной может быть то, что объект характеристики, подлежащий записи, даже не принадлежит текущей службе. Вкратце, эти два типа ошибок позволяют быстро отличить ошибки на локальном и на удалённом уровне.

Все запросы сериализуются в соответствии с принципом «первым пришёл, первым обслужен». Например, выдача второго запроса на запись до завершения предыдущего запроса задерживается до завершения первого запроса на запись.

В некоторых случаях периферийное устройство генерирует обновления значений, которые центральное устройство заинтересовано в получении. Для того, чтобы характеристика поддерживала такие уведомления, она должна иметь свойство QLowEnergyCharacteristic::Notify или QLowEnergyCharacteristic::Indicate и описатель типа QBluetoothUuid::DescriptorType::ClientCharacteristicConfiguration. При выполнении этих условий уведомления можно включить, как показано в следующем фрагменте кода:

    //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

Пример демонстрирует характеристику уровня заряда батареи, которая обновляет центральное устройство при каждом изменении значения. Уведомления предоставляются через сигнал characteristicChanged(). Более подробные сведения об этом механизме приведены в Спецификации Bluetooth.

Обмен данными службы

Каждый экземпляр QLowEnergyService обменивается своими внутренними состояниями и информацией с другими экземплярами QLowEnergyService той же службы. Если один экземпляр инициирует обнаружение деталей службы, все остальные экземпляры автоматически следуют за ним. Поэтому следующий фрагмент всегда работает:

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

Другие операции, такие как вызовы readCharacteristic(), readDescriptor(), writeCharacteristic(), writeDescriptor() или аннулирование службы из-за отключения связанного QLowEnergyController от устройства, разделяются таким же образом.

См. также QLowEnergyController, QLowEnergyCharacteristic и QLowEnergyDescriptor.

Документация по типам членов

[since 6.2] Перечисление QLowEnergyService::DiscoveryMode

Это перечисление содержит режимы обнаружения служб. Все режимы обнаруживают характеристики службы и описатели характеристик. Режимы различаются по тому, считываются ли значения характеристик и описатели.

Это перечисление было добавлено или изменено в Qt 6.2.

См. также discoverDetails().

Перечисление QLowEnergyService::ServiceError

Это перечисление описывает все возможные условия ошибки во время существования службы. Функция error() возвращает последнюю возникшую ошибку.

перечисление QLowEnergyService::ServiceState

Это перечисление описывает состояние() объекта службы.

перечисление QLowEnergyService::ServiceTypeфлаги QLowEnergyService::ServiceTypes

Это перечисление описывает тип службы.

Тип ServiceTypes является typedef для QFlags<ServiceType>. Он хранит логическое ИЛИ комбинацию значений ServiceType.

enum QLowEnergyService::WriteMode

Этот перечисление описывает режим, который следует использовать при записи значения характеристики. Характеристика рекламирует свои поддерживаемые режимы записи через свои свойства.

Документация функций-членов

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

Если связанный объект контроллера находится в роли центрального устройства, этот сигнал генерируется, когда значение characteristic изменяется событием со стороны периферийного устройства/устройства. В этом случае выдача сигнала подразумевает, что уведомления о изменениях должны быть активированы через дескриптор ClientCharacteristicConfiguration характеристики до события изменения на периферийном устройстве. Более подробную информацию о том, как это можно сделать, можно найти выше.

Если контроллер находится в роли периферийного устройства, то есть объект сервиса был создан с помощью QLowEnergyController::addService, сигнал генерируется, когда клиент GATT записал значение характеристики с помощью запроса или команды записи.

Параметр newValue содержит обновлённое значение characteristic.

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

Этот сигнал генерируется, когда запрос на чтение для characteristic успешно вернул его value. Сигнал может быть вызван при вызове characteristicRead(). Если операция чтения не выполняется успешно, вызывается сигнал error() с флагом CharacteristicReadError.

Эта функция была добавлена в Qt 5.5.

См. также readCharacteristic().

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

Этот сигнал испускается, когда значение characteristic успешно изменено на newValue. Изменение должно было быть вызвано вызовом writeCharacteristic(). Если операция записи не удалась, испускается сигнал error() с флагом CharacteristicWriteError.

Приём сигнала о записи можно рассматривать как признак того, что целевое устройство получило значение для записи и сообщило о статусе запроса на запись.

См. также writeCharacteristic().

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

Этот сигнал испускается, когда запрос на чтение для descriptor успешно вернул его value. Сигнал может быть вызван вызовом descriptorRead(). Если операция чтения не удалась, испускается сигнал error() с флагом DescriptorReadError.

Эта функция была добавлена в Qt 5.5.

См. также readDescriptor().

[signal] void QLowEnergyService::descriptorWritten(const QLowEnergyDescriptor &descriptor, const QByteArray &newValue)

Этот сигнал испускается, когда значение descriptor успешно изменено на newValue. Если связанный объект контроллера находится в роли центрального, изменение должно быть вызвано вызовом writeDescriptor(). В противном случае сигнал является результатом запроса или команды записи от клиента GATT на соответствующий дескриптор.

См. также writeDescriptor().

[signal, since 6.2] void QLowEnergyService::errorOccurred(QLowEnergyService::ServiceError newError)

Этот сигнал испускается, когда произошла ошибка. Параметр newError описывает произошедшую ошибку.

Эта функция была добавлена в Qt 6.2.

[signal] void QLowEnergyService::stateChanged(QLowEnergyService::ServiceState newState)

Этот сигнал испускается, когда состояние сервиса изменяется. newState также можно получить через state().

См. также state().

[virtual] QLowEnergyService::~QLowEnergyService()

Уничтожает экземпляр QLowEnergyService.

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

Возвращает соответствующую характеристику для uuid; в противном случае недействительную характеристику.

Возвращаемая характеристика недействительна, если для этого экземпляра сервиса еще не был вызван discoverDetails() или нет характеристик с соответствующим uuid.

См. также characteristics().

QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const

Возвращает все характеристики, связанные с этим экземпляром сервиса.

Возвращаемый список пуст, если для этого экземпляра сервиса еще не был вызван discoverDetails() или известные характеристики отсутствуют.

См. также characteristic(), state() и discoverDetails().

bool QLowEnergyService::contains(const QLowEnergyCharacteristic &characteristic) const

Возвращает true если characteristic принадлежит данному сервису; в противном случае false.

Характеристика принадлежит сервису, если characteristics() содержит данную characteristic.

bool QLowEnergyService::contains(const QLowEnergyDescriptor &descriptor) const

Возвращает true если descriptor принадлежит данному сервису; в противном случае false.

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.

QList<QBluetoothUuid> QLowEnergyService::includedServices() const

Возвращает UUID всех сервисов, включенных в текущий сервис.

Возвращаемый список пуст, если для данного экземпляра сервиса еще не был вызван discoverDetails() или если известные характеристики отсутствуют.

Возможен случай, когда включенный сервис содержит еще один сервис. Такие вложенные сервисы необходимо получать через соответствующий экземпляр QLowEnergyService первого уровня. Технически, это может создать циклическую зависимость.

QLowEnergyController::createServiceObject() следует использовать для получения экземпляров сервисов для каждого из UUID.

См. также createServiceObject().

[since 5.5] void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

Считывает значение characteristic. В случае успеха, генерируется сигнал characteristicRead(); в противном случае устанавливается CharacteristicReadError. Как правило, characteristic читается, если свойство QLowEnergyCharacteristic::Read установлено.

Все запросы к дескрипторам и характеристикам к одному удалённому устройству сериализуются. Используется очередь при одновременном отправлении нескольких запросов. Очередь не устраняет дублирующие запросы чтения для одной и той же характеристики.

Характеристика может быть считана только если сервис находится в состоянии ServiceDiscovered и принадлежит сервису. Если одно из этих условий не выполняется, устанавливается QLowEnergyService::OperationError.

Данная функция была добавлена в Qt 5.5.

См. также characteristicRead() и writeCharacteristic().

[since 5.5] void QLowEnergyService::readDescriptor(const QLowEnergyDescriptor &descriptor)

Читает значение descriptor. Если операция выполнена успешно, испускается сигнал descriptorRead(); в противном случае устанавливается DescriptorReadError.

Все запросы к описателям и характеристикам для одного и того же удалённого устройства сериализуются. При одновременном выполнении нескольких запросов используется очередь. Очередь не исключает дублирования запросов чтения для одного и того же описателя.

Описатель может быть прочитан только в том случае, если служба находится в состоянии ServiceDiscovered, и описатель принадлежит этой службе. Если одно из этих условий не выполняется, устанавливается QLowEnergyService::OperationError.

Данная функция была добавлена в Qt 5.5.

См. также descriptorRead() и writeDescriptor().

QString QLowEnergyService::serviceName() const

Возвращает имя службы; в противном случае пустую строку.

Возвращаемое имя может быть получено только если serviceUuid() является известным UUID.

QBluetoothUuid QLowEnergyService::serviceUuid() const

Возвращает UUID службы; в противном случае нулевой UUID.

QLowEnergyService::ServiceState QLowEnergyService::state() const

Возвращает текущее состояние службы.

Если служба устройства была создана впервые, состояние объекта равно DiscoveryRequired. Состояние всех объектов службы, указывающих на одну и ту же службу на периферийном устройстве, всегда одинаково. Это обусловлено общим характером данных внутреннего объекта. Поэтому любой экземпляр объекта службы, созданный после первого, имеет состояние, равное уже существующим экземплярам.

Служба становится недоступной, если QLowEnergyController отключается от удалённого устройства. Недоступная служба сохраняет своё внутреннее состояние на момент события отключения. Это означает, что после того, как сведения о службе обнаружены, их можно получить даже из недоступной службы. Это позволяет сценарии, где соединение с устройством установлено, сведения о службе получены, и устройство немедленно отключено, чтобы позволить подключение следующего устройства к периферийному устройству.

Однако в обычных ситуациях соединение должно сохраняться, чтобы избежать многократного обнаружения служб и их данных. Обнаружение может занять некоторое время, и клиент может подписаться на уведомления о текущих изменениях.

См. также stateChanged().

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().