Merge CallControl#reject into CallControl#disconnect
API council reviewed CallControl and suggested that reject should be
merged into disconnect. After talking it over with the team, we decided
this was a good suggestion.
changes:
- CallControl#Reject API removed
- CallControl#Disconnect API only allows 3 disconnect codes
- Throw an IllegalArgumentException if the client passes an invalid code
- EndCallTransaction adjustments
bug: 265809508
Test: CTS
Change-Id: I2b11ad507a7c280e8447f069c1865f765991468c
diff --git a/telecomm/java/android/telecom/CallControl.java b/telecomm/java/android/telecom/CallControl.java
index 315ac67..f3c91f6 100644
--- a/telecomm/java/android/telecom/CallControl.java
+++ b/telecomm/java/android/telecom/CallControl.java
@@ -28,6 +28,7 @@
import android.os.ParcelUuid;
import android.os.RemoteException;
import android.os.ResultReceiver;
+import android.text.TextUtils;
import com.android.internal.telecom.ClientTransactionalServiceRepository;
import com.android.internal.telecom.ICallControl;
@@ -67,7 +68,7 @@
/**
* @return the callId Telecom assigned to this CallControl object which should be attached to
- * an individual call.
+ * an individual call.
*/
@NonNull
public ParcelUuid getCallId() {
@@ -78,9 +79,9 @@
* Request Telecom set the call state to active.
*
* @param executor The {@link Executor} on which the {@link OutcomeReceiver} callback
- * will be called on.
+ * will be called on.
* @param callback that will be completed on the Telecom side that details success or failure
- * of the requested operation.
+ * of the requested operation.
*
* {@link OutcomeReceiver#onResult} will be called if Telecom has successfully
* switched the call state to active
@@ -109,9 +110,9 @@
* but can be extended to setting a meeting to inactive.
*
* @param executor The {@link Executor} on which the {@link OutcomeReceiver} callback
- * will be called on.
+ * will be called on.
* @param callback that will be completed on the Telecom side that details success or failure
- * of the requested operation.
+ * of the requested operation.
*
* {@link OutcomeReceiver#onResult} will be called if Telecom has successfully
* switched the call state to inactive
@@ -136,23 +137,42 @@
}
/**
- * Request Telecom set the call state to disconnect.
+ * Request Telecom disconnect the call and remove the call from telecom tracking.
*
- * @param executor The {@link Executor} on which the {@link OutcomeReceiver} callback
- * will be called on.
- * @param callback that will be completed on the Telecom side that details success or failure
- * of the requested operation.
+ * @param disconnectCause represents the cause for disconnecting the call. The only valid
+ * codes for the {@link android.telecom.DisconnectCause} passed in are:
+ * <ul>
+ * <li>{@link DisconnectCause#LOCAL}</li>
+ * <li>{@link DisconnectCause#REMOTE}</li>
+ * <li>{@link DisconnectCause#REJECTED}</li>
+ * <li>{@link DisconnectCause#MISSED}</li>
+ * </ul>
*
- * {@link OutcomeReceiver#onResult} will be called if Telecom has successfully
- * disconnected the call.
+ * @param executor The {@link Executor} on which the {@link OutcomeReceiver} callback
+ * will be called on.
*
- * {@link OutcomeReceiver#onError} will be called if Telecom has failed to
- * disconnect the call. A {@link CallException} will be passed
- * that details why the operation failed.
+ * @param callback That will be completed on the Telecom side that details success or
+ * failure of the requested operation.
+ *
+ * {@link OutcomeReceiver#onResult} will be called if Telecom has
+ * successfully disconnected the call.
+ *
+ * {@link OutcomeReceiver#onError} will be called if Telecom has failed
+ * to disconnect the call. A {@link CallException} will be passed
+ * that details why the operation failed.
+ *
+ * <p>
+ * Note: After the call has been successfully disconnected, calling any CallControl API will
+ * result in the {@link OutcomeReceiver#onError} with
+ * {@link CallException#CODE_CALL_IS_NOT_BEING_TRACKED}.
*/
public void disconnect(@NonNull DisconnectCause disconnectCause,
@CallbackExecutor @NonNull Executor executor,
@NonNull OutcomeReceiver<Void, CallException> callback) {
+ Objects.requireNonNull(disconnectCause);
+ Objects.requireNonNull(executor);
+ Objects.requireNonNull(callback);
+ validateDisconnectCause(disconnectCause);
if (mServerInterface != null) {
try {
mServerInterface.disconnect(mCallId, disconnectCause,
@@ -166,35 +186,6 @@
}
/**
- * Request Telecom reject the incoming call.
- *
- * @param executor The {@link Executor} on which the {@link OutcomeReceiver} callback
- * will be called on.
- * @param callback that will be completed on the Telecom side that details success or failure
- * of the requested operation.
- *
- * {@link OutcomeReceiver#onResult} will be called if Telecom has successfully
- * rejected the incoming call.
- *
- * {@link OutcomeReceiver#onError} will be called if Telecom has failed to
- * reject the incoming call. A {@link CallException} will be passed
- * that details why the operation failed.
- */
- public void rejectCall(@CallbackExecutor @NonNull Executor executor,
- @NonNull OutcomeReceiver<Void, CallException> callback) {
- if (mServerInterface != null) {
- try {
- mServerInterface.rejectCall(mCallId,
- new CallControlResultReceiver("rejectCall", executor, callback));
- } catch (RemoteException e) {
- throw e.rethrowAsRuntimeException();
- }
- } else {
- throw new IllegalStateException(INTERFACE_ERROR_MSG);
- }
- }
-
- /**
* Request start a call streaming session. On receiving valid request, telecom will bind to
* the {@link CallStreamingService} implemented by a general call streaming sender. So that the
* call streaming sender can perform streaming local device audio to another remote device and
@@ -231,10 +222,10 @@
* requesting a change. Instead, the new endpoint should be one of the valid endpoints provided
* by {@link CallEventCallback#onAvailableCallEndpointsChanged(List)}.
*
- * @param callEndpoint ; The {@link CallEndpoint} to change to.
- * @param executor ; The {@link Executor} on which the {@link OutcomeReceiver} callback
+ * @param callEndpoint The {@link CallEndpoint} to change to.
+ * @param executor The {@link Executor} on which the {@link OutcomeReceiver} callback
* will be called on.
- * @param callback ; The {@link OutcomeReceiver} that will be completed on the Telecom side
+ * @param callback The {@link OutcomeReceiver} that will be completed on the Telecom side
* that details success or failure of the requested operation.
*
* {@link OutcomeReceiver#onResult} will be called if Telecom has
@@ -266,7 +257,9 @@
* Since {@link OutcomeReceiver}s cannot be passed via AIDL, a ResultReceiver (which can) must
* wrap the Clients {@link OutcomeReceiver} passed in and await for the Telecom Server side
* response in {@link ResultReceiver#onReceiveResult(int, Bundle)}.
- * @hide */
+ *
+ * @hide
+ */
private class CallControlResultReceiver extends ResultReceiver {
private final String mCallingMethod;
private final Executor mExecutor;
@@ -308,4 +301,18 @@
}
return new CallException(message, CallException.CODE_ERROR_UNKNOWN);
}
+
+ /** @hide */
+ private void validateDisconnectCause(DisconnectCause disconnectCause) {
+ final int code = disconnectCause.getCode();
+ if (code != DisconnectCause.LOCAL && code != DisconnectCause.REMOTE
+ && code != DisconnectCause.MISSED && code != DisconnectCause.REJECTED) {
+ throw new IllegalArgumentException(TextUtils.formatSimple(
+ "The DisconnectCause code provided, %d , is not a valid Disconnect code. Valid "
+ + "DisconnectCause codes are limited to [DisconnectCause.LOCAL, "
+ + "DisconnectCause.REMOTE, DisconnectCause.MISSED, or "
+ + "DisconnectCause.REJECTED]", disconnectCause.getCode()));
+ }
+ }
+
}