D-Bus интерфейс GattCharacteristic1

Интерфейс позволяет получать информацию о GATT-характеристиках.


Шина:	системная
Служба:	`org.bluez`
Объект:	`[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY`
Интерфейс:	`org.bluez.GattCharacteristic1`

Свойства

Flags : array{string} [только для чтения]
Handle : uint16 [опционально, только для сервера]
MTU : uint16 [опционально, только для сервера]
NotifyAcquired : boolean [только для чтения, опционально]
Notifying : boolean [только для чтения, опционально]
Service : object [только для чтения]
UUID : string [только для чтения]
Value : array{byte} [только для чтения, опционально]
WriteAcquired : boolean [только для чтения, опционально]

Методы

fd, uint16 AcquireNotify(dict options) [опционально]
fd, uint16 AcquireWrite(dict options) [опционально]
Confirm() [опционально, только для сервера]
array{byte} ReadValue(dict options)
StartNotify()
StopNotify()
WriteValue(array{byte} value, dict options)

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

Интерфейс содержит методы и свойства для получения информацию о GATT-характеристиках. Для локальных служб, определённых GATT, пути к объектам должны соответствовать иерархии путей службы и свободно определяться.

Описание свойств

Flags : array{string} [только для чтения]

Определяет, как может использоваться значение характеристики. См. основную спецификацию «Table 3.5: Characteristic Properties bit field» и «Table 3.8: Characteristic Extended Properties bit field».

Флаги x-notify и x-indicate ограничивают доступ к уведомлениям и индикации, накладывая ограничения на запись в дескриптор конфигурации характеристик клиента.

Допустимые значения:

broadcast,
read,
write-without-response,
write,
notify,
indicate,
authenticated-signed-writes,
extended-properties,
reliable-write,
writable-auxiliaries,
encrypt-read,
encrypt-write,
encrypt-notify (только для сервера),
encrypt-indicate (только для сервера),
encrypt-authenticated-read,
encrypt-authenticated-write,
encrypt-authenticated-notify (только для сервера),
encrypt-authenticated-indicate (только для сервера),
secure-read (только для сервера),
secure-write (только для сервера),
secure-notify (только для сервера),
secure-indicate (только для сервера),
authorize.

Handle : uint16 [опционально, только для сервера]

Дескриптор характеристики. Когда он доступен на сервере, его попытаются использовать для выделения памяти в базе данных, что может привести к сбою. Для автоматического выделения должно использоваться значение 0x0000, что приведёт к установке выделенного дескриптора после регистрации.

MTU : uint16 [опционально, только для сервера]

Характеристика MTU. Свойство допустимо как для ReadValue(), так и для WriteValue(), но любой метод может использовать длинные процедуры, если они поддерживаются.

NotifyAcquired : boolean [только для чтения, опционально]

Истинно, если эта характеристика была получена любым клиентом, использующим AcquireNotify().

Для клиента это свойство опускается, если флаг notify не установлен.

Для сервера наличие этого свойства указывает на то, что AcquireNotify() поддерживается.

Notifying : boolean [только для чтения, опционально]

Истинно, если в данный момент включены уведомления или индикация по этой характеристике.

Service : object [только для чтения]

Путь к объекту у службы GATT, которой принадлежит характеристика.

UUID : string [только для чтения]

128-битный UUID характеристики.

Value : array{byte} [только для чтения, опционально]

Кэшированное значение характеристики. Свойство обновляется только после успешного запроса на чтение и при получении уведомления или индикации, после чего будет отправлен сигнал PropertiesChanged.

WriteAcquired : boolean [только для чтения, опционально]

Истинно, если характеристика была получена любым клиентом, использующим AcquireWrite().

Для свойств клиента не указывается, если не установлен флаг write-without-response.

Для сервера наличие свойства указывает на то, что AcquireWrite() поддерживается.

Описание методов

fd, uint16 AcquireNotify(dict options) [опционально]

Возвращает файловый дескриптор и MTU для уведомления. Поддерживаются только сокеты. Использование StartNotify будет заблокировано, что приведёт к возврату ошибки NotPermitted.

Для сервера возвращаемый MTU должен быть равен или меньше согласованного MTU.

Работает только с характеристиками, у которых определено свойство NotifyAcquired, которое зависит от флага уведомления, и ни один другой клиент не вызвал StartNotify.

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

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

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

Возможные ключи:

device: объект устройства (только для сервера)
mtu: изменённый MTU (только для сервера)
link: тип ссылки (только для сервера)

Возможные ошибки:

org.bluez.Error.Failed,
org.bluez.Error.NotSupported.

fd, uint16 AcquireWrite(dict options) [опционально]

Возвращает файловый дескриптор и MTU для записи. Поддерживаются только сокеты. Использование WriteValue будет заблокировано, что приведёт к возврату ошибки NotPermitted.

Для сервера возвращаемый MTU должен быть равен или меньше согласованного MTU.

Для клиента метод работает только с характеристиками, у которых определено свойство WriteAcquired, которое зависит от флага записи без ответа.

Возможные ключи:

device: объект устройства (только для сервера)
mtu: изменённый MTU (только для сервера)
link: тип ссылки (только для сервера)

Возможные ошибки:

org.bluez.Error.Failed,
org.bluez.Error.NotSupported.

Confirm() [опционально, только для сервера]

Метод не ожидает ответа, поэтому обозначает просто подтверждение того, что значение было получено.

Возможные ошибки:

org.bluez.Error.Failed.

array{byte} ReadValue(dict options)

Отправляет запрос на чтение значения характеристики и возвращает значение, если операция прошла успешно.

Возможные ключи:

offset: uint16, смещение
mtu: изменённый MTU (только для сервера)
device: объект устройства (только для сервера)

Возможные ошибки:

org.bluez.Error.Failed,
org.bluez.Error.InProgress,
org.bluez.Error.NotPermitted,
org.bluez.Error.NotAuthorized,
org.bluez.Error.InvalidOffset,
org.bluez.Error.NotSupported.

StartNotify()

Запускает сеанс уведомления для характеристики, если она поддерживает уведомления или индикацию значений.

Возможные ошибки:

org.bluez.Error.Failed,
org.bluez.Error.NotPermitted,
org.bluez.Error.InProgress,
org.bluez.Error.NotConnected,
org.bluez.Error.NotSupported.

StopNotify()

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

Возможные ошибки:

org.bluez.Error.Failed.

WriteValue(array{byte} value, dict options)

Отправляет запрос на запись значения характеристики.

Возможные ключи:

offset: начальное смещение.
type: тип, возможные значения:

command — записать без ответа
request — записать с ответом
reliable — надёжная запись

mtu: изменённый MTU (только для сервера)
device: объект устройства (только для сервера)
link: тип ссылки (только для сервера)
prepare-authorize: истинно, если готовится запрос на авторизацию

Возможные ошибки:

org.bluez.Error.Failed,
org.bluez.Error.InProgress,
org.bluez.Error.NotPermitted,
org.bluez.Error.InvalidValueLength,
org.bluez.Error.NotAuthorized,
org.bluez.Error.NotSupported.