Merge "Add the abort API to ICallService implementations." into master-nova

3 files changed, 48 insertions, 16 deletions

diff --git a/telecomm/java/android/telecomm/CallService.java b/telecomm/java/android/telecomm/CallService.java
index 8767ffa..261de4c 100644
--- a/telecomm/java/android/telecomm/CallService.java
+++ b/telecomm/java/android/telecomm/CallService.java
@@ -60,8 +60,8 @@ public abstract class CallService extends Service {
                 case MSG_CALL:
                     call((CallInfo) msg.obj);
                     break;
-                case MSG_DISCONNECT:
-                    disconnect((String) msg.obj);
+                case MSG_ABORT:
+                    abort((String) msg.obj);
                     break;
                 case MSG_SET_INCOMING_CALL_ID:
                     SomeArgs args = (SomeArgs) msg.obj;
@@ -79,6 +79,9 @@ public abstract class CallService extends Service {
                 case MSG_REJECT:
                     reject((String) msg.obj);
                     break;
+                case MSG_DISCONNECT:
+                    disconnect((String) msg.obj);
+                    break;
                 default:
                     break;
             }
@@ -106,8 +109,8 @@ public abstract class CallService extends Service {
         }
 
         @Override
-        public void disconnect(String callId) {
-            mMessageHandler.obtainMessage(MSG_DISCONNECT, callId).sendToTarget();
+        public void abort(String callId) {
+            mMessageHandler.obtainMessage(MSG_ABORT, callId).sendToTarget();
         }
 
         @Override
@@ -127,6 +130,11 @@ public abstract class CallService extends Service {
         public void reject(String callId) {
             mMessageHandler.obtainMessage(MSG_REJECT, callId).sendToTarget();
         }
+
+        @Override
+        public void disconnect(String callId) {
+            mMessageHandler.obtainMessage(MSG_DISCONNECT, callId).sendToTarget();
+        }
     }
 
     // Only used internally by this class.
@@ -138,10 +146,11 @@ public abstract class CallService extends Service {
             MSG_SET_CALL_SERVICE_ADAPTER = 1,
             MSG_IS_COMPATIBLE_WITH = 2,
             MSG_CALL = 3,
-            MSG_DISCONNECT = 4,
+            MSG_ABORT = 4,
             MSG_SET_INCOMING_CALL_ID = 5,
             MSG_ANSWER = 6,
-            MSG_REJECT = 7;
+            MSG_REJECT = 7,
+            MSG_DISCONNECT = 8;
 
     /**
      * Message handler for consolidating binder callbacks onto a single thread.
@@ -180,7 +189,7 @@ public abstract class CallService extends Service {
     /**
      * Determines if the CallService can place the specified call. Response is sent via
      * {@link ICallServiceAdapter#setCompatibleWith}. When responding, the correct call ID must be
-     * specified.
+     * specified.  Only used in the context of outgoing calls and call switching (handoff).
      *
      * @param callInfo The details of the relevant call.
      */
@@ -192,18 +201,22 @@ public abstract class CallService extends Service {
      * dynamically extensible since call providers should be able to implement arbitrary
      * handle-calling systems.  See {@link #isCompatibleWith}. It is expected that the
      * call service respond via {@link ICallServiceAdapter#handleSuccessfulOutgoingCall(String)}
-     * if it can successfully make the call.
+     * if it can successfully make the call.  Only used in the context of outgoing calls.
      *
      * @param callInfo The details of the relevant call.
      */
     public abstract void call(CallInfo callInfo);
 
     /**
-     * Disconnects the specified call.
+     * Aborts the outgoing call attempt. Invoked in the unlikely event that Telecomm decides to
+     * abort an attempt to place a call.  Only ever be invoked after {@link #call} invocations.
+     * After this is invoked, Telecomm does not expect any more updates about the call and will
+     * actively ignore any such update. This is different from {@link #disconnect} where Telecomm
+     * expects confirmation via {@link #markCallAsDisconnected}.
      *
-     * @param callId The ID of the call to disconnect.
+     * @param callId The identifier of the call to abort.
      */
-    public abstract void disconnect(String callId);
+    public abstract void abort(String callId);
 
     /**
      * Receives a new call ID to use with an incoming call. Invoked by Telecomm after it is notified
@@ -236,4 +249,11 @@ public abstract class CallService extends Service {
      * @param callId The ID of the call.
      */
     public abstract void reject(String callId);
+
+    /**
+     * Disconnects the specified call.
+     *
+     * @param callId The ID of the call to disconnect.
+     */
+    public abstract void disconnect(String callId);
 }
diff --git a/telecomm/java/android/telecomm/CallState.java b/telecomm/java/android/telecomm/CallState.java
index d4a45f9..d699fbd 100644
--- a/telecomm/java/android/telecomm/CallState.java
+++ b/telecomm/java/android/telecomm/CallState.java
@@ -67,6 +67,7 @@ public enum CallState {
     /**
      * Indicates that the call was attempted (mostly in the context of outgoing, at least at the
      * time of writing) but cancelled before it was successfully connected.
+     * @hide
      */
     ABORTED;
 }
diff --git a/telecomm/java/android/telecomm/ICallService.aidl b/telecomm/java/android/telecomm/ICallService.aidl
index 382bdd5..c035262 100644
--- a/telecomm/java/android/telecomm/ICallService.aidl
+++ b/telecomm/java/android/telecomm/ICallService.aidl
@@ -49,7 +49,7 @@ oneway interface ICallService {
      * specified. It is expected that the call service respond within 500 milliseconds. Any response
      * that takes longer than 500 milliseconds will be treated as being incompatible.
      * TODO(santoscordon): 500 ms was arbitrarily chosen and must be confirmed before this
-     * API is made public.
+     * API is made public.  Only used in the context of outgoing calls and call switching (handoff).
      *
      * @param callInfo The details of the relevant call.
      */
@@ -61,7 +61,7 @@ oneway interface ICallService {
      * dynamically extensible since call providers should be able to implement arbitrary
      * handle-calling systems.  See {@link #isCompatibleWith}. It is expected that the
      * call service respond via {@link ICallServiceAdapter#handleSuccessfulOutgoingCall} if it can
-     * successfully make the call.
+     * successfully make the call.  Only used in the context of outgoing calls.
      * TODO(santoscordon): Figure out how a call service can short-circuit a failure to the adapter.
      *
      * @param callInfo The details of the relevant call.
@@ -69,11 +69,15 @@ oneway interface ICallService {
     void call(in CallInfo callInfo);
 
     /**
-     * Disconnects the call identified by callId.
+     * Aborts the outgoing call attempt. Invoked in the unlikely event that Telecomm decides to
+     * abort an attempt to place a call.  Only ever be invoked after {@link #call} invocations.
+     * After this is invoked, Telecomm does not expect any more updates about the call and will
+     * actively ignore any such update. This is different from {@link #disconnect} where Telecomm
+     * expects confirmation via {@link #markCallAsDisconnected}.
      *
-     * @param callId The identifier of the call to disconnect.
+     * @param callId The identifier of the call to abort.
      */
-    void disconnect(String callId);
+    void abort(String callId);
 
     /**
      * Receives a new call ID to use with an incoming call. Invoked by Telecomm after it is notified
@@ -107,4 +111,11 @@ oneway interface ICallService {
      * @param callId The ID of the call.
      */
     void reject(String callId);
+
+    /**
+     * Disconnects the call identified by callId.  Used for outgoing and incoming calls.
+     *
+     * @param callId The identifier of the call to disconnect.
+     */
+    void disconnect(String callId);
 }