Класс QLowEnergyController

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

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

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

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

Сигналы

Статические открытые члены

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

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

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

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

После создания объекта контроллера в роли центрального устройства первым шагом является установление соединения с помощью connectToDevice(). После того как соединение будет установлено, состояние контроллера state() изменится на 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.

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

перечисление QLowEnergyController::ControllerState

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

перечисление QLowEnergyController::Error

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

перечисление QLowEnergyController::RemoteAddressType

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

[since 5.7] перечисление QLowEnergyController::Role

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

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

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

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

[signal] void QLowEnergyController::connected()

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

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

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

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

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

[signal] void QLowEnergyController::disconnected()

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

[signal] void QLowEnergyController::discoveryFinished()

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

Сигнал может быть испущен только если контроллер находится в роли CentralRole.

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

[signal, since 6.2] void QLowEnergyController::errorOccurred(QLowEnergyController::Error newError)

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

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

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

[signal] void QLowEnergyController::mtuChanged(int mtu)

Этот сигнал испускается в результате успешного изменения MTU. mtu представляет новое значение.

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

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

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

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

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

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

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

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

[virtual] QLowEnergyController::~QLowEnergyController()

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

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

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

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

См. также stopAdvertising(), disconnectFromDevice() и QLowEnergyServiceData::addIncludedService.

void QLowEnergyController::connectToDevice()

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

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

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

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

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

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

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

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

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

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

Возвращает новый экземпляр этого класса с parent.

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

Подключение устанавливается через localDevice. Если localDevice некорректен, автоматически выбирается локальное стандартное устройство. Если localDevice указывает на локальное устройство, которое не является локальным адаптером Bluetooth, error() устанавливается в InvalidBluetoothAdapterError после вызова connectToDevice().

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

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

[static, since 6.2] QLowEnergyController *QLowEnergyController::createPeripheral(const QBluetoothAddress &localDevice, QObject *parent = nullptr)

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

Периферийное устройство создаётся на localDevice. Если localDevice некорректен, автоматически выбирается локальное стандартное устройство. Если localDevice указывает на локальное устройство, которое не является локальным адаптером Bluetooth, error() устанавливается в InvalidBluetoothAdapterError.

Выбор localDevice поддерживается только в Linux. На других платформах параметр игнорируется.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void QLowEnergyController::disconnectFromDevice()

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

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

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

Если контроллер находится в роли периферийного устройства, он прекращает рекламу и удаляет все сервисы, которые были ранее добавлены с помощью addService(). Для повторного использования экземпляра QLowEnergyController приложение должно повторно добавить сервисы и перезапустить режим рекламы, вызвав startAdvertising().

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

void QLowEnergyController::discoverServices()

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

Процесс обнаружения отображается с помощью сигнала serviceDiscovered(). Сигнал discoveryFinished() генерируется по завершении процесса.

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

QLowEnergyController::Error QLowEnergyController::error() const

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

QString QLowEnergyController::errorString() const

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

QBluetoothAddress QLowEnergyController::localAddress() const

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

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

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

int QLowEnergyController::mtu() const

Возвращает размер MTU.

Во время настройки соединения размер MTU ATT согласовывается. Этот метод предоставляет результат этого согласования. Его можно использовать для оптимизации размеров пакетов в некоторых ситуациях. Максимальный объём данных, который может быть передан в одном пакете, составляет mtu-3 байта. 3 байта требуются для заголовка протокола ATT.

Перед настройкой соединения и согласованием MTU будет возвращено значение по умолчанию 23.

Не все платформы предоставляют значение MTU. На платформах (например, Linux) эта функция всегда возвращает -1.

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

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

QBluetoothAddress QLowEnergyController::remoteAddress() const

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

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

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

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

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

QLowEnergyController::Role QLowEnergyController::role() const

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

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

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

QList<QBluetoothUuid> QLowEnergyController::services() const

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

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

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

void QLowEnergyController::setRemoteAddressType(QLowEnergyController::RemoteAddressType type)

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

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

См. также 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::ControllerState QLowEnergyController::state() const

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

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

[since 5.7] void QLowEnergyController::stopAdvertising()

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

Для работы этой функции контроллер должен быть в роли PeripheralRole. Она не делает недействительными сервисы, которые были ранее добавлены с помощью addService().

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

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