Класс QLowEnergyService

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

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

Публичные типы

Публичные функции

• 32 публичные функции, унаследованные от QObject

Сигналы

• 2 сигнала, унаследованные от QObject

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 1 публичный слот, унаследованный от QObject
• 11 статических публичных членов, унаследованные от QObject
• 9 защищённых функций, унаследованные от QObject

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

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

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

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

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

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

Взаимодействие с сервисом

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

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

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

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

Все запросы сериализуются на основе принципа FIFO. Например, отправка второго запроса на запись до завершения предыдущего запроса откладывается до завершения первого запроса на запись.

Примечание: В настоящее время невозможно отправлять запросы на запись с подписью или надёжные запросы на запись.

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

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

    QLowEnergyDescriptor notification = batteryLevel.descriptor(
                QBluetoothUuid::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::BatteryService);
    second = control.createServiceObject(QBluetoothUuid::BatteryService);
    Q_ASSERT(first->state() == QLowEnergyService::DiscoveryRequired);
    Q_ASSERT(first->state() == second->state());

    first->discoverDetails();

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

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

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

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

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

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

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

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

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

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

Тип ServiceTypes — это синоним для QFlags<ServiceType>. Он хранит объединение значений ServiceType с использованием оператора ИЛИ.

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

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

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

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 характеристики до события изменения на периферийном устройстве. Более подробную информацию о том, как это можно сделать, можно найти далее выше.

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

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

[signal] 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() вызывается с режимом WriteWithoutResponse, этот сигнал и error() никогда не генерируются.

Примечание: Этот сигнал генерируется только для случаев, связанных с ролью Центра.

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

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.

[signal] 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. Если связанный объект-контроллер находится в роли central, изменение должно быть вызвано вызовом writeDescriptor(). В противном случае сигнал является результатом запроса на запись от клиента GATT к соответствующему дескриптору.

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

void QLowEnergyService::discoverDetails()

Инициализирует поиск служб, характеристик и дескрипторов, содержащихся в сервисе. Процесс поиска показан с помощью сигнала stateChanged().

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

ServiceError QLowEnergyService::error() const

Возвращает последнюю произошедшую ошибку или NoError.

[signal] void QLowEnergyService::error(QLowEnergyService::ServiceError newError)

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

Примечание: Сигнал error перегружен в этом классе. Для подключения к этому сигналу с использованием синтаксиса указателя на функцию Qt предоставляет удобную вспомогательную функцию для получения указателя на функцию, как показано в этом примере:

connect(lowEnergyService, QOverload<QLowEnergyService::ServiceError>::of(&QLowEnergyService::error),
    [=](QLowEnergyService::ServiceError newError){ /* ... */ });

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.

Примечание: Вызов этой функции, несмотря на то, что QLowEnergyCharacteristic::properties() сообщает о несчитываемом свойстве, всегда пытается прочитать значение характеристики на оборудовании. Если оборудование возвращает ошибку, устанавливается CharacteristicReadError.

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

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

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

void QLowEnergyService::stateChanged(QLowEnergyService::ServiceState newState)

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

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

QLowEnergyService::ServiceTypes QLowEnergyService::type() const

Возвращает тип сервиса.

Примечание: Атрибуту типа нельзя доверять до тех пор, пока сервис не достигнет состояния ServiceDiscovered. Этот поле инициализируется со значением PrimaryService.

Примечание: В Android невозможно определить, является ли сервис первичным или вторичным. Поэтому для всех сервисов установлен флаг PrimaryService.

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

Записывает newValue в качестве значения для characteristic. Точные семантики зависят от роли ассоциированного объекта контроллера.

Роль центра

Вызов приводит к запросу или команде записи на удалённый периферийный узел. Если операция успешна, испускается сигнал characteristicWritten(), в противном случае устанавливается ошибка CharacteristicWriteError. Вызов этой функции не вызывает сигнал characteristicChanged(), если периферийный узел сам не изменит значение после текущего запроса на запись.

Параметр mode определяет, должен ли удалённый узел отправить подтверждение записи. Записываемая characteristic должна поддерживать соответствующий режим записи. Поддерживаемые режимы записи характеристики указаны в её свойствах QLowEnergyCharacteristic::Write и QLowEnergyCharacteristic::WriteNoResponse.

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

Примечание: В настоящее время невозможно использовать подписанные или надёжные записи, как определено в спецификации Bluetooth.

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

Примечание: Вызов этой функции, несмотря на то, что QLowEnergyCharacteristic::properties() сообщает о несчитываемом свойстве, всегда пытается записать в оборудование. Аналогично, WriteWithoutResponse также отправляется оборудованию, хотя характеристика может поддерживать только WriteWithResponse. Если оборудование возвращает ошибку, устанавливается CharacteristicWriteError.

Роль периферийного устройства

Вызов приводит к обновлению значения характеристики в локальной базе данных.

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

Если есть ограничения на длину значения характеристики и newValue не соответствует этому ограничению, поведение не определено.

Примечание: Аргумент mode игнорируется в режиме периферийного устройства.

См. также 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().