diff options
Diffstat (limited to 'java/org/direct_bt/BTManager.java')
| -rw-r--r-- | java/org/direct_bt/BTManager.java | 338 |
1 files changed, 338 insertions, 0 deletions
diff --git a/java/org/direct_bt/BTManager.java b/java/org/direct_bt/BTManager.java new file mode 100644 index 00000000..c770d6cf --- /dev/null +++ b/java/org/direct_bt/BTManager.java @@ -0,0 +1,338 @@ +/** + * Author: Sven Gothel <[email protected]> + * Copyright (c) 2020 Gothel Software e.K. + * Copyright (c) 2020 ZAFENA AB + * + * Author: Andrei Vasiliu <[email protected]> + * Copyright (c) 2016 Intel Corporation. + * + * Permission is hereby granted, free of charge, to any person obtaining + * a copy of this software and associated documentation files (the + * "Software"), to deal in the Software without restriction, including + * without limitation the rights to use, copy, modify, merge, publish, + * distribute, sublicense, and/or sell copies of the Software, and to + * permit persons to whom the Software is furnished to do so, subject to + * the following conditions: + * + * The above copyright notice and this permission notice shall be + * included in all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + */ + +package org.direct_bt; + +import java.util.List; + +public interface BTManager +{ + /** + * Interface allowing to retrieve certain settings + * of the implementation. + * <p> + * In case this interface will have to add a multitude of settings in the future, + * we will revise the API using a more efficient bitfield approach. + * </p> + */ + public static interface Settings { + /** + * Returns true if underlying implementation is Direct-BT. + */ + boolean isDirectBT(); + + /** + * Returns true if underlying implementation is TinyB. + */ + boolean isTinyB(); + + /** + * Returns whether {@link BTGattChar} API: {@link BTGattChar#getValue() value cache} and + * {@link BTGattChar#enableValueNotifications(BluetoothNotification) value notification} + * is supported. + * <p> + * This is enabled using {@link #isTinyB() TinyB}, but disabled by default using {@link #isDirectBT() Direct-BT}. + * </p> + * <p> + * If using {@link #isDirectBT() Direct-BT}, user are encouraged to + * {@link BTGattChar#addCharacteristicListener(GATTCharacteristicListener, boolean[]) utilize GATTCharacteristicListener} + * to handle value notifications when they occur w/o caching. + * </p> + * <p> + * If using {@link #isDirectBT() Direct-BT}, users can enable this TinyB compatibility + * by setting the System property {@code direct_bt.tinyb.characteristic.compat} to {@code true}. + * It defaults to {@code false}, i.e. disabled. + * </p> + */ + boolean isCharacteristicValueCacheNotificationSupported(); + + @Override + String toString(); + } + + + /** + * Event listener to receive change events regarding the system's {@link BTAdapter} set, + * e.g. a removed or added {@link BTAdapter} due to user interaction or 'cold reset'. + * <p> + * When a new callback is added, all available adapter's will be reported as added, + * this allows a fully event driven workflow. + * </p> + * <p> + * The callback is performed on a dedicated thread, + * allowing the user to perform complex operations. + * </p> + * @since 2.0.0 + * @implNote Not implemented on tinyb.dbus + * @see BTManager#addChangedAdapterSetListener(ChangedAdapterSetListener) + * @see BTManager#removeChangedAdapterSetListener(ChangedAdapterSetListener) + */ + public static interface ChangedAdapterSetListener { + /** + * {@link BTAdapter} was added to the system. + * @param adapter the newly added {@link BTAdapter} to the system + */ + void adapterAdded(final BTAdapter adapter); + + /** + * {@link BTAdapter} was removed from the system. + * <p> + * {@link BTAdapter#close()} is being called by the native manager after issuing all + * {@link #adapterRemoved(BTAdapter)} calls. + * </p> + * @param adapter the removed {@link BTAdapter} from the system + */ + void adapterRemoved(final BTAdapter adapter); + } + + /** + * Returns this implmentation's {@link Settings}. + */ + public Settings getSettings(); + + /** Find a BluetoothObject of a type matching type. If parameters name, + * identifier and parent are not null, the returned object will have to + * match them. + * It will first check for existing objects. It will not turn on discovery + * or connect to devices. + * @parameter type specify the type of the object you are + * waiting for, NONE means anything. + * @parameter name optionally specify the name of the object you are + * waiting for (for Adapter or Device) + * @parameter identifier optionally specify the identifier of the object you are + * waiting for (UUID for GattService, GattCharacteristic or GattDescriptor, address + * for Adapter or Device) + * @parameter parent optionally specify the parent of the object you are + * waiting for + * @parameter timeoutMS the function will return after timeout time in milliseconds, a + * value of zero means wait forever. If object is not found during this time null will be returned. + * @return An object matching the name, identifier, parent or null if not found before + * timeout expires or event is canceled. + */ + public BTObject find(BTType type, String name, String identifier, BTObject parent, long timeoutMS); + + + /** Find a BluetoothObject of a type matching type. If parameters name, + * identifier and parent are not null, the returned object will have to + * match them. + * It will first check for existing objects. It will not turn on discovery + * or connect to devices. + * @parameter type specify the type of the object you are + * waiting for, NONE means anything. + * @parameter name optionally specify the name of the object you are + * waiting for (for Adapter or Device) + * @parameter identifier optionally specify the identifier of the object you are + * waiting for (UUID for GattService, GattCharacteristic or GattDescriptor, address + * for Adapter or Device) + * @parameter parent optionally specify the parent of the object you are + * waiting for + * @return An object matching the name, identifier and parent. + */ + public BTObject find(BTType type, String name, String identifier, BTObject parent); + + /** Find a BluetoothObject of type T. If parameters name, identifier and + * parent are not null, the returned object will have to match them. + * It will first check for existing objects. It will not turn on discovery + * or connect to devices. + * @parameter name optionally specify the name of the object you are + * waiting for (for Adapter or Device) + * @parameter identifier optionally specify the identifier of the object you are + * waiting for (UUID for GattService, GattCharacteristic or GattDescriptor, address + * for Adapter or Device) + * @parameter parent optionally specify the parent of the object you are + * waiting for + * @parameter timeoutMS the function will return after timeout time in milliseconds, a + * value of zero means wait forever. If object is not found during this time null will be returned. + * @return An object matching the name, identifier, parent or null if not found before + * timeout expires or event is canceled. + */ + public <T extends BTObject> T find(String name, String identifier, BTObject parent, long timeoutMS); + + /** Find a BluetoothObject of type T. If parameters name, identifier and + * parent are not null, the returned object will have to match them. + * It will first check for existing objects. It will not turn on discovery + * or connect to devices. + * @parameter name optionally specify the name of the object you are + * waiting for (for Adapter or Device) + * @parameter identifier optionally specify the identifier of the object you are + * waiting for (UUID for GattService, GattCharacteristic or GattDescriptor, address + * for Adapter or Device) + * @parameter parent optionally specify the parent of the object you are + * waiting for + * @return An object matching the name, identifier and parent. + */ + public <T extends BTObject> T find(String name, String identifier, BTObject parent); + + /** Return a BluetoothObject of a type matching type. If parameters name, + * identifier and parent are not null, the returned object will have to + * match them. Only objects which are already in the system will be returned. + * @parameter type specify the type of the object you are + * waiting for, NONE means anything. + * @parameter name optionally specify the name of the object you are + * waiting for (for Adapter or Device) + * @parameter identifier optionally specify the identifier of the object you are + * waiting for (UUID for GattService, GattCharacteristic or GattDescriptor, address + * for Adapter or Device) + * @parameter parent optionally specify the parent of the object you are + * waiting for + * @return An object matching the name, identifier, parent or null if not found. + */ + public BTObject getObject(BTType type, String name, + String identifier, BTObject parent); + + /** Return a List of BluetoothObject of a type matching type. If parameters name, + * identifier and parent are not null, the returned object will have to + * match them. Only objects which are already in the system will be returned. + * @parameter type specify the type of the object you are + * waiting for, NONE means anything. + * @parameter name optionally specify the name of the object you are + * waiting for (for Adapter or Device) + * @parameter identifier optionally specify the identifier of the object you are + * waiting for (UUID for GattService, GattCharacteristic or GattDescriptor, address + * for Adapter or Device) + * @parameter parent optionally specify the parent of the object you are + * waiting for + * @return A vector of object matching the name, identifier, parent. + */ + public List<BTObject> getObjects(BTType type, String name, + String identifier, BTObject parent); + + /** Returns a list of BluetoothAdapters available in the system + * @return A list of BluetoothAdapters available in the system + */ + public List<BTAdapter> getAdapters(); + + /** + * Returns the BluetoothAdapter matching the given dev_id or null if not found. + * <p> + * The adapters internal device id is constant across the adapter lifecycle, + * but may change after its destruction. + * </p> + * @param dev_id the internal temporary adapter device id + * @since 2.0.0 + * @implNote Not implemented on tinyb.dbus + */ + public BTAdapter getAdapter(final int dev_id); + + /** Returns a list of discovered BluetoothDevices + * @return A list of discovered BluetoothDevices + */ + public List<BTDevice> getDevices(); + + /** Returns a list of available BluetoothGattServices + * @return A list of available BluetoothGattServices + */ + public List<BTGattService> getServices(); + + /** + * Sets a default adapter to use for discovery. + * @return TRUE if the device was set + * @implNote not implemented for direct_bt.tinyb + */ + public boolean setDefaultAdapter(BTAdapter adapter); + + /** + * Gets the default adapter to use for discovery. + * <p> + * <i>direct_bt.tinyb</i>: The default adapter is either the first {@link BTAdapter#isPowered() powered} {@link BTAdapter}, + * or function returns nullptr if none is enabled. + * </p> + * <p> + * <i>tinyb.dbus</i>: System default is the last detected adapter at initialization. + * </p> + * @return the used default adapter + */ + public BTAdapter getDefaultAdapter(); + + /** Turns on device discovery on the default adapter if it is disabled. + * @return TRUE if discovery was successfully enabled + * @deprecated since 2.0.0, use {@link #startDiscovery(boolean)}. + */ + @Deprecated + public boolean startDiscovery() throws BTException; + + /** + * Turns on device discovery on the default adapter if it is disabled. + * @param keepAlive if {@code true}, indicates that discovery shall be restarted + * if stopped by the underlying Bluetooth implementation (BlueZ, ..). + * Using {@link #startDiscovery(boolean) startDiscovery}({@code keepAlive=true}) + * and {@link #stopDiscovery()} is the recommended workflow + * for a reliable discovery process. + * @return {@link HCIStatusCode#SUCCESS} if successful, otherwise the {@link HCIStatusCode} error state + * @throws BTException + * @since 2.0.0 + * @implNote {@code keepAlive} not implemented in tinyb.dbus + */ + public HCIStatusCode startDiscovery(final boolean keepAlive) throws BTException; + + /** + * Turns off device discovery on the default adapter if it is enabled. + * @return {@link HCIStatusCode#SUCCESS} if successful, otherwise the {@link HCIStatusCode} error state + * @apiNote return {@link HCIStatusCode} since 2.0.0 + * @since 2.0.0 + */ + public HCIStatusCode stopDiscovery() throws BTException; + + /** Returns if the discovers is running or not. + * @return TRUE if discovery is running + */ + public boolean getDiscovering() throws BTException; + + /** + * Add the given {@link ChangedAdapterSetListener} to this manager. + * <p> + * When a new callback is added, all available adapter's will be reported as added, + * this allows a fully event driven workflow. + * </p> + * <p> + * The callback is performed on a dedicated thread, + * allowing the user to perform complex operations. + * </p> + * @since 2.0.0 + * @implNote Not implemented on tinyb.dbus + */ + void addChangedAdapterSetListener(final ChangedAdapterSetListener l); + + /** + * Remove the given {@link ChangedAdapterSetListener} from this manager. + * @param l the to be removed element + * @return the number of removed elements + * @since 2.0.0 + * @implNote Not implemented on tinyb.dbus + */ + int removeChangedAdapterSetListener(final ChangedAdapterSetListener l); + + /** + * Release the native memory associated with this object and all related Bluetooth resources. + * The object should not be used following a call to close + * <p> + * Shutdown method is intended to allow a clean Bluetooth state at program exist. + * </p> + */ + public void shutdown(); +} |