diff options
Diffstat (limited to 'java/org/direct_bt/BTGattChar.java')
| -rw-r--r-- | java/org/direct_bt/BTGattChar.java | 107 |
1 files changed, 69 insertions, 38 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 */ |