Package org.bluez

Interface GattCharacteristic1

All Superinterfaces:
org.freedesktop.dbus.interfaces.DBusInterface
public interface GattCharacteristic1 extends org.freedesktop.dbus.interfaces.DBusInterface
File generated - 2023-02-20.
Based on bluez Documentation: gatt-api.txt.

Service: org.bluez
Interface: org.bluez.GattCharacteristic1

Object path:
[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY

Supported properties:

string UUID [read-only]

128-bit characteristic UUID.

object Service [read-only]

Object path of the GATT service the characteristic
belongs to.

array{byte} Value [read-only, optional]

The cached value of the characteristic. This property
gets updated only after a successful read request and
when a notification or indication is received, upon
which a PropertiesChanged signal will be emitted.

boolean WriteAcquired [read-only, optional]

True, if this characteristic has been acquired by any
client using AcquireWrite.

For client properties is ommited in case
'write-without-response' flag is not set.

For server the presence of this property indicates
that AcquireWrite is supported.

boolean NotifyAcquired [read-only, optional]

True, if this characteristic has been acquired by any
client using AcquireNotify.

For client this properties is ommited in case 'notify'
flag is not set.

For server the presence of this property indicates
that AcquireNotify is supported.

boolean Notifying [read-only, optional]

True, if notifications or indications on this
characteristic are currently enabled.

array{string} Flags [read-only]

Defines how the characteristic value can be used. See
Core spec "Table 3.5: Characteristic Properties bit
field", and "Table 3.8: Characteristic Extended
Properties bit field".

The "x-notify" and "x-indicate" flags restrict access
to notifications and indications by imposing write
restrictions on a characteristic's client
characteristic configuration descriptor.

Allowed values:

"broadcast"
"read"
"write-without-response"
"write"
"notify"
"indicate"
"authenticated-signed-writes"
"extended-properties"
"reliable-write"
"writable-auxiliaries"
"encrypt-read"
"encrypt-write"
"encrypt-notify" (Server only)
"encrypt-indicate" (Server only)
"encrypt-authenticated-read"
"encrypt-authenticated-write"
"encrypt-authenticated-notify" (Server only)
"encrypt-authenticated-indicate" (Server only)
"secure-read" (Server only)
"secure-write" (Server only)
"secure-notify" (Server only)
"secure-indicate" (Server only)
"authorize"

uint16 Handle [read-write, optional] (Server Only)

Characteristic handle. When available in the server it
would attempt to use to allocate into the database
which may fail, to auto allocate the value 0x0000
shall be used which will cause the allocated handle to
be set once registered.

uint16 MTU [read-only]

Characteristic MTU, this is valid both for ReadValue
and WriteValue but either method can use long
procedures when supported.


  • Method Summary

    Modifier and Type
    Method
    Description
    TwoTuple<org.freedesktop.dbus.FileDescriptor,org.freedesktop.dbus.types.UInt16>
    AcquireNotify(Map<String,org.freedesktop.dbus.types.Variant<?>> _options)
    From bluez documentation:

    Acquire file descriptor and MTU for notify.
    TwoTuple<org.freedesktop.dbus.FileDescriptor,org.freedesktop.dbus.types.UInt16>
    AcquireWrite(Map<String,org.freedesktop.dbus.types.Variant<?>> _options)
    From bluez documentation:

    Acquire file descriptor and MTU for writing.
    void
    Confirm()
    From bluez documentation:

    This method doesn't expect a reply so it is just a
    confirmation that value was received.

    byte[]
    ReadValue(Map<String,org.freedesktop.dbus.types.Variant<?>> _options)
    From bluez documentation:

    Issues a request to read the value of the
    characteristic and returns the value if the
    operation was successful.

    Possible options: "offset": uint16 offset
    "mtu": Exchanged MTU (Server only)
    "device": Object Device (Server only)

    void
    StartNotify()
    From bluez documentation:

    Starts a notification session from this characteristic
    if it supports value notifications or indications.

    void
    StopNotify()
    From bluez documentation:

    This method will cancel any previous StartNotify
    transaction.
    void
    WriteValue(byte[] _value, Map<String,org.freedesktop.dbus.types.Variant<?>> _options)
    From bluez documentation:

    Issues a request to write the value of the
    characteristic.

    Possible options: "offset": Start offset
    "type": string
    Possible values:
    "command": Write without
    response
    "request": Write with response
    "reliable": Reliable Write
    "mtu": Exchanged MTU (Server only)
    "device": Device path (Server only)
    "link": Link type (Server only)
    "prepare-authorize": True if prepare
    authorization
    request

    Methods inherited from interface org.freedesktop.dbus.interfaces.DBusInterface

    getObjectPath, isRemote

  • Method Details

    • ReadValue

      byte[] ReadValue(Map<String,org.freedesktop.dbus.types.Variant<?>> _options) throws BluezFailedException, BluezInProgressException, BluezNotPermittedException, BluezNotAuthorizedException, BluezInvalidOffsetException, BluezNotSupportedException
      From bluez documentation:

      Issues a request to read the value of the
      characteristic and returns the value if the
      operation was successful.

      Possible options: "offset": uint16 offset
      "mtu": Exchanged MTU (Server only)
      "device": Object Device (Server only)

      Parameters:
      _options - options
      Returns:
      byte[] - maybe null
      Throws:
      BluezFailedException - on failure
      BluezInProgressException - when operation already in progress
      BluezNotPermittedException - on BluezNotPermittedException
      BluezNotAuthorizedException - when not authorized
      BluezInvalidOffsetException - on BluezInvalidOffsetException
      BluezNotSupportedException - when operation not supported

    • WriteValue

      void WriteValue(byte[] _value, Map<String,org.freedesktop.dbus.types.Variant<?>> _options) throws BluezFailedException, BluezInProgressException, BluezNotPermittedException, BluezInvalidValueLengthException, BluezNotAuthorizedException, BluezNotSupportedException
      From bluez documentation:

      Issues a request to write the value of the
      characteristic.

      Possible options: "offset": Start offset
      "type": string
      Possible values:
      "command": Write without
      response
      "request": Write with response
      "reliable": Reliable Write
      "mtu": Exchanged MTU (Server only)
      "device": Device path (Server only)
      "link": Link type (Server only)
      "prepare-authorize": True if prepare
      authorization
      request

      Parameters:
      _value - value
      _options - options
      Throws:
      BluezFailedException - on failure
      BluezInProgressException - when operation already in progress
      BluezNotPermittedException - on BluezNotPermittedException
      BluezInvalidValueLengthException - on BluezInvalidValueLengthException
      BluezNotAuthorizedException - when not authorized
      BluezNotSupportedException - when operation not supported

    • AcquireWrite

      TwoTuple<org.freedesktop.dbus.FileDescriptor,org.freedesktop.dbus.types.UInt16> AcquireWrite(Map<String,org.freedesktop.dbus.types.Variant<?>> _options) throws BluezFailedException, BluezNotSupportedException
      From bluez documentation:

      Acquire file descriptor and MTU for writing. Only
      sockets are supported. Usage of WriteValue will be
      locked causing it to return NotPermitted error.

      For server the MTU returned shall be equal or smaller
      than the negotiated MTU.

      For client it only works with characteristic that has
      WriteAcquired property which relies on
      write-without-response Flag.

      To release the lock the client shall close the file
      descriptor, a HUP is generated in case the device
      is disconnected.

      Note: the MTU can only be negotiated once and is
      symmetric therefore this method may be delayed in
      order to have the exchange MTU completed, because of
      that the file descriptor is closed during
      reconnections as the MTU has to be renegotiated.

      Possible options: "device": Object Device (Server only)
      "mtu": Exchanged MTU (Server only)
      "link": Link type (Server only)

      Parameters:
      _options - options
      Returns:
      TwoTuple<FileDescriptor, UInt16> - maybe null
      Throws:
      BluezFailedException - on failure
      BluezNotSupportedException - when operation not supported

    • AcquireNotify

      TwoTuple<org.freedesktop.dbus.FileDescriptor,org.freedesktop.dbus.types.UInt16> AcquireNotify(Map<String,org.freedesktop.dbus.types.Variant<?>> _options) throws BluezFailedException, BluezNotSupportedException
      From bluez documentation:

      Acquire file descriptor and MTU for notify. Only
      sockets are support. Usage of StartNotify will be locked
      causing it to return NotPermitted error.

      For server the MTU returned shall be equal or smaller
      than the negotiated MTU.

      Only works with characteristic that has NotifyAcquired
      which relies on notify Flag and no other client have
      called StartNotify.

      Notification are enabled during this procedure so
      StartNotify shall not be called, any notification
      will be dispatched via file descriptor therefore the
      Value property is not affected during the time where
      notify has been acquired.

      To release the lock the client shall close the file
      descriptor, a HUP is generated in case the device
      is disconnected.

      Note: the MTU can only be negotiated once and is
      symmetric therefore this method may be delayed in
      order to have the exchange MTU completed, because of
      that the file descriptor is closed during
      reconnections as the MTU has to be renegotiated.

      Possible options: "device": Object Device (Server only)
      "mtu": Exchanged MTU (Server only)
      "link": Link type (Server only)

      Parameters:
      _options - options
      Returns:
      TwoTuple<FileDescriptor, UInt16> - maybe null
      Throws:
      BluezFailedException - on failure
      BluezNotSupportedException - when operation not supported

    • StartNotify

      void StartNotify() throws BluezFailedException, BluezNotPermittedException, BluezInProgressException, BluezNotConnectedException, BluezNotSupportedException
      From bluez documentation:

      Starts a notification session from this characteristic
      if it supports value notifications or indications.

      Throws:
      BluezFailedException - on failure
      BluezNotPermittedException - on BluezNotPermittedException
      BluezInProgressException - when operation already in progress
      BluezNotConnectedException - when bluez not connected
      BluezNotSupportedException - when operation not supported

    • StopNotify

      void StopNotify() throws BluezFailedException
      From bluez documentation:

      This method will cancel any previous StartNotify
      transaction. Note that notifications from a
      characteristic are shared between sessions thus
      calling StopNotify will release a single session.

      Throws:
      BluezFailedException - on failure

    • Confirm

      void Confirm() throws BluezFailedException
      From bluez documentation:

      This method doesn't expect a reply so it is just a
      confirmation that value was received.

      Throws:
      BluezFailedException - on failure