* This class keeps track of the state changes in a call participant and updates its data model as needed. View classes * are expected to directly use the read-only data model. */ diff --git a/app/src/main/java/com/nextcloud/talk/call/CallParticipantList.java b/app/src/main/java/com/nextcloud/talk/call/CallParticipantList.java index 921900e7e..4a1c7370b 100644 --- a/app/src/main/java/com/nextcloud/talk/call/CallParticipantList.java +++ b/app/src/main/java/com/nextcloud/talk/call/CallParticipantList.java @@ -17,7 +17,7 @@ import java.util.Map; /** * Helper class to keep track of the participants in a call based on the signaling messages. - * + *
* The CallParticipantList adds a listener for participant list messages as soon as it is created and starts tracking * the call participants until destroyed. Notifications about the changes can be received by adding an observer to the * CallParticipantList; note that no sorting is guaranteed on the participants. diff --git a/app/src/main/java/com/nextcloud/talk/call/CallParticipantListNotifier.java b/app/src/main/java/com/nextcloud/talk/call/CallParticipantListNotifier.java index 2c0d16985..f02b300e0 100644 --- a/app/src/main/java/com/nextcloud/talk/call/CallParticipantListNotifier.java +++ b/app/src/main/java/com/nextcloud/talk/call/CallParticipantListNotifier.java @@ -15,7 +15,7 @@ import java.util.Set; /** * Helper class to register and notify CallParticipantList.Observers. - * + *
* This class is only meant for internal use by CallParticipantList; listeners must register themselves against * a CallParticipantList rather than against a CallParticipantListNotifier. */ diff --git a/app/src/main/java/com/nextcloud/talk/call/CallParticipantModel.java b/app/src/main/java/com/nextcloud/talk/call/CallParticipantModel.java index bd59a28e8..f5409ad33 100644 --- a/app/src/main/java/com/nextcloud/talk/call/CallParticipantModel.java +++ b/app/src/main/java/com/nextcloud/talk/call/CallParticipantModel.java @@ -17,23 +17,23 @@ import java.util.Objects; /** * Read-only data model for (remote) call participants. - * + *
* If the hand was never raised null is returned by "getRaisedHand()". Otherwise a RaisedHand object is returned with * the current state (raised or not) and the timestamp when the raised hand state last changed. - * + *
* The received audio and video are available only if the participant is sending them and also has them enabled. * Before a connection is established it is not known whether audio and video are available or not, so null is returned * in that case (therefore it should not be autoboxed to a plain boolean without checking that). - * + *
* Audio and video in screen shares, on the other hand, are always seen as available. - * + *
* Actor type and actor id will be set only in Talk >= 20. - * + *
* Clients of the model can observe it with CallParticipantModel.Observer to be notified when any value changes. * Getters called after receiving a notification are guaranteed to provide at least the value that triggered the * notification, but it may return even a more up to date one (so getting the value again on the following * notification may return the same value as before). - * + *
* Besides onChange(), which notifies about changes in the model values, CallParticipantModel.Observer provides * additional methods to be notified about one-time events that are not reflected in the model values, like reactions. */ @@ -169,11 +169,11 @@ public class CallParticipantModel { /** * Adds an observer to be notified when any value changes. - * + *
* The observer will be notified on the thread associated to the given handler. If no handler is given the * observer will be immediately notified on the same thread that changed the value; the observer will be * immediately notified too if the thread of the handler is the same thread that changed the value. - * + *
* An observer is expected to be added only once. If the same observer is added again it will be notified just * once on the thread of the last handler. * diff --git a/app/src/main/java/com/nextcloud/talk/call/MutableCallParticipantModel.java b/app/src/main/java/com/nextcloud/talk/call/MutableCallParticipantModel.java index 221b38352..c8bbdedce 100644 --- a/app/src/main/java/com/nextcloud/talk/call/MutableCallParticipantModel.java +++ b/app/src/main/java/com/nextcloud/talk/call/MutableCallParticipantModel.java @@ -13,7 +13,7 @@ import org.webrtc.PeerConnection; /** * Mutable data model for (remote) call participants. - * + *
* There is no synchronization when setting the values; if needed, it should be handled by the clients of the model. */ public class MutableCallParticipantModel extends CallParticipantModel { diff --git a/app/src/main/java/com/nextcloud/talk/signaling/LocalParticipantMessageNotifier.java b/app/src/main/java/com/nextcloud/talk/signaling/LocalParticipantMessageNotifier.java index f3fffbf75..154a1aa8b 100644 --- a/app/src/main/java/com/nextcloud/talk/signaling/LocalParticipantMessageNotifier.java +++ b/app/src/main/java/com/nextcloud/talk/signaling/LocalParticipantMessageNotifier.java @@ -12,7 +12,7 @@ import java.util.Set; /** * Helper class to register and notify LocalParticipantMessageListeners. - * + *
* This class is only meant for internal use by SignalingMessageReceiver; listeners must register themselves against * a SignalingMessageReceiver rather than against a LocalParticipantMessageNotifier. */ diff --git a/app/src/main/java/com/nextcloud/talk/signaling/OfferMessageNotifier.java b/app/src/main/java/com/nextcloud/talk/signaling/OfferMessageNotifier.java index b0dd8ba3b..f8947b539 100644 --- a/app/src/main/java/com/nextcloud/talk/signaling/OfferMessageNotifier.java +++ b/app/src/main/java/com/nextcloud/talk/signaling/OfferMessageNotifier.java @@ -12,7 +12,7 @@ import java.util.Set; /** * Helper class to register and notify OfferMessageListeners. - * + *
* This class is only meant for internal use by SignalingMessageReceiver; listeners must register themselves against * a SignalingMessageReceiver rather than against an OfferMessageNotifier. */ diff --git a/app/src/main/java/com/nextcloud/talk/signaling/ParticipantListMessageNotifier.java b/app/src/main/java/com/nextcloud/talk/signaling/ParticipantListMessageNotifier.java index c860574e1..fe8622f0e 100644 --- a/app/src/main/java/com/nextcloud/talk/signaling/ParticipantListMessageNotifier.java +++ b/app/src/main/java/com/nextcloud/talk/signaling/ParticipantListMessageNotifier.java @@ -15,7 +15,7 @@ import java.util.Set; /** * Helper class to register and notify ParticipantListMessageListeners. - * + *
* This class is only meant for internal use by SignalingMessageReceiver; listeners must register themselves against * a SignalingMessageReceiver rather than against a ParticipantListMessageNotifier. */ diff --git a/app/src/main/java/com/nextcloud/talk/signaling/SignalingMessageReceiver.java b/app/src/main/java/com/nextcloud/talk/signaling/SignalingMessageReceiver.java index 90f658f92..fb3e9c191 100644 --- a/app/src/main/java/com/nextcloud/talk/signaling/SignalingMessageReceiver.java +++ b/app/src/main/java/com/nextcloud/talk/signaling/SignalingMessageReceiver.java @@ -20,20 +20,20 @@ import java.util.Map; /** * Hub to register listeners for signaling messages of different kinds. - * + *
* In general, if a listener is added while an event is being handled the new listener will not receive that event. * An exception to that is adding a WebRtcMessageListener when handling an offer in an OfferMessageListener; in that * case the "onOffer()" method of the WebRtcMessageListener will be called for that same offer. - * + *
* Similarly, if a listener is removed while an event is being handled the removed listener will still receive that * event. Again the exception is removing a WebRtcMessageListener when handling an offer in an OfferMessageListener; in * that case the "onOffer()" method of the WebRtcMessageListener will not be called for that offer. - * + *
* Adding and removing listeners, as well as notifying them is internally synchronized. This should be kept in mind * if listeners are added or removed when handling an event to prevent deadlocks (nevertheless, just adding or * removing a listener in the same thread handling the event is fine, and in most cases it will be fine too if done * in a different thread, as long as the notifier thread is not forced to wait until the listener is added or removed). - * + *
* SignalingMessageReceiver does not fetch the signaling messages itself; subclasses must fetch them and then call * the appropriate protected methods to process the messages and notify the listeners. */ @@ -55,7 +55,7 @@ public abstract class SignalingMessageReceiver { /** * Listener for participant list messages. - * + *
* The messages are implicitly bound to the room currently joined in the signaling server; listeners are expected * to know the current room. */ @@ -63,17 +63,17 @@ public abstract class SignalingMessageReceiver { /** * List of all the participants in the room. - * + *
* This message is received only when the internal signaling server is used. - * + *
* The message is received periodically, and the participants may not have been modified since the last message. - * + *
* Only the following participant properties are set: * - inCall * - lastPing * - sessionId * - userId (if the participant is not a guest) - * + *
* "participantPermissions" is provided in the message (since Talk 13), but not currently set in the * participant. "publishingPermissions" was provided instead in Talk 12, but it was not used anywhere, so it is * ignored. @@ -84,25 +84,25 @@ public abstract class SignalingMessageReceiver { /** * List of all the participants in the call or the room (depending on what triggered the event). - * + *
* This message is received only when the external signaling server is used. - * + *
* The message is received when any participant changed, although what changed is not provided and should be * derived from the difference with previous messages. The list of participants may include only the * participants in the call (including those that just left it and thus triggered the event) or all the * participants currently in the room (participants in the room but not currently active, that is, without a * session, are not included). - * + *
* Only the following participant properties are set: * - inCall * - lastPing * - sessionId * - type * - userId (if the participant is not a guest) - * + *
* "nextcloudSessionId" is provided in the message (when the "inCall" property of any participant changed), but * not currently set in the participant. - * + *
* "participantPermissions" is provided in the message (since Talk 13), but not currently set in the * participant. "publishingPermissions" was provided instead in Talk 12, but it was not used anywhere, so it is * ignored. @@ -113,7 +113,7 @@ public abstract class SignalingMessageReceiver { /** * Update of the properties of all the participants in the room. - * + *
* This message is received only when the external signaling server is used. * * @param inCall the new value of the inCall property @@ -123,17 +123,17 @@ public abstract class SignalingMessageReceiver { /** * Listener for local participant messages. - * + *
* The messages are implicitly bound to the local participant (or, rather, its session); listeners are expected * to know the local participant. - * + *
* The messages are related to the conversation, so the local participant may or may not be in a call when they * are received. */ public interface LocalParticipantMessageListener { /** * Request for the client to switch to the given conversation. - * + *
* This message is received only when the external signaling server is used. * * @param token the token of the conversation to switch to. @@ -143,10 +143,10 @@ public abstract class SignalingMessageReceiver { /** * Listener for call participant messages. - * + *
* The messages are bound to a specific call participant (or, rather, session), so each listener is expected to * handle messages only for a single call participant. - * + *
* Although "unshareScreen" is technically bound to a specific peer connection it is instead treated as a general * message on the call participant. */ @@ -166,11 +166,11 @@ public abstract class SignalingMessageReceiver { /** * Listener for WebRTC offers. - * + *
* Unlike the WebRtcMessageListener, which is bound to a specific peer connection, an OfferMessageListener listens * to all offer messages, no matter which peer connection they are bound to. This can be used, for example, to * create a new peer connection when a remote offer for which there is no previous connection is received. - * + *
* When an offer is received all OfferMessageListeners are notified before any WebRtcMessageListener is notified. */ public interface OfferMessageListener { @@ -179,7 +179,7 @@ public abstract class SignalingMessageReceiver { /** * Listener for WebRTC messages. - * + *
* The messages are bound to a specific peer connection, so each listener is expected to handle messages only for * a single peer connection. */ @@ -192,7 +192,7 @@ public abstract class SignalingMessageReceiver { /** * Adds a listener for participant list messages. - * + *
* A listener is expected to be added only once. If the same listener is added again it will be notified just once. * * @param listener the ParticipantListMessageListener @@ -207,7 +207,7 @@ public abstract class SignalingMessageReceiver { /** * Adds a listener for local participant messages. - * + *
* A listener is expected to be added only once. If the same listener is added again it will be notified just once. * * @param listener the LocalParticipantMessageListener @@ -222,7 +222,7 @@ public abstract class SignalingMessageReceiver { /** * Adds a listener for call participant messages. - * + *
* A listener is expected to be added only once. If the same listener is added again it will no longer be notified * for the messages from the previous session ID. * @@ -247,7 +247,7 @@ public abstract class SignalingMessageReceiver { /** * Adds a listener for all offer messages. - * + *
* A listener is expected to be added only once. If the same listener is added again it will be notified just once. * * @param listener the OfferMessageListener @@ -262,7 +262,7 @@ public abstract class SignalingMessageReceiver { /** * Adds a listener for WebRTC messages from the given session ID and room type. - * + *
* A listener is expected to be added only once. If the same listener is added again it will no longer be notified * for the messages from the previous session ID or room type. * @@ -475,7 +475,7 @@ public abstract class SignalingMessageReceiver { /** * Creates and initializes a Participant from the data in the given map. - * + *
* Maps from internal and external signaling server messages can be used. Nevertheless, besides the differences * between the messages and the optional properties, it is expected that the message is correct and the given data * is parseable. Broken messages (for example, a string instead of an integer for "inCall" or a missing diff --git a/app/src/main/java/com/nextcloud/talk/webrtc/DataChannelMessageNotifier.java b/app/src/main/java/com/nextcloud/talk/webrtc/DataChannelMessageNotifier.java index a2f1b5f5e..2fca22ac8 100644 --- a/app/src/main/java/com/nextcloud/talk/webrtc/DataChannelMessageNotifier.java +++ b/app/src/main/java/com/nextcloud/talk/webrtc/DataChannelMessageNotifier.java @@ -12,7 +12,7 @@ import java.util.Set; /** * Helper class to register and notify DataChannelMessageListeners. - * + *
* This class is only meant for internal use by PeerConnectionWrapper; listeners must register themselves against * a PeerConnectionWrapper rather than against a DataChannelMessageNotifier. */ diff --git a/app/src/main/java/com/nextcloud/talk/webrtc/PeerConnectionNotifier.java b/app/src/main/java/com/nextcloud/talk/webrtc/PeerConnectionNotifier.java index ff0930c9c..cea2a8661 100644 --- a/app/src/main/java/com/nextcloud/talk/webrtc/PeerConnectionNotifier.java +++ b/app/src/main/java/com/nextcloud/talk/webrtc/PeerConnectionNotifier.java @@ -15,7 +15,7 @@ import java.util.Set; /** * Helper class to register and notify PeerConnectionObserver. - * + *
* This class is only meant for internal use by PeerConnectionWrapper; observers must register themselves against * a PeerConnectionWrapper rather than against a PeerConnectionNotifier. */