java: Document Notification methods

Signed-off-by: Petre Eftime <[email protected]>

5 files changed, 140 insertions, 12 deletions

diff --git a/java/BluetoothAdapter.java b/java/BluetoothAdapter.java
index cd51823d..10c39a2d 100644
--- a/java/BluetoothAdapter.java
+++ b/java/BluetoothAdapter.java
@@ -117,7 +117,18 @@ public class BluetoothAdapter extends BluetoothObject
       */
     public native boolean getPowered();
 
-    public native void enablePoweredNotifications(BluetoothNotification<Boolean> powered);
+    /**
+     * Enables notifications for the powered property and calls run function of the
+     * BluetoothNotification object.
+     * @param callback A BluetoothNotification<Boolean> object. Its run function will be called
+     * when a notification is issued. The run function will deliver the new value of the powered
+     * property.
+     */
+    public native void enablePoweredNotifications(BluetoothNotification<Boolean> callback);
+    /**
+     * Disables notifications of the powered property and unregisters the callback
+     * object passed through the corresponding enable method.
+     */
     public native void disablePoweredNotifications();
 
     /** Sets the power state the adapter.
@@ -129,7 +140,18 @@ public class BluetoothAdapter extends BluetoothObject
       */
     public native boolean getDiscoverable();
 
-    public native void enableDiscoverableNotifications(BluetoothNotification<Boolean> discoverable);
+    /**
+     * Enables notifications for the discoverable property and calls run function of the
+     * BluetoothNotification object.
+     * @param callback A BluetoothNotification<Boolean> object. Its run function will be called
+     * when a notification is issued. The run function will deliver the new value of the discoverable
+     * property.
+     */
+    public native void enableDiscoverableNotifications(BluetoothNotification<Boolean> callback);
+    /**
+     * Disables notifications of the discoverable property and unregisters the callback
+     * object passed through the corresponding enable method.
+     */
     public native void disableDiscoverableNotifications();
 
     /** Sets the discoverable state the adapter.
@@ -151,7 +173,18 @@ public class BluetoothAdapter extends BluetoothObject
       */
     public native boolean getPairable();
 
-    public native void enablePairableNotifications(BluetoothNotification<Boolean> pairable);
+    /**
+     * Enables notifications for the pairable property and calls run function of the
+     * BluetoothNotification object.
+     * @param callback A BluetoothNotification<Boolean> object. Its run function will be called
+     * when a notification is issued. The run function will deliver the new value of the pairable
+     * property.
+     */
+    public native void enablePairableNotifications(BluetoothNotification<Boolean> callback);
+    /**
+     * Disables notifications of the pairable property and unregisters the callback
+     * object passed through the corresponding enable method.
+     */
     public native void disablePairableNotifications();
 
     /** Sets the discoverable state the adapter.
@@ -174,7 +207,18 @@ public class BluetoothAdapter extends BluetoothObject
       */
     public native boolean getDiscovering();
 
-    public native void enableDiscoveringNotifications(BluetoothNotification<Boolean> discovering);
+    /**
+     * Enables notifications for the discovering property and calls run function of the
+     * BluetoothNotification object.
+     * @param callback A BluetoothNotification<Boolean> object. Its run function will be called
+     * when a notification is issued. The run function will deliver the new value of the discovering
+     * property.
+     */
+    public native void enableDiscoveringNotifications(BluetoothNotification<Boolean> callback);
+    /**
+     * Disables notifications of the discovering property and unregisters the discovering
+     * object passed through the corresponding enable method.
+     */
     public native void disableDiscoveringNotifications();
 
     /** Returns the UUIDs of the adapter.
diff --git a/java/BluetoothDevice.java b/java/BluetoothDevice.java
index 07605b59..df5fbe49 100644
--- a/java/BluetoothDevice.java
+++ b/java/BluetoothDevice.java
@@ -150,7 +150,18 @@ public class BluetoothDevice extends BluetoothObject
       */
     public native boolean getPaired();
 
-    public native void enablePairedNotifications(BluetoothNotification<Boolean> paired);
+    /**
+     * Enables notifications for the paired property and calls run function of the
+     * BluetoothNotification object.
+     * @param callback A BluetoothNotification<Boolean> object. Its run function will be called
+     * when a notification is issued. The run function will deliver the new value of the paired
+     * property.
+     */
+    public native void enablePairedNotifications(BluetoothNotification<Boolean> callback);
+    /**
+     * Disables notifications of the paired property and unregisters the callback
+     * object passed through the corresponding enable method.
+     */
     public native void disablePairedNotifications();
 
     /** Returns the trusted state the device.
@@ -158,7 +169,18 @@ public class BluetoothDevice extends BluetoothObject
       */
     public native boolean getTrusted();
 
-    public native void enableTrustedNotifications(BluetoothNotification<Boolean> trusted);
+    /**
+     * Enables notifications for the trusted property and calls run function of the
+     * BluetoothNotification object.
+     * @param callback A BluetoothNotification<Boolean> object. Its run function will be called
+     * when a notification is issued. The run function will deliver the new value of the trusted
+     * property.
+     */
+    public native void enableTrustedNotifications(BluetoothNotification<Boolean> callback);
+    /**
+     * Disables notifications of the trusted property and unregisters the callback
+     * object passed through the corresponding enable method.
+     */
     public native void disableTrustedNotifications();
 
     /** Sets the trusted state the device.
@@ -170,8 +192,19 @@ public class BluetoothDevice extends BluetoothObject
       */
     public native boolean getBlocked();
 
-    public native void enableBlockedNotifications(BluetoothNotification<Boolean> blocked);
-    public native void disableBlockeddNotifications();
+    /**
+     * Enables notifications for the blocked property and calls run function of the
+     * BluetoothNotification object.
+     * @param callback A BluetoothNotification<Boolean> object. Its run function will be called
+     * when a notification is issued. The run function will deliver the new value of the blocked
+     * property.
+     */
+    public native void enableBlockedNotifications(BluetoothNotification<Boolean> callback);
+    /**
+     * Disables notifications of the blocked property and unregisters the callback
+     * object passed through the corresponding enable method.
+     */
+    public native void disableBlockedNotifications();
 
     /** Sets the blocked state the device.
       */
@@ -187,7 +220,18 @@ public class BluetoothDevice extends BluetoothObject
       */
     public native short getRSSI();
 
-    public native void enableRSSINotifications(BluetoothNotification<Short> rssi);
+    /**
+     * Enables notifications for the RSSI property and calls run function of the
+     * BluetoothNotification object.
+     * @param callback A BluetoothNotification<Short> object. Its run function will be called
+     * when a notification is issued. The run function will deliver the new value of the RSSI
+     * property.
+     */
+    public native void enableRSSINotifications(BluetoothNotification<Short> callback);
+    /**
+     * Disables notifications of the RSSI property and unregisters the callback
+     * object passed through the corresponding enable method.
+     */
     public native void disableRSSINotifications();
 
     /** Returns the connected state of the device.
@@ -195,8 +239,19 @@ public class BluetoothDevice extends BluetoothObject
       */
     public native boolean getConnected();
 
-    public native void enableConnectedNotifications(BluetoothNotification<Boolean> connected);
-    public native void disableConnectedNotifications();
+    /**
+     * Enables notifications for the connected property and calls run function of the
+     * BluetoothNotification object.
+     * @param callback A BluetoothNotification<Boolean> object. Its run function will be called
+     * when a notification is issued. The run function will deliver the new value of the connected
+     * property.
+     */
+    public native void enableConnectedNotifications(BluetoothNotification<Boolean> callback);
+    /**
+     * Disables notifications of the connected property and unregisters the callback
+     * object passed through the corresponding enable method.
+     */
+     public native void disableConnectedNotifications();
 
     /** Returns the UUIDs of the device.
       * @return Array containing the UUIDs of the device, ends with NULL.
diff --git a/java/BluetoothGattCharacteristic.java b/java/BluetoothGattCharacteristic.java
index cb80c3be..9e20fffc 100644
--- a/java/BluetoothGattCharacteristic.java
+++ b/java/BluetoothGattCharacteristic.java
@@ -74,7 +74,19 @@ public class BluetoothGattCharacteristic extends BluetoothObject
       */
     public native byte[] readValue() throws BluetoothException;
 
+    /**
+     * Enables notifications for the value and calls run function of the BluetoothNotification
+     * object. It enables notifications for this characteristic at BLE level.
+     * @param callback A BluetoothNotification<byte[]> object. Its run function will be called
+     * when a notification is issued. The run function will deliver the new value of the value
+     * property.
+     */
     public native void enableValueNotifications(BluetoothNotification<byte[]> callback);
+    /**
+     * Disables notifications of the value and unregisters the callback object
+     * passed through the corresponding enable method. It disables notications
+     * at BLE level for this characteristic.
+     */
     public native void disableValueNotifications();
 
     /** Writes the value of this characteristic.
diff --git a/java/BluetoothGattDescriptor.java b/java/BluetoothGattDescriptor.java
index b1a87c78..d5911d23 100644
--- a/java/BluetoothGattDescriptor.java
+++ b/java/BluetoothGattDescriptor.java
@@ -50,7 +50,18 @@ public class BluetoothGattDescriptor extends BluetoothObject
       */
     public native boolean writeValue(byte[] argValue) throws BluetoothException;
 
-    public native void enableValueNotifications(BluetoothNotification<byte[]> value);
+    /**
+     * Enables notifications for the value and calls run function of the BluetoothNotification
+     * object.
+     * @param callback A BluetoothNotification<byte[]> object. Its run function will be called
+     * when a notification is issued. The run function will deliver the new value of the value
+     * property.
+     */
+    public native void enableValueNotifications(BluetoothNotification<byte[]> callback);
+    /**
+     * Disables notifications of the value and unregisters the callback object
+     * passed through the corresponding enable method.
+     */
     public native void disableValueNotifications();
 
     /* D-Bus property accessors: */
diff --git a/java/BluetoothNotification.java b/java/BluetoothNotification.java
index d3329dd7..79fe800c 100644
--- a/java/BluetoothNotification.java
+++ b/java/BluetoothNotification.java
@@ -24,6 +24,12 @@
 
 package tinyb;
 
+/*
+ * This interface is used by notifications.
+ * Implement a class inheriting BluetoothNotification and pass an object of that type
+ * to the enable*Notifications function. When a notification of that type is received,
+ * the run function of the class will be called.
+ */
 public interface BluetoothNotification<T> {
     public void run(T value);
 }