Класс QLowEnergyService

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

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

Типы

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

• 31 публичная функция, унаследованная от 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)

Этот сигнал излучается, когда значение characteristic изменяется событием на периферийном устройстве. Параметр newValue содержит обновлённое значение characteristic.

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

[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.

Поскольку этот сигнал указывает на успешную операцию записи, newValue обычно соответствует значению, переданному в вызов writeCharacteristic(). Однако, могут возникнуть случаи, когда два значения отличаются. Это может произойти, когда записанное значение используется удалённым устройством для запуска операции, и оно возвращает другое значение через запись и/или уведомления об изменениях. Такие случаи очень специфичны для целевого устройства. В любом случае, получение сигнала о записи всё ещё можно рассматривать как признак того, что целевое устройство получило значение, подлежащее записи.

Примечание: Если writeCharacteristic() вызывается с режимом WriteWithoutResponse, этот сигнал и error() никогда не излучаются.

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

QList<QLowEnergyCharacteristic> QLowEnergyService::characteristics() const

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

Возвращаемый список пуст, если для этого экземпляра службы метод 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. Изменение должно быть вызвано вызовом writeDescriptor().

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

void QLowEnergyService::discoverDetails()

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

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

ServiceError QLowEnergyService::error() const

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

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

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

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

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

QList<QBluetoothUuid> QLowEnergyService::includedServices() const

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

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

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

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

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

void QLowEnergyService::readCharacteristic(const QLowEnergyCharacteristic &characteristic)

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

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

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

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

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

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

void QLowEnergyService::readDescriptor(const QLowEnergyDescriptor &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().

[signal] 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 в качестве значения для характеристики. При успешном выполнении операции, генерируется сигнал characteristicWritten(); в противном случае устанавливается CharacteristicWriteError.

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

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

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

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

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

См. также QLowEnergyService::characteristicWritten() и QLowEnergyService::readCharacteristic().

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

Записывает newValue в качестве значения для описателя. При успешном выполнении операции, генерируется сигнал descriptorWritten(); в противном случае генерируется DescriptorWriteError.

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

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

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