From caef9170f5c3a396a1167184723b4a61d6c9191c Mon Sep 17 00:00:00 2001 From: niedev Date: Mon, 26 Oct 2020 10:09:09 +0100 Subject: [PATCH] Fixed documentation --- .../communicator/BluetoothCommunicator.java | 81 +++++++++++++------ .../communicator/BluetoothConnection.java | 26 +++--- .../BluetoothConnectionClient.java | 4 - .../BluetoothConnectionServer.java | 5 +- .../communicator/BluetoothMessage.java | 4 - .../com/bluetooth/communicator/Channel.java | 4 - .../bluetooth/communicator/ClientChannel.java | 4 - .../com/bluetooth/communicator/Message.java | 20 +++-- .../java/com/bluetooth/communicator/Peer.java | 52 ++++++++---- .../bluetooth/communicator/ServerChannel.java | 4 - .../communicator/tools/BluetoothTools.java | 1 + 11 files changed, 125 insertions(+), 80 deletions(-) diff --git a/app/src/main/java/com/bluetooth/communicator/BluetoothCommunicator.java b/app/src/main/java/com/bluetooth/communicator/BluetoothCommunicator.java index 716741d..20ed1c6 100644 --- a/app/src/main/java/com/bluetooth/communicator/BluetoothCommunicator.java +++ b/app/src/main/java/com/bluetooth/communicator/BluetoothCommunicator.java @@ -49,19 +49,21 @@ * It also automatically implements (they are active by default) reconnection in case of temporary connection loss, reliable message sending, * splitting and rebuilding of long messages, sending raw data in addition to text messages and a message queue in order to always send the messages (and always in the right order) * even in case of connection problems (they will be sent as soon as the connection is restored) - * + *

* First create a bluetooth communicator object, it is the object that handles all operations of bluetooth low energy library, if you want to manage * the bluetooth connections in multiple activities I suggest you to save this object as an attribute of a custom class that extends Application and * create a getter so you can access to bluetoothCommunicator from any activity or service with: - * + * 
{@code
  * ((custom class name) getApplication()).getBluetoothCommunicator();
+ * }
* Next step is to initialize bluetoothCommunicator, the parameters are: a context, the name by which the other devices will see us (limited to 18 characters * and can be only characters listed in BluetoothTools.getSupportedUTFCharacters(context) because the number of bytes for advertising beacon is limited) and the strategy * (for now the only supported strategy is BluetoothCommunicator.STRATEGY_P2P_WITH_RECONNECTION) - * + * 
{@code
  * bluetoothCommunicator = new BluetoothCommunicator(this, "device name", BluetoothCommunicator.STRATEGY_P2P_WITH_RECONNECTION);
+ * }
* Then add the bluetooth communicator callback, the callback will listen for all events of bluetooth communicator: - * + * 
{@code
  * bluetoothCommunicator.addCallback(new BluetoothCommunicator.Callback() {
  *     @Override
  *     public void onBluetoothLeNotSupported() {
@@ -149,11 +151,12 @@
  *         device has accepted your connection request and the connection is complete, from now on you
  *         can send messages or data (or disconnection request) to this peer until onDisconnected
  *
-           To send messages to all connected peers you need to create a message with a context, a header, represented by a single character string
- *         (you can use a header to distinguish between different types of messages, or you can ignore it and use a random
- *         character), the text of the message, or a series of bytes if you want to send any kind of data and the peer you want to send the message to
- *         (must be connected to avoid errors), example: new Message(context,"a","hello world",peer);
- *         If you want to send message to a specific peer you have to set the sender of the message with the corresponding peer.
+ *         To send messages to all connected peers you need to create a message with a context, a header, represented by a
+ *         single character string (you can use a header to distinguish between different types of messages, or you can ignore
+ *         it and use a random character), the text of the message, or a series of bytes if you want to send any kind of data
+ *         and the peer you want to send the message to (must be connected to avoid errors), example:
+ *         new Message(context,"a","hello world",peer); If you want to send message to a specific peer you have to set
+ *         the sender of the message with the corresponding peer.
  *
  *         To send disconnection request to connected peer you need to call bluetoothCommunicator.disconnect(peer);
  *     }
@@ -218,17 +221,20 @@
  *         (however the disconnection will be notified in onDisconnection)
  *     }
  * });
+ * }
* Finally you can start discovery and/or advertising: - * + * 
{@code
  * bluetoothCommunicator.startAdvertising();
  * bluetoothCommunicator.startDiscovery();
+ * }
* All other actions that can be done are explained with the comments in the code of callback I wrote before. - * + *

* To use this library add these permissions to your manifest: - * + * 
{@code
  * 
  * 
  * 
+ * }
*/ public class BluetoothCommunicator { // constants @@ -278,6 +284,7 @@ public class BluetoothCommunicator { /** * Constructor of BluetoothCommunicator + * * @param context * @param name the name by which the other devices will see us (limited to 18 characters * and can be only characters listed in BluetoothTools.getSupportedUTFCharacters(context) because the number of bytes for advertising beacon is limited) @@ -429,7 +436,8 @@ public void onScanFailed(int errorCode) { /** * Constructor of BluetoothCommunicator that adds a callback (it can also be added with addCallback - * @param context + * + * @param context context * @param name the name by which the other devices will see us (limited to 18 characters * and can be only characters listed in BluetoothTools.getSupportedUTFCharacters(context) because the number of bytes for advertising beacon is limited) * @param strategy (for now the only supported strategy is BluetoothCommunicator.STRATEGY_P2P_WITH_RECONNECTION) @@ -572,7 +580,7 @@ public void onDisconnectionFailed() { /** * This method start advertising, so this device can be discovered by other devices that use this library and can receive a connection request, * this method will eventually turn on bluetooth if it is off (BluetoothCommunicator will restore bluetooth status when both advertising and discovery are stopped) - * + *

* This method must always be done from the main thread or it will return NOT_MAIN_THREAD without doing anything. * * @return SUCCESS if everithing is OK, ALREADY_STARTED if BluetoothCommunicator is already advertising, NOT_MAIN_THREAD if this method is not called @@ -650,7 +658,7 @@ private int executeStartAdvertising() { /** * This method stop advertising, this method will eventually turn off bluetooth if BluetoothCommunicator turned on before and if discovery is off - * + *

* This method must always be done from the main thread or it will return NOT_MAIN_THREAD without doing anything. * * @return SUCCESS if everithing is OK, ALREADY_STOPPED if BluetoothCommunicator is not advertising, NOT_MAIN_THREAD if this method is not called @@ -712,6 +720,7 @@ private int executeStopAdvertising() { /** * This method will check if BluetoothLe is supported by the device (rarely it can indicate a general bluetooth error, not an incompatibility with bluetooth le) + * * @return SUCCESS if bluetooth le is supported, BLUETOOTH_LE_NOT_SUPPORTED if not (or rarely if we had a generic bluetooth problem) */ public int isBluetoothLeSupported() { @@ -725,7 +734,7 @@ public int isBluetoothLeSupported() { /** * This method start discovery so BluetoothCommunicator can discover advertising devices and notify them with onPeerFound, * this method will eventually turn on bluetooth if it is off (BluetoothCommunicator will restore bluetooth status when both advertising and discovery are stopped) - * + *

* This method must always be done from the main thread or it will return NOT_MAIN_THREAD without doing anything. * * @return SUCCESS if everithing is OK, ALREADY_STARTED if BluetoothCommunicator is already advertising, NOT_MAIN_THREAD if this method is not called @@ -799,7 +808,7 @@ private int executeStartDiscovery() { /** * This method stop discovery, this method will eventually turn off bluetooth if BluetoothCommunicator turned on before and if advertising is off - * + *

* This method must always be done from the main thread or it will return NOT_MAIN_THREAD without doing anything. * * @return SUCCESS if everithing is OK, ALREADY_STOPPED if BluetoothCommunicator is not discovering, NOT_MAIN_THREAD if this method is not called @@ -858,6 +867,7 @@ private int executeStopDiscovery() { /** * This method will send the text contained in message to the peer contained in the receiver attribute of the message (only if that peer is connected), if receiver is not set * the message will be sent to all the connected peers + * * @param message message to be sent */ public void sendMessage(final Message message) { @@ -897,6 +907,7 @@ public void onMessageSent() { // means that we have sent the message to all th /** * This method will send the data contained in message to the peer contained in the receiver attribute of the message (only if that peer is connected), if receiver is not set * the message will be sent to all the connected peers + * * @param data message to be sent */ public void sendData(final Message data) { @@ -937,9 +948,10 @@ public void onMessageSent() { // means that we have sent the message to all th * this method set the name with which you would be seen by other devices, the name must be limited to 18 characters * and can be only characters listed in BluetoothTools.getSupportedUTFCharacters(context) because the number of bytes for advertising beacon is limited, * there is no controls for this so if you not follow these restrictions BluetoothCommunicator will not work correctly. - * + *

* To the name will be added 4 random symbols in a completely transparent way (this 4 symbols will exixts only inside BluetoothCommunicator, which removes them before the name gets on the outside), * this allows to have a unique identification (for BluetoothCommunicator, not for the user) even for peers with the same name + * * @param name * @return SUCCESS if bluetooth le is supported by the device or BLUETOOTH_LE_NOT_SUPPORTED if not (or rarely if we had a generic bluetooth problem) */ @@ -981,6 +993,7 @@ public ArrayList getConnectedPeersList() { /** * This method must be used after you have received a connection request to accept it and complete the connection (the connection is complete when * onConnectionSuccess is called) + * * @param peer the peer that has sent the connection request that we want to accept * @return SUCCESS if bluetooth le is supported by the device or BLUETOOTH_LE_NOT_SUPPORTED if not (or rarely if we had a generic bluetooth problem) */ @@ -994,7 +1007,8 @@ public int acceptConnection(Peer peer) { } /** - * This method must be used after you have received a connection request to reject it and cancel the connection + * This method must be used after you have received a connection request to reject it and cancel the connection. + * * @param peer the peer that has sent the connection request that you want to accept * @return SUCCESS if bluetooth le is supported by the device or BLUETOOTH_LE_NOT_SUPPORTED if not (or rarely if we had a generic bluetooth problem) */ @@ -1009,6 +1023,7 @@ public int rejectConnection(Peer peer) { /** * This method is used to know if BluetoothCommunicator is advertising + * * @return advertising */ public boolean isAdvertising() { @@ -1026,7 +1041,8 @@ public boolean isDiscovering() { /** * This method must be used to send a connection request to a founded peer, successfully you can know if it has accepted or rejected the connection listening * onConnectionSuccess and onConnectionFailed - * @param peer + * + * @param peer found peer you want to connect with * @return SUCCESS if everything is gone OK, BLUETOOTH_LE_NOT_SUPPORTED if bluetooth le is not supported (or rarely if we had a generic bluetooth problem) * or DESTROYING if destroy() is called before */ @@ -1055,6 +1071,7 @@ public int readPhy(Peer peer) { /** * This method return the bluetooth adapter used by BluetoothCommunicator + * * @return bluetoothAdapter */ public BluetoothAdapter getBluetoothAdapter() { @@ -1066,8 +1083,9 @@ public BluetoothAdapter getBluetoothAdapter() { * when onDisconnected is called with that peer as argument, in case the disconnection fails onDisconnectionFailed is called but if you not * override it or leave the call to super BluetoothCommunicator will turn off and on bluetooth to force the disconnection and onDisconnection will be * called. - * @param peer - * @return + * + * @param peer connected peer you want to disconnect from + * @return SUCCESS if bluetooth le is supported by the device or BLUETOOTH_LE_NOT_SUPPORTED if not (or rarely if we had a generic bluetooth problem) */ public int disconnect(final Peer peer) { synchronized (bluetoothLock) { @@ -1089,6 +1107,7 @@ public int disconnect(final Peer peer) { /** * This method will call disconnect for all the connected peers + * * @return SUCCESS if bluetooth le is supported by the device or BLUETOOTH_LE_NOT_SUPPORTED if not (or rarely if we had a generic bluetooth problem) */ public int disconnectFromAll() { @@ -1124,10 +1143,19 @@ public interface DestroyCallback { } + /** + * With this method you can add the callback for listening all the events of BluetoothCommunicator + * + * @param callback callback for listening all the events of BluetoothCommunicator + */ public void addCallback(Callback callback) { clientCallbacks.add(callback); } + /** + * This remote will remove the callback you pass as argument from the list of callback of this class, so this callback will not receive method call anymore + * @param callback callback for listening all the events of BluetoothCommunicator + */ public void removeCallback(Callback callback) { clientCallbacks.remove(callback); } @@ -1320,12 +1348,13 @@ public void onDiscoveryStopped() { /** * Notify that a Peer is found with the discovery. - * + *

* Here for example you can save peer in a list or anywhere you want and when the user * choose a peer you can call bluetoothCommunicator.connect(peer founded) but if you want to * use a peer for connect you have to have peer updated (see onPeerUpdated or onPeerLost), if you use a * non updated peer the connection might fail - * instead if you want to immediate connect where peer is found you can call bluetoothCommunicator.connect(peer) here + * instead if you want to immediate connect where peer is found you can call bluetoothCommunicator.connect(peer) here. + * * @param peer founded peer */ public void onPeerFound(Peer peer) { @@ -1333,8 +1362,9 @@ public void onPeerFound(Peer peer) { /** * Notify that a peer is out of range or has interrupted the advertise. + *

+ * Here you can delete the peer lost from a eventual collection of founded peers. * - * Here you can delete the peer lost from a eventual collection of founded peers * @param peer */ public void onPeerLost(Peer peer) { @@ -1342,6 +1372,7 @@ public void onPeerLost(Peer peer) { /** * Notify that a peer is disconnected, peersLeft indicate the number of connected peers remained + * * @param peer disconnected peer * @param peersLeft remaining peers connected */ diff --git a/app/src/main/java/com/bluetooth/communicator/BluetoothConnection.java b/app/src/main/java/com/bluetooth/communicator/BluetoothConnection.java index 360f0e2..40dd366 100644 --- a/app/src/main/java/com/bluetooth/communicator/BluetoothConnection.java +++ b/app/src/main/java/com/bluetooth/communicator/BluetoothConnection.java @@ -26,10 +26,7 @@ import java.util.ArrayList; import java.util.UUID; -/** - * This class is used only for the internal function of BluetoothCommunicator, there is no need to use this class, - * instead see the classes: BluetoothCommunicator, Peer, Message and BluetoothTools - */ + abstract class BluetoothConnection { //costanti public static final int ACCEPT = 0; @@ -312,6 +309,7 @@ public static class Callback { * It means you have received a connection request from another device (peer) (that have called connect) * for accept the connection request and start connection call bluetoothCommunicator.acceptConnection(peer); * for refusing call bluetoothCommunicator.rejectConnection(peer); (the peer must be the peer argument of onConnectionRequest). + * * @param peer the peer that have sent the connection request */ public void onConnectionRequest(Peer peer) { @@ -321,14 +319,15 @@ public void onConnectionRequest(Peer peer) { * This means that you have accepted the connection request using acceptConnection or the other * device has accepted your connection request and the connection is complete, from now on you * can send messages or data (or disconnection request) to this peer until onDisconnected. - * + *

* To send messages to all connected peers you need to create a message with a context, a header, represented by a single character string * (you can use a header to distinguish between different types of messages, or you can ignore it and use a random * character), the text of the message, or a series of bytes if you want to send any kind of data and the peer you want to send the message to * (must be connected to avoid errors), example: new Message(context,"a","hello world",peer); * If you want to send message to a specific peer you have to set the sender of the message with the corresponding peer. - * + *

* To send disconnection request to connected peer you need to call bluetoothCommunicator.disconnect(peer); + * * @param peer the peer with you have established the connection * @param source if in this connection you are a client (BluetoothCommunicator.CLIENT) or a server (BluetoothCommunicator.SERVER), it can be ignored. */ @@ -338,7 +337,8 @@ public void onConnectionSuccess(Peer peer, int source) { /** * This means that our connection request is rejected or has other problems, * to know the cause of the failure see errorCode (BluetoothCommunicator.CONNECTION_REJECTED - * means rejected connection and BluetoothCommunicator.ERROR means generic error) + * means rejected connection and BluetoothCommunicator.ERROR means generic error). + * * @param peer the peer with you have failed the connection * @param errorCode the core of the error for know if the cause is a rejection or a generic problem */ @@ -348,9 +348,10 @@ public void onConnectionFailed(Peer peer, int errorCode) { /** * This means that a connected peer has lost the connection with you and the library is trying * to restore it, in this case you can update the gui to notify this problem. - * + *

* You can still send messages in this situation, all sent messages are put in a queue * and sent as soon as the connection is restored. + * * @param peer the peer with you have lost the connection */ public void onConnectionLost(Peer peer) { @@ -358,6 +359,7 @@ public void onConnectionLost(Peer peer) { /** * Means that connection lost is resumed successfully. + * * @param peer */ public void onConnectionResumed(Peer peer) { @@ -367,6 +369,7 @@ public void onConnectionResumed(Peer peer) { * Means that you have received a message containing TEXT, to know the sender you can call message.getSender() that return * the peer that have sent the message, you can ignore source, it indicate only if you have received the message * as client or as server. + * * @param message received text message * @param source indicate only if you have received the message as clients or as servers, it can be ignored */ @@ -377,6 +380,7 @@ public void onMessageReceived(Message message, int source) { * Means that you have received a message containing DATA, to know the sender you can call message.getSender() that return * the peer that have sent the message, you can ignore source, it indicate only if you have received the message * as client or as server. + * * @param data received data message * @param source indicate only if you have received the message as clients or as servers, it can be ignored */ @@ -386,9 +390,10 @@ public void onDataReceived(Message data, int source) { /** * It means that a founded peer (or connected peer) has changed (name or address or other things), * if you have a collection of founded peers, you need to replace peer with newPeer if you want to connect successfully to that peer. - * + *

* In case the peer updated is connected and you have saved connected peers you have to update the peer if you want to successfully * send a message or a disconnection request to that peer. + * * @param peer * @param newPeer */ @@ -397,8 +402,9 @@ public void onPeerUpdated(Peer peer, Peer newPeer) { /** * This method is only for internal usage, do not override it. + *

+ * Instead override onDisconnected(Peer peer, int peersLeft). * - * Instead override onDisconnected(Peer peer, int peersLeft) * @param peer */ void onDisconnected(Peer peer) { diff --git a/app/src/main/java/com/bluetooth/communicator/BluetoothConnectionClient.java b/app/src/main/java/com/bluetooth/communicator/BluetoothConnectionClient.java index cd61b4a..cf2271e 100644 --- a/app/src/main/java/com/bluetooth/communicator/BluetoothConnectionClient.java +++ b/app/src/main/java/com/bluetooth/communicator/BluetoothConnectionClient.java @@ -37,10 +37,6 @@ import java.nio.charset.StandardCharsets; import java.util.ArrayList; -/** - * This class is used only for the internal function of BluetoothCommunicator, there is no need to use this class, - * instead see the classes: BluetoothCommunicator, Peer, Message and BluetoothTools - */ class BluetoothConnectionClient extends BluetoothConnection { private BluetoothGattCallback channelsCallback; private ConnectionDeque pendingConnections = new ConnectionDeque(); diff --git a/app/src/main/java/com/bluetooth/communicator/BluetoothConnectionServer.java b/app/src/main/java/com/bluetooth/communicator/BluetoothConnectionServer.java index 8670992..b69467f 100644 --- a/app/src/main/java/com/bluetooth/communicator/BluetoothConnectionServer.java +++ b/app/src/main/java/com/bluetooth/communicator/BluetoothConnectionServer.java @@ -37,10 +37,7 @@ import java.util.ArrayList; import java.util.UUID; -/** - * This class is used only for the internal function of BluetoothCommunicator, there is no need to use this class, - * instead see the classes: BluetoothCommunicator, Peer, Message and BluetoothTools - */ + class BluetoothConnectionServer extends BluetoothConnection { //costants public static final UUID CONNECTION_REQUEST_UUID = UUID.fromString("fa87c0d0-afac-11de-8a39-0857350c7a66"); diff --git a/app/src/main/java/com/bluetooth/communicator/BluetoothMessage.java b/app/src/main/java/com/bluetooth/communicator/BluetoothMessage.java index 672d389..c02fd17 100644 --- a/app/src/main/java/com/bluetooth/communicator/BluetoothMessage.java +++ b/app/src/main/java/com/bluetooth/communicator/BluetoothMessage.java @@ -28,10 +28,6 @@ import java.nio.charset.StandardCharsets; import java.util.ArrayList; -/** - * This class is used only for the internal function of BluetoothCommunicator, there is no need to use this class, - * instead see the classes: BluetoothCommunicator, Peer, Message and BluetoothTools - */ class BluetoothMessage implements Parcelable { public static final int ID_LENGTH = 4; public static final int SEQUENCE_NUMBER_LENGTH = 3; diff --git a/app/src/main/java/com/bluetooth/communicator/Channel.java b/app/src/main/java/com/bluetooth/communicator/Channel.java index 271768e..62e13db 100644 --- a/app/src/main/java/com/bluetooth/communicator/Channel.java +++ b/app/src/main/java/com/bluetooth/communicator/Channel.java @@ -30,10 +30,6 @@ import java.util.ArrayDeque; import java.util.ArrayList; -/** - * This class is used only for the internal function of BluetoothCommunicator, there is no need to use this class, - * instead see the classes: BluetoothCommunicator, Peer, Message and BluetoothTools - */ abstract class Channel { //timeouts of timers private final int RECONNECTION_TIMEOUT = 30000; diff --git a/app/src/main/java/com/bluetooth/communicator/ClientChannel.java b/app/src/main/java/com/bluetooth/communicator/ClientChannel.java index 8ef0f2b..5bd0dff 100644 --- a/app/src/main/java/com/bluetooth/communicator/ClientChannel.java +++ b/app/src/main/java/com/bluetooth/communicator/ClientChannel.java @@ -29,10 +29,6 @@ import java.nio.charset.StandardCharsets; -/** - * This class is used only for the internal function of BluetoothCommunicator, there is no need to use this class, - * instead see the classes: BluetoothCommunicator, Peer, Message and BluetoothTools - */ class ClientChannel extends Channel { private BluetoothGatt bluetoothGatt; diff --git a/app/src/main/java/com/bluetooth/communicator/Message.java b/app/src/main/java/com/bluetooth/communicator/Message.java index 542d05e..85bcf22 100644 --- a/app/src/main/java/com/bluetooth/communicator/Message.java +++ b/app/src/main/java/com/bluetooth/communicator/Message.java @@ -30,15 +30,15 @@ /** * Message is used to send and receive messages using BluetoothCommunicator, in practice this class is a container for the messages that will be sent and received. - * + *

* In order to send a message the message object must always contain a header and the text or data (if it will be sent via BluetoothCommunicator.sendMessage text will be sent, * if it will be sent via BluetoothCommunicator.sendData then data will be sent). * If you want to specify a peer to send the message to (by default it is sent to all) then the peer must be set as receiver, you can do it in the constructor or through the Message.setReceiver method. - * + *

* To send a message there is no need to set the sender because the latter will not be sent, the receiver will recognize the sender through the channel in which he will receive the message, * in any case it is something completely transparent. The sender is used only to identify the sender of received messages, and upon receipt of a message * via the BluetoothCommunicator.onMessageReceived or onDataReceived method the sender will have already been automatically inserted into the message by the library, along with the text / data and header. - * + *

* Another way you can use the Message class is to represent messages (graphically, to save them, etc.), some Message constructors would not make sense for sending or receiving messages, * but they can be useful for use as representation. */ @@ -160,6 +160,7 @@ public Message(Context context, @Nullable Peer sender, @NonNull byte[] data) { * Sets the header, the header is a single character that can be used to differentiate the types of message, * if you use a single type of message, just pick a random character for header and ignore it when receiving * text messages or data messages. + * * @param header must contain 1 character to avoid errors */ public void setHeader(String header) { @@ -183,11 +184,12 @@ public Peer getSender() { } /** - * Sets the sender. + * Sets the sender.
* To send a message there is no need to set the sender because the latter will not be sent, the receiver will recognize the sender through the channel in which he will receive the message, * in any case it is something completely transparent. The sender is used only to identify the sender of received messages, and upon receipt of a message * via the BluetoothCommunicator.onMessageReceived or onDataReceived method the sender will have already been automatically inserted into the message by the library, along with the text / data and header. - * A way this method can be useful is when you are using Message for representation (for the gui, for saving messages etc.) + * A way this method can be useful is when you are using Message for representation (for the gui, for saving messages etc.). + * * @param sender */ public void setSender(@Nullable Peer sender) { @@ -204,8 +206,9 @@ public Peer getReceiver() { } /** - * Sets the receiver. + * Sets the receiver.
* If you want to specify a peer to send the message to (by default it is sent to all) then the peer must be set as receiver, you can do it in the constructor or through the Message.setReceiver method. + * * @param receiver */ public void setReceiver(@Nullable Peer receiver) { @@ -214,6 +217,7 @@ public void setReceiver(@Nullable Peer receiver) { /** * Return the text of the message + * * @return text */ public String getText() { @@ -222,6 +226,7 @@ public String getText() { /** * Sets the text of the message + * * @param text */ public void setText(String text) { @@ -230,6 +235,7 @@ public void setText(String text) { /** * Return the data of the message + * * @return text */ public byte[] getData() { @@ -238,6 +244,7 @@ public byte[] getData() { /** * Sets the data of the message + * * @param data */ public void setData(byte[] data) { @@ -246,6 +253,7 @@ public void setData(byte[] data) { /** * This method is used only by the library, there is no need for you to use it because the split and the reassembly of a long message is handled by the library. + * * @param id * @return the message splitted in more BluetoothMessages (or converted in one BluetoothMessage if the message is short enough) */ diff --git a/app/src/main/java/com/bluetooth/communicator/Peer.java b/app/src/main/java/com/bluetooth/communicator/Peer.java index 8d305a5..30a55a2 100644 --- a/app/src/main/java/com/bluetooth/communicator/Peer.java +++ b/app/src/main/java/com/bluetooth/communicator/Peer.java @@ -30,11 +30,11 @@ /** * This class represents a device that we can find, with which we can establish a connection, and communicate (obviously in that order). - * + *

* Usually there is no need to create a peer, in fact we should start using it when it is found (BluetoothCommunicator.onPeerFound), later we can use the * found peer to request a connection (BluetoothCommunicator.connect) to the latter and if the peer accepts the connection request * (BluetoothCommunicator.onConnectionSuccess) then we can start exchanging messages with him and eventually make a disconnection. - * + *

* To understand if one peer is equivalent to another we should compare the uniqueName of the two peers, this is because the device * can vary over time and name could have a homonym. */ @@ -55,6 +55,7 @@ public class Peer implements Parcelable, Cloneable { /** * This constructor is used internally by BluetoothCommunicator, you shouldn't create a Peer but instead use the peers founded by * the discovery. + * * @param device * @param uniqueName * @param isConnected @@ -73,7 +74,8 @@ public Peer(BluetoothDevice device, String uniqueName, boolean isConnected) { } /** - * Copy constructor + * Copy constructor. + * * @param peer peer to copy */ public Peer(Peer peer) { @@ -92,7 +94,8 @@ public Peer(Peer peer) { /** * If obj is a Peer this method compare the address of the devices of the peers if they have one (if not it return false). * If obj is a Channel it will do the same comparison with the peer of that channel (this is only for internal usage) - * This method is for advanced usages, normally you should compare the uniqueName + * This method is for advanced usages, normally you should compare the uniqueName. + * * @param obj * @return true if equal false if not or missing attributes */ @@ -116,7 +119,8 @@ public boolean equals(Object obj) { } /** - * return the bluetooth device of the peer + * return the bluetooth device of the peer. + * * @return bluetooth device */ public BluetoothDevice getDevice() { @@ -126,8 +130,9 @@ public BluetoothDevice getDevice() { /** * Call bluetoothAdapter.getRemoteDevice() passing it the address of the device of this peer and return * what the method of getRemoteDevice return, this method is only for internal usage, you does't need to use it. + * * @param bluetoothAdapter - * @return + * @return remote device */ public BluetoothDevice getRemoteDevice(BluetoothAdapter bluetoothAdapter) { return bluetoothAdapter.getRemoteDevice(device.getAddress()); @@ -140,6 +145,7 @@ public BluetoothDevice getRemoteDevice(BluetoothAdapter bluetoothAdapter) { * are removed in the name, so the user of the library can ignore the uniqueName and use it only for know if a peer * matches another (the random characters are always the same, so if the name + the 4 random characters are equals * the two peers represents the same device. + * * @return unique name */ public String getUniqueName() { @@ -147,15 +153,17 @@ public String getUniqueName() { } /** - * Returns the normal name of the peer - * @return + * Returns the normal name of the peer. + * + * @return name */ public String getName() { return name; } /** - * Sets the bluetooth device for this peer + * Sets the bluetooth device for this peer. + * * @param device */ public void setDevice(BluetoothDevice device) { @@ -163,7 +171,8 @@ public void setDevice(BluetoothDevice device) { } /** - * Sets the unique name of this peer + * Sets the unique name of this peer. + * * @param uniqueName */ public void setUniqueName(@NonNull String uniqueName) { @@ -174,7 +183,8 @@ public void setUniqueName(@NonNull String uniqueName) { } /** - * Return the normal name of this peer + * Return the normal name of this peer. + * * @return name */ @NonNull @@ -194,12 +204,13 @@ public Object clone() { } /** - * Returns true if the peer is hardware connected to us. + * Returns true if the peer is hardware connected to us.
* For example this method returns false if this peer - * is connecter to us but has lost the connection and it is reconnecting, and return true if we have sent the + * is connected to us but has lost the connection and it is reconnecting, and return true if we have sent the * connection request to a peer but it hasn't answered yet, because for sending a connection request the devices has * to be already connected via hardware, but for the library they are not connected (when a peer refuse a connection - * request the hardware connection is interuupter too). + * request the hardware connection is interrupted too). + * * @return isHardwareConnected */ public boolean isHardwareConnected() { @@ -208,6 +219,7 @@ public boolean isHardwareConnected() { /** * Sets if the peer is hardware connected to us, this method should not be called by the user, but only from the library. + * * @param hardwareConnected */ public void setHardwareConnected(boolean hardwareConnected) { @@ -215,7 +227,8 @@ public void setHardwareConnected(boolean hardwareConnected) { } /** - * Returns true if this peer is connected to us + * Returns true if this peer is connected to us. + * * @return isConnected */ public boolean isConnected() { @@ -224,6 +237,7 @@ public boolean isConnected() { /** * Returns true if this peer is connected and is not reconnecting + * * @return (isConnected && !isReconnecting) */ public boolean isFullyConnected() { @@ -232,6 +246,7 @@ public boolean isFullyConnected() { /** * Sets if this peer is connected to us, this method should not be called by the user, but only from the library. + * * @param connected */ public void setConnected(boolean connected) { @@ -240,6 +255,7 @@ public void setConnected(boolean connected) { /** * Returns true if the peer is connected to us but has lost the connection and it is trying to reconnect + * * @return isReconnecting */ public boolean isReconnecting() { @@ -248,6 +264,7 @@ public boolean isReconnecting() { /** * Sets if this peer is trying to reconnect with us, this method should not be called by the user, but only from the library. + * * @param reconnecting * @param connected */ @@ -263,6 +280,7 @@ public void setReconnecting(boolean reconnecting, boolean connected) { /** * This method is for internal usage only + * * @param requestingReconnection */ public void setRequestingReconnection(boolean requestingReconnection) { @@ -273,6 +291,7 @@ public void setRequestingReconnection(boolean requestingReconnection) { /** * This method is for internal usage only + * * @return */ public boolean isRequestingReconnection() { @@ -281,6 +300,7 @@ public boolean isRequestingReconnection() { /** * Check if this peer is in the bonded devices of the phone + * * @param bluetoothAdapter * @return is bonded */ @@ -298,6 +318,7 @@ public boolean isBonded(BluetoothAdapter bluetoothAdapter) { /** * Returns true if the device is disconnecting from us + * * @return isDisconnecting */ public boolean isDisconnecting() { @@ -306,6 +327,7 @@ public boolean isDisconnecting() { /** * Sets if the devices is disconnecting from us, this method should not be called by the user, but only from the library. + * * @param disconnecting */ public void setDisconnecting(boolean disconnecting) { diff --git a/app/src/main/java/com/bluetooth/communicator/ServerChannel.java b/app/src/main/java/com/bluetooth/communicator/ServerChannel.java index 2ba7d0e..88bcd82 100644 --- a/app/src/main/java/com/bluetooth/communicator/ServerChannel.java +++ b/app/src/main/java/com/bluetooth/communicator/ServerChannel.java @@ -31,10 +31,6 @@ import java.nio.charset.StandardCharsets; import java.util.UUID; -/** - * This class is used only for the internal function of BluetoothCommunicator, there is no need to use this class, - * instead see the classes: BluetoothCommunicator, Peer, Message and BluetoothTools - */ class ServerChannel extends Channel { private BluetoothGattServer bluetoothGattServer; private BluetoothAdapter bluetoothAdapter; diff --git a/app/src/main/java/com/bluetooth/communicator/tools/BluetoothTools.java b/app/src/main/java/com/bluetooth/communicator/tools/BluetoothTools.java index b284cee..558bcb6 100644 --- a/app/src/main/java/com/bluetooth/communicator/tools/BluetoothTools.java +++ b/app/src/main/java/com/bluetooth/communicator/tools/BluetoothTools.java @@ -29,6 +29,7 @@ public class BluetoothTools { * to send to nearby devices) so ensure that the name that will be passed to BluetoothCommunicator in the * constructor o in setName contains only these character and not exceed 18 characters in length, otherwise * BluetoothCommunicator may not work correctly. + * * @param context * @return list of supported characters */