Add RemoteConference javadocs.
Bug: 21066411
Change-Id: Ie4cdfef58e6442531c3377cec4a708d67b790945
diff --git a/telecomm/java/android/telecom/RemoteConference.java b/telecomm/java/android/telecom/RemoteConference.java
index a76bf59..b59584b 100644
--- a/telecomm/java/android/telecom/RemoteConference.java
+++ b/telecomm/java/android/telecom/RemoteConference.java
@@ -29,7 +29,10 @@
import java.util.concurrent.CopyOnWriteArraySet;
/**
- * Represents a conference call which can contain any number of {@link Connection} objects.
+ * A conference provided to a {@link ConnectionService} by another {@code ConnectionService}
+ * running in a different process.
+ *
+ * @see ConnectionService#onRemoteConferenceAdded
*/
public final class RemoteConference {
@@ -62,18 +65,18 @@
private DisconnectCause mDisconnectCause;
private int mConnectionCapabilities;
- /** {@hide} */
+ /** @hide */
RemoteConference(String id, IConnectionService connectionService) {
mId = id;
mConnectionService = connectionService;
}
- /** {@hide} */
+ /** @hide */
String getId() {
return mId;
}
- /** {@hide} */
+ /** @hide */
void setDestroyed() {
for (RemoteConnection connection : mChildConnections) {
connection.setConference(null);
@@ -90,7 +93,7 @@
}
}
- /** {@hide} */
+ /** @hide */
void setState(final int newState) {
if (newState != Connection.STATE_ACTIVE &&
newState != Connection.STATE_HOLDING &&
@@ -116,7 +119,7 @@
}
}
- /** {@hide} */
+ /** @hide */
void addConnection(final RemoteConnection connection) {
if (!mChildConnections.contains(connection)) {
mChildConnections.add(connection);
@@ -134,7 +137,7 @@
}
}
- /** {@hide} */
+ /** @hide */
void removeConnection(final RemoteConnection connection) {
if (mChildConnections.contains(connection)) {
mChildConnections.remove(connection);
@@ -152,7 +155,7 @@
}
}
- /** {@hide} */
+ /** @hide */
void setConnectionCapabilities(final int connectionCapabilities) {
if (mConnectionCapabilities != connectionCapabilities) {
mConnectionCapabilities = connectionCapabilities;
@@ -187,7 +190,7 @@
}
}
- /** {@hide} */
+ /** @hide */
void setDisconnected(final DisconnectCause disconnectCause) {
if (mState != Connection.STATE_DISCONNECTED) {
mDisconnectCause = disconnectCause;
@@ -205,18 +208,37 @@
}
}
+ /**
+ * Returns the list of {@link RemoteConnection}s contained in this conference.
+ *
+ * @return A list of child connections.
+ */
public final List<RemoteConnection> getConnections() {
return mUnmodifiableChildConnections;
}
+ /**
+ * Gets the state of the conference call. See {@link Connection} for valid values.
+ *
+ * @return A constant representing the state the conference call is currently in.
+ */
public final int getState() {
return mState;
}
+ /**
+ * Returns the capabilities of the conference. See {@code CAPABILITY_*} constants in class
+ * {@link Connection} for valid values.
+ *
+ * @return A bitmask of the capabilities of the conference call.
+ */
public final int getConnectionCapabilities() {
return mConnectionCapabilities;
}
+ /**
+ * Disconnects the conference call as well as the child {@link RemoteConnection}s.
+ */
public void disconnect() {
try {
mConnectionService.disconnect(mId);
@@ -224,6 +246,13 @@
}
}
+ /**
+ * Removes the specified {@link RemoteConnection} from the conference. This causes the
+ * {@link RemoteConnection} to become a standalone connection. This is a no-op if the
+ * {@link RemoteConnection} does not belong to this conference.
+ *
+ * @param connection The remote-connection to remove.
+ */
public void separate(RemoteConnection connection) {
if (mChildConnections.contains(connection)) {
try {
@@ -233,6 +262,16 @@
}
}
+ /**
+ * Merges all {@link RemoteConnection}s of this conference into a single call. This should be
+ * invoked only if the conference contains the capability
+ * {@link Connection#CAPABILITY_MERGE_CONFERENCE}, otherwise it is a no-op. The presence of said
+ * capability indicates that the connections of this conference, despite being part of the
+ * same conference object, are yet to have their audio streams merged; this is a common pattern
+ * for CDMA conference calls, but the capability is not used for GSM and SIP conference calls.
+ * Invoking this method will cause the unmerged child connections to merge their audio
+ * streams.
+ */
public void merge() {
try {
mConnectionService.mergeConference(mId);
@@ -240,6 +279,15 @@
}
}
+ /**
+ * Swaps the active audio stream between the conference's child {@link RemoteConnection}s.
+ * This should be invoked only if the conference contains the capability
+ * {@link Connection#CAPABILITY_SWAP_CONFERENCE}, otherwise it is a no-op. This is only used by
+ * {@link ConnectionService}s that create conferences for connections that do not yet have
+ * their audio streams merged; this is a common pattern for CDMA conference calls, but the
+ * capability is not used for GSM and SIP conference calls. Invoking this method will change the
+ * active audio stream to a different child connection.
+ */
public void swap() {
try {
mConnectionService.swapConference(mId);
@@ -247,6 +295,9 @@
}
}
+ /**
+ * Puts the conference on hold.
+ */
public void hold() {
try {
mConnectionService.hold(mId);
@@ -254,6 +305,9 @@
}
}
+ /**
+ * Unholds the conference call.
+ */
public void unhold() {
try {
mConnectionService.unhold(mId);
@@ -261,10 +315,22 @@
}
}
+ /**
+ * Returns the {@link DisconnectCause} for the conference if it is in the state
+ * {@link Connection#STATE_DISCONNECTED}. If the conference is not disconnected, this will
+ * return null.
+ *
+ * @return The disconnect cause.
+ */
public DisconnectCause getDisconnectCause() {
return mDisconnectCause;
}
+ /**
+ * Requests that the conference start playing the specified DTMF tone.
+ *
+ * @param digit The digit for which to play a DTMF tone.
+ */
public void playDtmfTone(char digit) {
try {
mConnectionService.playDtmfTone(mId, digit);
@@ -272,6 +338,11 @@
}
}
+ /**
+ * Stops the most recent request to play a DTMF tone.
+ *
+ * @see #playDtmfTone
+ */
public void stopDtmfTone() {
try {
mConnectionService.stopDtmfTone(mId);
@@ -279,6 +350,12 @@
}
}
+ /**
+ * Request to change the conference's audio routing to the specified state. The specified state
+ * can include audio routing (Bluetooth, Speaker, etc) and muting state.
+ *
+ * @see android.telecom.AudioState
+ */
public void setAudioState(AudioState state) {
try {
mConnectionService.onAudioStateChanged(mId, state);
@@ -286,14 +363,31 @@
}
}
+ /**
+ * Returns a list of independent connections that can me merged with this conference.
+ *
+ * @return A list of conferenceable connections.
+ */
public List<RemoteConnection> getConferenceableConnections() {
return mUnmodifiableConferenceableConnections;
}
+ /**
+ * Register a callback through which to receive state updates for this conference.
+ *
+ * @param callback The callback to notify of state changes.
+ */
public final void registerCallback(Callback callback) {
registerCallback(callback, new Handler());
}
+ /**
+ * Registers a callback through which to receive state updates for this conference.
+ * Callbacks will be notified using the specified handler, if provided.
+ *
+ * @param callback The callback to notify of state changes.
+ * @param handler The handler on which to execute the callbacks.
+ */
public final void registerCallback(Callback callback, Handler handler) {
unregisterCallback(callback);
if (callback != null && handler != null) {
@@ -301,6 +395,13 @@
}
}
+ /**
+ * Unregisters a previously registered callback.
+ *
+ * @see #registerCallback
+ *
+ * @param callback The callback to unregister.
+ */
public final void unregisterCallback(Callback callback) {
if (callback != null) {
for (CallbackRecord<Callback> record : mCallbackRecords) {