Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add RemoteConference javadocs.

Browse Source 
Bug: 21066411
Change-Id: Ie4cdfef58e6442531c3377cec4a708d67b790945
This commit is contained in:
Santos Cordon
2015-05-12 12:09:47 -07:00
parent a2f043822b
commit b804f8d8ff
2 changed files with 111 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
telecomm/java/android/telecom/RemoteConference.java
View File

@@ -29,7 +29,10 @@ import java.util.concurrent.CopyOnWriteArrayList;
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 @@ public final class RemoteConference {
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 @@ public final class RemoteConference {
}
}
/** {@hide} */
/** @hide */
void setState(final int newState) {
if (newState != Connection.STATE_ACTIVE &&
newState != Connection.STATE_HOLDING &&
@@ -116,7 +119,7 @@ public final class RemoteConference {
}
}
/** {@hide} */
/** @hide */
void addConnection(final RemoteConnection connection) {
if (!mChildConnections.contains(connection)) {
mChildConnections.add(connection);
@@ -134,7 +137,7 @@ public final class RemoteConference {
}
}
/** {@hide} */
/** @hide */
void removeConnection(final RemoteConnection connection) {
if (mChildConnections.contains(connection)) {
mChildConnections.remove(connection);
@@ -152,7 +155,7 @@ public final class RemoteConference {
}
}
/** {@hide} */
/** @hide */
void setConnectionCapabilities(final int connectionCapabilities) {
if (mConnectionCapabilities != connectionCapabilities) {
mConnectionCapabilities = connectionCapabilities;
@@ -187,7 +190,7 @@ public final class RemoteConference {
}
}
/** {@hide} */
/** @hide */
void setDisconnected(final DisconnectCause disconnectCause) {
if (mState != Connection.STATE_DISCONNECTED) {
mDisconnectCause = disconnectCause;
@@ -205,18 +208,37 @@ public final class RemoteConference {
}
}
/**
* 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 @@ public final class RemoteConference {
}
}
/**
* 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 @@ public final class RemoteConference {
}
}
/**
* 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 @@ public final class RemoteConference {
}
}
/**
* 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 @@ public final class RemoteConference {
}
}
/**
* Puts the conference on hold.
*/
public void hold() {
try {
mConnectionService.hold(mId);
@@ -254,6 +305,9 @@ public final class RemoteConference {
}
}
/**
* Unholds the conference call.
*/
public void unhold() {
try {
mConnectionService.unhold(mId);
@@ -261,10 +315,22 @@ public final class RemoteConference {
}
}
/**
* 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 @@ public final class RemoteConference {
}
}
/**
* Stops the most recent request to play a DTMF tone.
*
* @see #playDtmfTone
*/
public void stopDtmfTone() {
try {
mConnectionService.stopDtmfTone(mId);
@@ -279,6 +350,12 @@ public final class RemoteConference {
}
}
/**
* 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 @@ public final class RemoteConference {
}
}
/**
* 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 @@ public final class RemoteConference {
}
}
/**
* 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) {