Класс QLowEnergyController

Класс QLowEnergyController предоставляет доступ к устройствам Bluetooth Low Energy. Подробнее...

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

Типы публичного доступа

Функции публичного доступа

• 32 public functions inherited from QObject

Сигналы

• 2 signals inherited from QObject

Статические члены публичного доступа

• 11 static public members inherited from QObject

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

• 1 свойство, унаследованное от QObject
• 1 public slot, унаследованный от QObject
• 9 protected functions inherited from QObject

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

Класс QLowEnergyController предоставляет доступ к устройствам Bluetooth Low Energy.

QLowEnergyController служит точкой входа для разработки приложений Bluetooth Low Energy.

Bluetooth Low Energy определяет два типа устройств: периферийное и центральное. Каждая роль выполняет разные задачи. Периферийное устройство предоставляет данные, которые используются центральными устройствами. Пример: датчик влажности, измеряющий влажность в зимнем саду. Устройство, такое как мобильный телефон, может считывать значение датчика и отображать его пользователю в более широком контексте всех датчиков в той же среде. В этом случае датчик — периферийное устройство, а мобильный телефон — центральное устройство.

Контроллер в роли центрального устройства создается с помощью фабричного метода createCentral(). Такой объект в основном служит заглушкой для удаленного периферийного устройства Low Energy, позволяя выполнять такие функции, как обнаружение сервисов и отслеживание состояния.

После создания объекта контроллера в роли центрального устройства первым шагом является установление соединения с помощью connectToDevice(). После установления соединения состояние контроллера меняется на QLowEnergyController::ConnectedState, и генерируется сигнал connected(). Важно отметить, что на некоторых платформах, таких как BlueZ на базе Linux, нельзя поддерживать два подключенных экземпляра QLowEnergyController к одному и тому же удаленному устройству. В таких случаях второй вызов connectToDevice() может завершиться неудачно. Это ограничение может быть устранено в будущем. Функция disconnectFromDevice() используется для разрыва существующего соединения.

Вторым шагом после установления соединения является обнаружение сервисов, предлагаемых удаленным периферийным устройством. Этот процесс запускается с помощью discoverServices() и завершается, как только будет сгенерирован сигнал discoveryFinished(). Обнаруженные сервисы можно перечислить с помощью services().

Последний шаг — создание объектов сервиса. Функция createServiceObject() выступает в роли фабрики для каждого объекта сервиса и ожидает UUID сервиса в качестве параметра. Вызывающий контекст должен принять на себя ответственность за возвращённый экземпляр QLowEnergyService.

Любой экземпляр QLowEnergyService, QLowEnergyCharacteristic или QLowEnergyDescriptor, созданный позже в связи с подключением этого контроллера, становится недействительным, как только контроллер отключается от удалённого устройства Bluetooth Low Energy.

Контроллер в роли периферийного устройства создаётся с помощью фабричного метода createPeripheral(). Такой объект сам выступает в качестве периферийного устройства, обеспечивая такие функции, как реклама сервисов и возможность уведомления клиентов о изменениях значений характеристик.

После создания объекта контроллера в периферийной роли первым шагом является заполнение набора GATT-сервисов, предлагаемых клиентским устройствам, с помощью вызовов addService(). После этого необходимо вызвать startAdvertising(), чтобы устройство транслировало некоторые данные и, в зависимости от типа рекламы, также принимало входящие подключения от клиентов GATT.

См. также QLowEnergyService, QLowEnergyCharacteristic, QLowEnergyDescriptor, QLowEnergyAdvertisingParameters и QLowEnergyAdvertisingData.

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

enum QLowEnergyController::ControllerState

Указывает состояние объекта контроллера.

enum QLowEnergyController::Error

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

enum QLowEnergyController::RemoteAddressType

Указывает тип адреса Bluetooth удалённого устройства.

enum QLowEnergyController::Role

Указывает роль объекта контроллера.

Примечание: Периферийная роль в настоящее время поддерживается только на Linux. Кроме того, обработка команды ATT «Подписанная запись» на стороне сервера требует BlueZ 5 и ядра версии 3.7 или новее.

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

См. также QLowEnergyController::createCentral() и QLowEnergyController::createPeripheral().

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

QLowEnergyController::~QLowEnergyController()

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

QLowEnergyService *QLowEnergyController::addService(const QLowEnergyServiceData &service, QObject *parent = nullptr)

Создаёт и возвращает объект QLowEnergyService с parent из service. Контроллер должен находиться в роли PeripheralRole и в состоянии UnconnectedState. Объект service должен быть валиден.

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

См. также QLowEnergyServiceData::addIncludedService.

void QLowEnergyController::connectToDevice()

Подключается к удалённому устройству Bluetooth Low Energy.

Эта функция ничего не делает, если состояние контроллера state() не равно UnconnectedState. Сигнал connected() генерируется, как только подключение успешно установлено.

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

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

[signal] void QLowEnergyController::connected()

Этот сигнал генерируется, когда контроллер успешно подключается к удалённому устройству Low Energy (если контроллер находится в роли CentralRole) или если к контроллеру подключается удалённое устройство Low Energy (если контроллер находится в роли PeripheralRole). В iOS и OS X этот сигнал ненадёжен, если контроллер находится в роли PeripheralRole — контроллер только предполагает, что какой-то центральный узел подключился к нашему периферийному устройству, как только этот центральный узел пытается записать/прочитать характеристику/описание.

[signal] void QLowEnergyController::connectionUpdated(const QLowEnergyConnectionParameters &newParameters)

Этот сигнал генерируется при изменении параметров подключения. Это может произойти в результате вызова requestConnectionUpdate() или по другим причинам, например, если другая сторона подключения запросила новые параметры. Новые значения можно получить из newParameters.

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

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

[static] QLowEnergyController *QLowEnergyController::createCentral(const QBluetoothDeviceInfo &remoteDevice, QObject *parent = nullptr)

Возвращает новый объект этого класса, который находится в роли CentralRole и имеет родительский объект parent. Параметр remoteDevice ссылается на устройство, к которому позже будет установлено подключение.

Контроллер использует локальный адаптер Bluetooth по умолчанию для управления подключением.

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

См. также QLowEnergyController::CentralRole.

[static] QLowEnergyController *QLowEnergyController::createPeripheral(QObject *parent = nullptr)

Возвращает новый объект этого класса, который находится в роли PeripheralRole и имеет родительский объект parent. Обычно, следующим шагом является вызов startAdvertising() для возвращённого объекта.

Контроллер использует локальный адаптер Bluetooth по умолчанию для управления подключением.

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

См. также QLowEnergyController::PeripheralRole.

QLowEnergyService *QLowEnergyController::createServiceObject(const QBluetoothUuid &serviceUuid, QObject *parent = Q_NULLPTR)

Создаёт экземпляр службы, представленной serviceUuid. Параметр serviceUuid должен быть получен с помощью services().

Вызывающий код получает владение возвращаемым указателем и может передать параметр parent в качестве владельца по умолчанию.

Функция возвращает нулевой указатель, если на удалённом устройстве или контроллер отключён не найдено никакой службы с serviceUuid.

Функция также может возвращать экземпляры вторичных служб. Взаимосвязи между службами могут быть выражены с помощью QLowEnergyService::includedServices().

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

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

void QLowEnergyController::disconnectFromDevice()

Отключается от удалённого устройства.

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

Эта функция ничего не делает, если контроллер находится в состоянии UnconnectedState.

Если контроллер находится в роли периферийного устройства, он также останавливает рекламу. Приложение должно перезапустить режим рекламы, вызвав startAdvertising().

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

[signal] void QLowEnergyController::disconnected()

Этот сигнал излучается, когда контроллер отключается от удалённого устройства Low Energy или наоборот. В iOS и OS X этот сигнал ненадежный, если контроллер находится в роли PeripheralRole.

void QLowEnergyController::discoverServices()

Инициирует процесс обнаружения служб.

Процесс обнаружения отображается через сигнал serviceDiscovered(). Сигнал discoveryFinished() излучается, когда процесс завершается.

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

Примечание: Некоторые платформы в процессе кешируют список служб устройства, которое было обнаружено в прошлом. Это может быть проблематично, если удалённое устройство изменило свой список служб или их иерархию включения. Если это поведение является проблемой, лучшим решением является временное отключение Bluetooth. Это вызывает сброс кешированных данных. В настоящее время Android демонстрирует такое поведение кеширования.

[signal] void QLowEnergyController::discoveryFinished()

Этот сигнал излучается, когда завершается запущенное обнаружение служб. Сигнал не излучается, если процесс обнаружения завершается с ошибкой.

Этот сигнал может излучаться только если контроллер находится в роли CentralRole.

См. также discoverServices() и error().

Error QLowEnergyController::error() const

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

[signal] void QLowEnergyController::error(QLowEnergyController::Error newError)

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

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

connect(lowEnergyController, QOverload<QLowEnergyController::Error>::of(&QLowEnergyController::error),
    [=](QLowEnergyController::Error newError){ /* ... */ });

См. также error() и errorString().

QString QLowEnergyController::errorString() const

Возвращает текстовое представление последней произошедшей ошибки. Строка переведена.

QBluetoothAddress QLowEnergyController::localAddress() const

Возвращает адрес локального адаптера Bluetooth, используемого для связи.

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

См. также QBluetoothAddress::isNull().

QBluetoothAddress QLowEnergyController::remoteAddress() const

Возвращает адрес удалённого устройства Bluetooth Low Energy.

Для контроллера в роли CentralRole, это значение всегда будет тем, которое было передано при создании объекта контроллера. Для контроллера в роли PeripheralRole, это значение — адрес устройства-клиента, с которым в данный момент установлено соединение. В частности, этот адрес будет недействительным, если контроллер в данный момент не находится в состоянии ConnectedState.

RemoteAddressType QLowEnergyController::remoteAddressType() const

Возвращает тип remoteAddress(). По умолчанию это значение инициализируется как PublicAddress.

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

QBluetoothUuid QLowEnergyController::remoteDeviceUuid() const

Возвращает уникальный идентификатор удалённого устройства Bluetooth Low Energy.

В macOS/iOS/tvOS CoreBluetooth не предоставляет/принимает аппаратные адреса для устройств LE; вместо этого разработчики должны использовать уникальные 128-битные UUID, сгенерированные CoreBluetooth. Эти UUID остаются постоянными для одной и той же пары центрального и периферийного устройства, и мы используем их при подключении к удалённому устройству. Для контроллера в роли CentralRole, это значение всегда будет тем, которое было передано при создании объекта контроллера. Для контроллера в роли PeripheralRole, это значение недействительно.

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

QString QLowEnergyController::remoteName() const

Возвращает имя удалённого устройства Bluetooth Low Energy, если контроллер находится в роли CentralRole. В противном случае результат не определён.

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

void QLowEnergyController::requestConnectionUpdate(const QLowEnergyConnectionParameters &parameters)

Запрашивает у контроллера обновление соединения в соответствии с parameters. Если запрос успешен, сигнал connectionUpdated() будет излучен с фактическими новыми параметрами. См. класс QLowEnergyConnectionParameters для получения дополнительной информации о параметрах соединения.

Android только косвенно позволяет настроить этот набор параметров. Параметры подключения разделены на три категории (высокий, низкий и сбалансированный приоритет). Каждая категория подразумевает предварительно сконфигурированный набор значений для QLowEnergyConnectionParameters::minimumInterval(), QLowEnergyConnectionParameters::maximumInterval() и QLowEnergyConnectionParameters::latency(). Хотя запрос на подключение является асинхронной операцией, Android не предоставляет обратный вызов, сообщая о результате запроса. Это известный баг Android. Из-за этого бага Android не излучает сигнал connectionUpdated().

Примечание: В настоящее время эта функциональность реализована только в Linux и Android.

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

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

Роль QLowEnergyController::role() const

Возвращает роль, в которой находится этот объект контроллера.

Роль определяется при создании экземпляра QLowEnergyController с помощью createCentral() или createPeripheral().

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

[signal] void QLowEnergyController::serviceDiscovered(const QBluetoothUuid &newService)

Этот сигнал излучается каждый раз, когда обнаруживается новый сервис. Параметр newService содержит UUID найденного сервиса.

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

См. также discoverServices() и discoveryFinished().

QList<QBluetoothUuid> QLowEnergyController::services() const

Возвращает список сервисов, предлагаемых удаленным устройством, если контроллер находится в CentralRole. В противном случае результат не определен.

Список содержит все первичные и вторичные сервисы.

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

void QLowEnergyController::setRemoteAddressType(RemoteAddressType type)

Устанавливает тип удачного адреса type. Тип необходим для подключения к удаленному устройству Bluetooth Low Energy.

Этот атрибут требуется устанавливать только в системах Linux/BlueZ с более старыми ядрами Linux (версия 3.3 или ниже), или если для исполняемого файла не задан CAP_NET_ADMIN. Значение по умолчанию для атрибута — RandomAddress.

Примечание: Все остальные платформы обрабатывают этот флаг прозрачно, поэтому приложения могут полностью его игнорировать. В Linux флаг типа адреса не отображается напрямую BlueZ, хотя в некоторых случаях эта информация требуется. Единственный способ определить флаг — через API управления Bluetooth ядра Linux (требуется версия ядра 3.4 и выше). Однако для этого API необходимы разрешения CAP_NET_ADMIN. Если у локального процесса QtBluetooth установлено это разрешение, QtBluetooth будет использовать API. Предполагается, что QBluetoothDeviceDiscoveryAgent был использован до вызова QLowEnergyController::connectToDevice().

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

void QLowEnergyController::startAdvertising(const QLowEnergyAdvertisingParameters &parameters, const QLowEnergyAdvertisingData &advertisingData, const QLowEnergyAdvertisingData &scanResponseData = QLowEnergyAdvertisingData())

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

Предоставление scanResponseData не требуется, так как оно неприменимо для определенных конфигураций parameters. advertisingData и scanResponseData ограничены 31 байтом пользовательских данных. Если, например, к advertisingData добавлены несколько 128-битных UUID, рекламируемые пакеты могут не содержать все UUID. Существующее ограничение может привести к усечению UUID. В таких случаях scanResponseData может использоваться для дополнительной информации.

Если этот объект в настоящее время не находится в UnconnectedState, ничего не происходит.

Примечание: Реклама автоматически остановится, как только клиент подключится к локальному устройству.

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

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

Состояние QLowEnergyController::state() const

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

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

[signal] void QLowEnergyController::stateChanged(QLowEnergyController::ControllerState state)

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

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

void QLowEnergyController::stopAdvertising()

Останавливает рекламу, если этот объект в настоящее время находится в состоянии рекламы.

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

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