diff options
Diffstat (limited to 'telecomm/java/android/telecom/RemoteConference.java')
| -rw-r--r-- | telecomm/java/android/telecom/RemoteConference.java | 119 |
1 files changed, 110 insertions, 9 deletions
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.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) { |