Add documentation (Java side)

README.md

@@ -1 +1,28 @@
-# AdHocLibrary (Android library)
+# Ad Hoc Library (adhoc_plugin)
+
+Flutter plugin that handles ad hoc network operations for Android mobile devices.
+
+This library is a ported version in Dart of the AdHocLibrary project developed by [Gaulthier Gain](https://github.com/gaulthiergain). The original version works with both Bluetooth and Wi-Fi Direct whereas the ported version supports Bluetooth Low Energy (only) and Wi-Fi Direct. Some classes have been kept as-is with minor modifications as those were not available in the Flutter framework, e.g., Android Wi-Fi Direct APIs. The original project can be found at the following link [AdHocLib](https://github.com/gaulthiergain/AdHocLib).
+
+This version is designed for my master thesis at the Université de Liège (Montefiore Institute). In addition to porting the original project, new security functionalities have been added such as the ability to send encrypted data to a remote peer.
+
+## Usage
+
+The ad hoc library supports the following operations:
+- Create an ad hoc network
+- Join an ad hoc network
+- Leave an ad hoc network
+- Send data in plain-text to a remote destination (use ad hoc routing algorithm (AODV) if needed)
+- Send encrypted data to a remote destination (use ad hoc routing algorithm (AODV) if needed)
+- Forward data to another node of the network (use ad hoc routing algorithm (AODV) if needed)
+- Broadcast data in plain-text to all directly connected neighbors
+- Broadcast encrypted data to all directly connected neighbors
+- Revoke its certificate (private key compromised)
+- Create a secure group in the ad hoc network
+- Join an existing secure group in the ad hoc network
+- Leave an existing secure group in the ad hoc network
+- Provides notifications of specific events related to the library (e.g., connection established, or data received)
+
+## Application Example
+
+See example.

android/src/main/java/com/montefiore/thaidinhle/adhoc_plugin/AdhocPlugin.java

@@ -16,7 +16,10 @@
 import io.flutter.plugin.common.MethodChannel.MethodCallHandler;
 import io.flutter.plugin.common.MethodChannel.Result;
 
-
+/**
+ * Class managing the Android platform-specific code, which is responsible 
+ * of managing platform call from the Flutter client.
+ */
 public class AdhocPlugin implements FlutterPlugin, MethodCallHandler {
   private static final String METHOD_NAME = "ad.hoc.lib/ble.method.channel";
 
@@ -37,18 +40,22 @@ public void onAttachedToEngine(@NonNull FlutterPluginBinding binding) {
     this.bluetoothManager = 
       (BluetoothManager) context.getSystemService(Context.BLUETOOTH_SERVICE);
 
+    // Attach this plugin to the Flutter environment
     methodChannel = new MethodChannel(messenger, METHOD_NAME);
     methodChannel.setMethodCallHandler(this);
 
+    // GattServerManager and BleManager (BLE)
     gattServerManager = new GattServerManager(context);
     bleManager = new BleManager();
 
+    // WifiAdHocManager (Wi-Fi Direct)
     WifiAdHocManager = new WifiAdHocManager(context);
     WifiAdHocManager.initMethodCallHandler(messenger);
   }
 
   @Override
   public void onMethodCall(@NonNull MethodCall call, @NonNull Result result) {
+    // Method that communicate with the Flutter client (Platform Channel)
     switch (call.method) {
       case "setVerbose":
         final boolean verbose = call.arguments();

android/src/main/java/com/montefiore/thaidinhle/adhoc_plugin/ble/BleManager.java

@@ -10,6 +10,9 @@
 
 import java.util.UUID;
 
+/**
+ * Class managing the peripheral role in Bluetooth Low Energy.
+ */
 public class BleManager {
     private static final String TAG = "[AdHocPlugin][BleManager]";
 
@@ -19,13 +22,17 @@ public class BleManager {
     private boolean verbose;
     private String initialName;
 
+    /**
+     * Default constructor
+     */
     public BleManager() {
         this.verbose = false;
         this.bluetoothAdapter = BluetoothAdapter.getDefaultAdapter();
         this.bluetoothLeAdvertiser = bluetoothAdapter.getBluetoothLeAdvertiser();
         this.initialName = bluetoothAdapter.getName();
     }
 
+    // Interface callback for notification about the discovery mode (advertisement)
     private AdvertiseCallback advertiseCallback = new AdvertiseCallback() {
         @Override
         public void onStartFailure (int errorCode) {
@@ -42,9 +49,13 @@ public void onStartSuccess (AdvertiseSettings settingsInEffect) {
         }
     };
 
+    /**
+     * Method allowing to start the advertisement process (discovery mode enable).
+     */
     public void startAdvertise() {
         if (verbose) Log.d(TAG, "startAdvertise()");
 
+        // Building the advertisement packet
         AdvertiseData data = new AdvertiseData.Builder()
             .addServiceUuid(new ParcelUuid(UUID.fromString(BleUtils.SERVICE_UUID)))
             .setIncludeDeviceName(true)
@@ -62,38 +73,76 @@ public void startAdvertise() {
                 return;
         }
 
+        // Start advertisement
         bluetoothLeAdvertiser.startAdvertising(settings, data, advertiseCallback);
     }
 
+    /**
+     * Method allowing to stop the advertisement process.
+     */
     public void stopAdvertise() {
         if (verbose) Log.d(TAG, "stopAdvertise()");
 
         if (bluetoothLeAdvertiser != null)
             bluetoothLeAdvertiser.stopAdvertising(advertiseCallback);
     }
 
+    /** 
+     * Method allowing to update the verbose/debug mode.
+     * 
+     * @param verbose   Boolean value representing the sate of the verbose/debug 
+     *                  mode.
+     */
     public void setVerbose(boolean verbose) {
         this.verbose = verbose;
     }
 
+    /**
+     * Method allowing to reset the name of the device Wi-Fi adapter.
+     * 
+     * @return true if it has been reset, otherwise false.
+     */
     public boolean resetDeviceName() {
         if (initialName != null)
             return bluetoothAdapter.setName(initialName);
         return false;
     }
 
+    /**
+     * Method allowing to update the device Wi-Fi adapter name.
+     *
+     * @param name  String value representing the new name of the device Wi-Fi 
+     *              adapter.
+     *
+     * @return true if the name was set, otherwise false.
+     */
     public boolean updateDeviceName(String name) {
         return bluetoothAdapter.setName(name);
     }
 
+    /**
+     * Method allowing to get the Bluetooth adapter name.
+     * 
+     * @return String value representing the name of the adapter.
+     */
     public String getAdapterName() {
         return bluetoothAdapter.getName();
     }
 
+    /**
+     * Method allowing to enable the Bluetooth adapter.
+     * 
+     * @return true if it has been enabled, otherwise false.
+     */
     public boolean enable() {
         return bluetoothAdapter.enable();
     }
 
+    /**
+     * Method allowing to disable the Bluetooth adapter.
+     * 
+     * @return true if it has been disable, otherwise false.
+     */
     public boolean disable() {
         return bluetoothAdapter.disable();
     }

android/src/main/java/com/montefiore/thaidinhle/adhoc_plugin/ble/BleUtils.java

@@ -2,23 +2,37 @@
 
 import android.bluetooth.BluetoothAdapter;
 
+/**
+ * Miscellaneous class for Bluetooth Low Energy.
+ */
 public class BleUtils {
+    // Gatt service and characteristic UUID
     public static final String SERVICE_UUID = "00000001-0000-1000-8000-00805f9b34fb";
     public static final String CHARACTERISTIC_UUID = "00000002-0000-1000-8000-00805f9b34fb";
-
+    // Minimum Bluetooth Low Energy mtu
     public static final byte MIN_MTU = 20;
-
+    // TAG for data fragmentation
     public static final byte MESSAGE_END = 0;
     public static final byte MESSAGE_FRAG = 1;
-
+    // TAG for connection state with a remote peer
     public static final byte STATE_DISCONNECTED = 0;
     public static final byte STATE_CONNECTED = 1;
 
+    /**
+     * Static method allowing to get the current name of the Bluetooth adapter.
+     * 
+     * @return String value representing the adapter name.
+     */
     public static String getCurrentName() {
         BluetoothAdapter mBluetoothAdapter = BluetoothAdapter.getDefaultAdapter();
         return (mBluetoothAdapter != null) ? mBluetoothAdapter.getName() : null;
     }
 
+    /**
+     * Static method allowing to check whether the Bluetooth adapter is enabled
+     * 
+     * @return true if it is, otherwise false.
+     */
     public static boolean isEnabled() {
         return BluetoothAdapter.getDefaultAdapter() != null && BluetoothAdapter.getDefaultAdapter().isEnabled();
     }