org.bluez.GattCharacteristic1 Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of bluez-dbus-osgi Show documentation
Java native bluetooth library which uses bluez via dbus (linux only). This is the OSGi compliant bundle of all required libraries in one bundle.
The newest version!
package org.bluez;

import org.bluez.datatypes.TwoTuple;
import org.bluez.exceptions.*;
import org.freedesktop.dbus.FileDescriptor;
import org.freedesktop.dbus.interfaces.DBusInterface;
import org.freedesktop.dbus.types.UInt16;
import org.freedesktop.dbus.types.Variant;

import java.util.Map;

/**
 * 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.

 * 

 * 

 */
public interface GattCharacteristic1 extends DBusInterface {

    /**
     * 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)

     * 

     * 
     * @param _options options
     * 
     * @return byte[] - maybe null
     * 
     * @throws BluezFailedException on failure
     * @throws BluezInProgressException when operation already in progress
     * @throws BluezNotPermittedException on BluezNotPermittedException
     * @throws BluezNotAuthorizedException when not authorized
     * @throws BluezInvalidOffsetException on BluezInvalidOffsetException
     * @throws BluezNotSupportedException when operation not supported
     */
    byte[] ReadValue(Map> _options) throws BluezFailedException, BluezInProgressException, BluezNotPermittedException, BluezNotAuthorizedException, BluezInvalidOffsetException, 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

     * 

     * 
     * @param _value value
     * @param _options options
     * 
     * @throws BluezFailedException on failure
     * @throws BluezInProgressException when operation already in progress
     * @throws BluezNotPermittedException on BluezNotPermittedException
     * @throws BluezInvalidValueLengthException on BluezInvalidValueLengthException
     * @throws BluezNotAuthorizedException when not authorized
     * @throws BluezNotSupportedException when operation not supported
     */
    void WriteValue(byte[] _value, Map> _options) throws BluezFailedException, BluezInProgressException, BluezNotPermittedException, BluezInvalidValueLengthException, BluezNotAuthorizedException, 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)

     * 

     * 
     * @param _options options
     * 
     * @return TwoTuple<FileDescriptor, UInt16> - maybe null
     * 
     * @throws BluezFailedException on failure
     * @throws BluezNotSupportedException when operation not supported
     */
    TwoTuple AcquireWrite(Map> _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)

     * 

     * 
     * @param _options options
     * 
     * @return TwoTuple<FileDescriptor, UInt16> - maybe null
     * 
     * @throws BluezFailedException on failure
     * @throws BluezNotSupportedException when operation not supported
     */
    TwoTuple AcquireNotify(Map> _options) throws BluezFailedException, BluezNotSupportedException;

    /**
     * From bluez documentation:

     * 

     * Starts a notification session from this characteristic

     * if it supports value notifications or indications.

     * 

     * 
     * @throws BluezFailedException on failure
     * @throws BluezNotPermittedException on BluezNotPermittedException
     * @throws BluezInProgressException when operation already in progress
     * @throws BluezNotConnectedException when bluez not connected
     * @throws BluezNotSupportedException when operation not supported
     */
    void StartNotify() throws BluezFailedException, BluezNotPermittedException, BluezInProgressException, BluezNotConnectedException, BluezNotSupportedException;

    /**
     * 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
     */
    void StopNotify() 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
     */
    void Confirm() throws BluezFailedException;

}