diff options
Diffstat (limited to 'java/org/direct_bt')
-rw-r--r-- | java/org/direct_bt/BTGattChar.java | 107 | ||||
-rw-r--r-- | java/org/direct_bt/BTGattCharListener.java | 6 |
2 files changed, 72 insertions, 41 deletions
diff --git a/java/org/direct_bt/BTGattChar.java b/java/org/direct_bt/BTGattChar.java index 5dfb2373..078fbd0f 100644 --- a/java/org/direct_bt/BTGattChar.java +++ b/java/org/direct_bt/BTGattChar.java @@ -38,6 +38,45 @@ import java.util.List; */ public interface BTGattChar extends BTObject { + /** + * {@link BTGattChar} event listener for notification and indication events. + * <p> + * This listener instance is attached to a {@link BTGattChar} via + * {@link BTGattChar#addCharListener(Listener)} or {@link BTGattChar#addCharListener(Listener, boolean[])} + * to listen to events associated with the {@link BTGattChar} instance. + * </p> + * <p> + * The listener manager maintains a unique set of listener instances without duplicates. + * </p> + * <p> + * Implementation will utilize a {@link BTGattCharListener) for the listener manager, + * delegating matching {@link BTGattChar} events to this instance. + * </p> + */ + static public interface Listener { + /** + * Called from native BLE stack, initiated by a received notification associated + * with the given {@link BTGattChar}. + * @param charDecl {@link BTGattChar} related to this notification + * @param value the notification value + * @param timestamp the indication monotonic timestamp, see {@link BTUtils#currentTimeMillis()} + */ + public void notificationReceived(final BTGattChar charDecl, + final byte[] value, final long timestamp); + + /** + * Called from native BLE stack, initiated by a received indication associated + * with the given {@link BTGattChar}. + * @param charDecl {@link BTGattChar} related to this indication + * @param value the indication value + * @param timestamp the indication monotonic timestamp, see {@link BTUtils#currentTimeMillis()} + * @param confirmationSent if true, the native stack has sent the confirmation, otherwise user is required to do so. + */ + public void indicationReceived(final BTGattChar charDecl, + final byte[] value, final long timestamp, + final boolean confirmationSent); + }; + @Override public BTGattChar clone(); @@ -130,80 +169,69 @@ public interface BTGattChar extends BTObject throws IllegalStateException; /** - * Add the given {@link BTGattCharListener} to the listener list if not already present. + * Add the given {@link BTGattChar.Listener} to the listener list if not already present. * <p> - * Occurring notifications and indications, if enabled via {@link #configNotificationIndication(boolean, boolean, boolean[])} + * Occurring notifications and indications for this characteristic, + * if enabled via {@link #configNotificationIndication(boolean, boolean, boolean[])} * or {@link #enableNotificationOrIndication(boolean[])}, - * will call the respective BTGattCharListener callback method. + * will call the respective {@link BTGattChar.Listener} callback method. * </p> - * @param listener A {@link BTGattCharListener} instance, listening to this {@link BTGattChar}'s events + * <p> + * Implementation wraps given {@link BTGattChar.Listener} into a {@link BTGattCharListener} + * to restrict the listener to listen only to this BTGattChar instance. + * </p> + * @param listener A {@link BTGattChar.Listener} instance, listening to this {@link BTGattChar}'s events * @return true if the given listener is not element of the list and has been newly added, otherwise false. * @throws IllegalStateException if the DBTDevice's GATTHandler is null, i.e. not connected - * @throws IllegalStateException if the given {@link BTGattCharListener} is already in use, i.e. added. + * @throws IllegalStateException if the given {@link BTGattChar.Listener} is already in use, i.e. added. * @see #enableNotificationOrIndication(boolean[]) * @see #configNotificationIndication(boolean, boolean, boolean[]) + * @see #addCharListener(Listener, boolean[]) + * @see #removeCharListener(Listener, boolean) + * @see #removeAllAssociatedCharListener(boolean) * @since 2.0.0 * @implNote not implemented in tinyb.dbus */ - public boolean addCharListener(final BTGattCharListener listener) + public boolean addCharListener(final Listener listener) throws IllegalStateException; /** - * Add the given {@link BTGattCharListener} to the listener list if not already present + * Add the given {@link BTGattChar.Listener} to the listener list if not already present * and if enabling the notification <i>or</i> indication for this characteristic at BLE level was successful.<br> * Notification and/or indication configuration is only performed per characteristic if changed. * <p> - * Implementation will attempt to enable notification only, if available, - * otherwise indication if available. <br> - * Implementation uses {@link #enableNotificationOrIndication(boolean[])} to enable one. + * Implementation will enable notification if available, + * otherwise indication will be enabled if available. <br> + * Implementation uses {@link #enableNotificationOrIndication(boolean[])} to enable either. * </p> * <p> - * Occurring notifications and indications will call the respective {@link BTGattCharListener} - * callback method. + * Occurring notifications and indications for this characteristic + * will call the respective {@link BTGattChar.Listener} callback method. * </p> - * @param listener A {@link BTGattCharListener} instance, listening to this {@link BTGattChar}'s events + * @param listener A {@link BTGattChar.Listener} instance, listening to this {@link BTGattChar}'s events * @param enabledState array of size 2, holding the resulting enabled state for notification and indication * using {@link #enableNotificationOrIndication(boolean[])} * @return true if enabling the notification and/or indication was successful * and if the given listener is not element of the list and has been newly added, otherwise false. * @throws IllegalStateException if the {@link BTDevice}'s GATTHandler is null, i.e. not connected - * @throws IllegalStateException if the given {@link BTGattCharListener} is already in use, i.e. added. + * @throws IllegalStateException if the given {@link BTGattChar.Listener} is already in use, i.e. added. * @see #enableNotificationOrIndication(boolean[]) * @see #configNotificationIndication(boolean, boolean, boolean[]) + * @see #addCharListener(Listener) + * @see #removeCharListener(Listener, boolean) + * @see #removeAllAssociatedCharListener(boolean) * @since 2.0.0 * @implNote not implemented in tinyb.dbus */ - public boolean addCharListener(final BTGattCharListener listener, final boolean enabledState[/*2*/]) + public boolean addCharListener(final Listener listener, final boolean enabledState[/*2*/]) throws IllegalStateException; /** - * Disables the notification and/or indication for this characteristic at BLE level - * if {@code disableIndicationNotification == true} - * and removes the given {@link BTGattCharListener} from the listener list. - * <p> - * If the DBTDevice's GATTHandler is null, i.e. not connected, {@code false} is being returned. - * </p> - * - * @param listener A {@link BTGattCharListener} instance - * @param disableIndicationNotification if true, disables the notification and/or indication for this characteristic - * using {@link #configNotificationIndication(boolean, boolean, boolean[])} - * @return true if the given listener is an element of the list and has been removed, otherwise false. - * @see #configNotificationIndication(boolean, boolean, boolean[]) - * @since 2.0.0 - * @implNote not implemented in tinyb.dbus - */ - public boolean removeCharListener(final BTGattCharListener l, final boolean disableIndicationNotification); - - /** * Disables the notification and/or indication for this characteristic BLE level * if {@code disableIndicationNotification == true} - * and removes all {@link BTGattCharListener} from the listener list, + * and removes all associated {@link BTGattChar.Listener} or {@link BTGattCharListener} from the listener list, * which are associated with this characteristic instance. * <p> - * Implementation tests all listener's {@link BTGattCharListener#getAssociatedChar()} - * to match with this characteristic instance. - * </p> - * <p> * If the DBTDevice's GATTHandler is null, i.e. not connected, {@code false} is being returned. * </p> * @@ -212,6 +240,9 @@ public interface BTGattChar extends BTObject * @return number of removed listener. * @see #configNotificationIndication(boolean, boolean, boolean[]) * @see BTDevice#removeAllAssociatedCharListener(BTGattChar) + * @see #addCharListener(Listener) + * @see #addCharListener(Listener, boolean[]) + * @see #removeCharListener(Listener, boolean) * @since 2.0.0 * @implNote not implemented in tinyb.dbus */ diff --git a/java/org/direct_bt/BTGattCharListener.java b/java/org/direct_bt/BTGattCharListener.java index d24a3d49..862ef4b0 100644 --- a/java/org/direct_bt/BTGattCharListener.java +++ b/java/org/direct_bt/BTGattCharListener.java @@ -31,7 +31,7 @@ import java.lang.ref.WeakReference; * {@link BTGattChar} event listener for notification and indication events. * <p> * A listener instance may be attached to a {@link BTGattChar} via - * {@link BTGattChar#addCharListener(BTGattCharListener)} to listen to its events. + * {@link BTGattChar#addCharListener(org.direct_bt.BTGattChar.Listener)} to listen to its events. * </p> * <p> * A listener instance may be attached to a {@link BTDevice} via @@ -39,7 +39,7 @@ import java.lang.ref.WeakReference; * to listen to all events of the device or the matching filtered events. * </p> * <p> - * One {@link BTGattCharListener} instance can only be attached to a listener receiver once at a time, + * One {@link BTGattCharListener} instance can only be attached to a listener manager once at a time, * i.e. you cannot attach the same instance more than once to a {@link BTDevice} * or {@link BTGattChar}. * <br> @@ -50,7 +50,7 @@ import java.lang.ref.WeakReference; * The latter will be added to the native list of listeners. * This class's {@code nativeInstance} field links the Java instance to mentioned C++ listener. * <br> - * Since the listener receiver maintains a unique set of listener instances without duplicates, + * Since the listener manager maintains a unique set of listener instances without duplicates, * this restriction is more esoteric. * </p> */ |