Updates CallService API.

Adds additional parameters and a response method for
isCompatibleWith on ICallServiceAdapter.

Adds connectionStartTime to CallInfo.

Change-Id: I27a8d14c5c63d3f6a70a290ffb39d9f623d40a60

5 files changed, 115 insertions, 46 deletions

diff --git a/telecomm/java/android/telecomm/CallInfo.java b/telecomm/java/android/telecomm/CallInfo.java
index 8fe67a0..d964944 100644
--- a/telecomm/java/android/telecomm/CallInfo.java
+++ b/telecomm/java/android/telecomm/CallInfo.java
@@ -19,10 +19,13 @@ package android.telecomm;
 import android.os.Parcel;
 import android.os.Parcelable;
 
+import java.util.Date;
+
 /**
- *  A parcelable holder class of Call information data.
- *  TODO(santoscordon): Need final public-facing comments in this file.
- *  @hide
+ * A parcelable holder class of Call information data. This class is intended for transfering call
+ * information from Telecomm to call services and thus is read-only.
+ * TODO(santoscordon): Need final public-facing comments in this file.
+ * @hide
  */
 public final class CallInfo implements Parcelable {
 
@@ -30,14 +33,29 @@ public final class CallInfo implements Parcelable {
      * Endpoint to which the call is connected.
      * This could be the dialed value for outgoing calls or the caller id of incoming calls.
      */
-    private String handle;
+    private final String mHandle;
+
+    // There are 4 timestamps that are important to a call:
+    // 1) Created timestamp - The time at which the user explicitly chose to make the call.
+    // 2) Connected timestamp - The time at which a call service confirms that it has connected
+    //    this call. This happens through a method-call to either newOutgoingCall or newIncomingCall
+    //    on CallServiceAdapter. Generally this should coincide roughly to the user physically
+    //    hearing/seeing a ring.
+    //    TODO(santoscordon): Consider renaming Call-active to better match the others.
+    // 3) Call-active timestamp - The time at which the call switches to the active state. This
+    //    happens when the user answers an incoming call or an outgoing call was answered by the
+    //    other party.
+    // 4) Disconnected timestamp - The time at which the call was disconnected.
 
+    /**
+     * Persists handle of the other party of this call.
+     */
     public CallInfo(String handle) {
-        this.handle = handle;
+        mHandle = handle;
     }
 
     public String getHandle() {
-        return handle;
+        return mHandle;
     }
 
     //
@@ -47,8 +65,8 @@ public final class CallInfo implements Parcelable {
     /**
      * Responsible for creating CallInfo objects for deserialized Parcels.
      */
-    public static final Parcelable.Creator<CallInfo> CREATOR
-            = new Parcelable.Creator<CallInfo> () {
+    public static final Parcelable.Creator<CallInfo> CREATOR =
+            new Parcelable.Creator<CallInfo> () {
 
         @Override
         public CallInfo createFromParcel(Parcel source) {
@@ -74,6 +92,6 @@ public final class CallInfo implements Parcelable {
      */
     @Override
     public void writeToParcel(Parcel destination, int flags) {
-        destination.writeString(handle);
+        destination.writeString(mHandle);
     }
 }
diff --git a/telecomm/java/android/telecomm/CallService.java b/telecomm/java/android/telecomm/CallService.java
index 9c5af3d..1f47a0a 100644
--- a/telecomm/java/android/telecomm/CallService.java
+++ b/telecomm/java/android/telecomm/CallService.java
@@ -24,6 +24,8 @@ import android.os.Message;
 
 import android.telecomm.ICallService;
 import android.telecomm.ICallServiceAdapter;
+import android.util.Log;
+import android.util.Pair;
 
 /**
  * Base implementation of CallService which can be used to provide calls for the system
@@ -44,6 +46,7 @@ import android.telecomm.ICallServiceAdapter;
  * @hide
  */
 public abstract class CallService extends Service {
+    private static final String TAG = CallService.class.getSimpleName();
 
     /**
      * Default Handler used to consolidate binder method calls onto a single thread.
@@ -56,10 +59,25 @@ public abstract class CallService extends Service {
                     setCallServiceAdapter((ICallServiceAdapter) msg.obj);
                     break;
                 case MSG_IS_COMPATIBLE_WITH:
-                    isCompatibleWith((String) msg.obj);
+                    // See {@link CallServiceWrapper#isCompatibleWith} for dataObject definition.
+                    try {
+                        // TODO(santoscordon): Switch to using a custom class here instead.  When we
+                        // switch to using Call objects instead of handles directly, this may not even be
+                        // necessary.
+                        Pair<String, String> dataObject = (Pair<String, String>) msg.obj;
+                        isCompatibleWith(dataObject.first, dataObject.second);
+                    } catch (ClassCastException e) {
+                        Log.e(TAG, "Unexpected object type for MSG_IS_COMPATIBLE_WITH.", e);
+                    }
                     break;
                 case MSG_CALL:
-                    call((String) msg.obj);
+                    // See {@link CallServiceWrapper#call} for dataObject definition.
+                    try {
+                        Pair<String, String> dataObject = (Pair<String, String>) msg.obj;
+                        call(dataObject.first, dataObject.second);
+                    } catch (ClassCastException e) {
+                        Log.e(TAG, "Unexpected object type for MSG_CALL.", e);
+                    }
                     break;
                 case MSG_DISCONNECT:
                     disconnect((String) msg.obj);
@@ -81,13 +99,15 @@ public abstract class CallService extends Service {
         }
 
         @Override
-        public void isCompatibleWith(String handle) {
-            mMessageHandler.obtainMessage(MSG_IS_COMPATIBLE_WITH, handle).sendToTarget();
+        public void isCompatibleWith(String handle, String callId) {
+            Pair<String, String> dataObject = new Pair<String, String>(handle, callId);
+            mMessageHandler.obtainMessage(MSG_IS_COMPATIBLE_WITH, dataObject).sendToTarget();
         }
 
         @Override
-        public void call(String handle) {
-            mMessageHandler.obtainMessage(MSG_CALL, handle).sendToTarget();
+        public void call(String handle, String callId) {
+            Pair<String, String> dataObject = new Pair<String, String>(handle, callId);
+            mMessageHandler.obtainMessage(MSG_CALL, dataObject).sendToTarget();
         }
 
         @Override
@@ -129,6 +149,13 @@ public abstract class CallService extends Service {
 
     /** {@inheritDoc} */
     public IBinder onBind(Intent intent) {
+        return getBinder();
+    }
+
+    /**
+     * Returns binder object which can be used across IPC methods.
+     */
+    public IBinder getBinder() {
         return mBinder;
     }
 
@@ -137,27 +164,37 @@ public abstract class CallService extends Service {
      * changes of existing calls.
      * TODO(santoscordon): Should we not reference ICallServiceAdapter directly from here? Should we
      * wrap that in a wrapper like we do for CallService/ICallService?
+     *
      * @param callServiceAdapter Adapter object for communicating call to CallsManager
      */
     public abstract void setCallServiceAdapter(ICallServiceAdapter callServiceAdapter);
 
     /**
-     * Determines if the CallService can make calls to the handle.
-     * @param handle The handle to test for compatibility.
-     * TODO(santoscordon): Need response parameter.
+     * Determines if the CallService can make calls to the handle. Response is sent via
+     * ICallServiceAdapter. When responding, the correct call ID must be specified along with
+     * the handle.
+     *
+     * @param handle The destination handle to test against.
+     * @param callId The call identifier associated with this compatibility request.
      */
-    public abstract void isCompatibleWith(String handle);
+    public abstract void isCompatibleWith(String handle, String callId);
 
     /**
-     * Calls the specified handle. Handle type is dynamically extensible and can be a phone number,
-     * a SIP address, or other types. Only called if {@link #isCompatibleWith} returns true for the
-     * same handle and this service is selected by the switchboard to handle the call.
-     * @param handle The handle to call.
+     * Attempts to call the relevant party using the specified handle, be it a phone number,
+     * SIP address, or some other kind of user ID.  Note that the set of handle types is
+     * 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#newOutgoingCall} if it can successfully
+     * make the call.
+     *
+     * @param handle The destination handle to call.
+     * @param callId Unique identifier for the call.
      */
-    public abstract void call(String handle);
+    public abstract void call(String handle, 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/ICallService.aidl b/telecomm/java/android/telecomm/ICallService.aidl
index 6764e4e..9d02234 100644
--- a/telecomm/java/android/telecomm/ICallService.aidl
+++ b/telecomm/java/android/telecomm/ICallService.aidl
@@ -43,26 +43,34 @@ oneway interface ICallService {
     void setCallServiceAdapter(in ICallServiceAdapter callServiceAdapter);
 
     /**
-     * Determines if the CallService can make calls to the handle.
-     * TODO(santoscordon): Move this method into its own service interface long term.
-     * TODO(santoscordon): Add response callback parameter.
+     * Determines if the ICallService can make calls to the handle. Response is sent via
+     * {@link ICallServiceAdapter#setCompatibleWith}.  When responding, the correct call ID must be
+     * specified along with the handle. 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.
+     * TODO(santoscordon): Switch from specific parameters to CallInfo/Call.
      *
-     * @param handle The destination handle to test against. Method should return true via the
-     * response callback if it can make a call to this handle.
+     * @param handle The destination handle to test against.
+     * @param callId The call identifier associated with this compatibility request.
      */
-    void isCompatibleWith(String handle);
+    void isCompatibleWith(String handle, String callId);
 
     /**
      * Attempts to call the relevant party using the specified handle, be it a phone number,
      * SIP address, or some other kind of user ID.  Note that the set of handle types is
      * dynamically extensible since call providers should be able to implement arbitrary
-     * handle-calling systems.  See {@link #isCompatibleWith}.
-     * TODO(santoscordon): Should this have a response attached to it to ensure that the call
-     * service actually plans to make the call?
+     * handle-calling systems.  See {@link #isCompatibleWith}. It is expected that the
+     * call service respond via {@link ICallServiceAdapter#newOutgoingCall} if it can successfully
+     * make the call.
+     * TODO(santoscordon): Figure out how a calls service can short-circuit a failure to
+     * the adapter.
      *
      * @param handle The destination handle to call.
+     * @param callId Unique identifier for the call.
      */
-    void call(String handle);
+    void call(String handle, String callId);
 
     /**
      * Disconnects the call identified by callId.
diff --git a/telecomm/java/android/telecomm/ICallServiceAdapter.aidl b/telecomm/java/android/telecomm/ICallServiceAdapter.aidl
index 01f785c..71c5006 100644
--- a/telecomm/java/android/telecomm/ICallServiceAdapter.aidl
+++ b/telecomm/java/android/telecomm/ICallServiceAdapter.aidl
@@ -26,30 +26,35 @@ import android.telecomm.CallInfo;
 oneway interface ICallServiceAdapter {
 
     /**
-     * Retrieves a new unique call ID for use with newOutgoingCall and newIncomingCall.
+     * Retrieves a new unique call ID for use with newIncomingCall.
      */
     void getNextCallId(/* TODO(santoscordon): Needs response object */);
 
     /**
+     * Receives confirmation of the call service's ability to make a call to the specified handle.
+     *
+     * @param handle The handle to call.
+     * @param callId The identifier of the call for which compatibility is being received.
+     * @param isCompatible True if the call service can place a call to the handle.
+     */
+    void setCompatibleWith(String handle, String callId, boolean isCompatible);
+
+    /**
      * Tells CallsManager of a new incoming call.
      *
+     * @param handle The handle to the other party or null if no such handle is available (as with
+     *     blocked caller ID).
      * @param callId The unique ID (via {@link #getNextCallId}) of the new incoming call.
-     * @param info Information about the new call including but not limited to the start time of the
-     *     call and information about the caller's handle.
      */
-    void newIncomingCall(String callId, in CallInfo info);
+    void newIncomingCall(String handle, String callId);
 
     /**
      * Tells CallsManager of a new outgoing call. Use of this method should always follow
      * {@link ICallService#call}.
      *
-     * @param callId The unique ID (via {@link #getNextCallId}) of the new outgoing call.
-     *     TODO(santoscordon): May be easier to have ICallService#call provide an ID instead of
-     *     requiring a separate call to getNextCallId().
-     * @param info Information about the new call including but not limited to the start time of the
-     *     call and information about the caller's handle.
+     * @param callId The unique ID (via {@link ICallService#call}) of the new outgoing call.
      */
-    void newOutgoingCall(String callId, in CallInfo info);
+    void newOutgoingCall(String callId);
 
     /**
      * Sets a call's state to active (e.g., an ongoing call where two parties can actively
diff --git a/telecomm/java/android/telecomm/ICallServiceLookupResponse.aidl b/telecomm/java/android/telecomm/ICallServiceLookupResponse.aidl
index 7384d1b..91c5724 100644
--- a/telecomm/java/android/telecomm/ICallServiceLookupResponse.aidl
+++ b/telecomm/java/android/telecomm/ICallServiceLookupResponse.aidl
@@ -25,10 +25,11 @@ import java.util.List;
  */
 oneway interface ICallServiceLookupResponse {
     /**
-     * Receives the list of {@link ICallService}s as a list of {@link IBinder}s.
+     * Forwards the list of {@link ICallService}s as a list of {@link IBinder}s to be processed by
+     * Telecomm which will choose which call service, among potentially many, to place a call.
      *
      * @param callServices List of call services from {@link ICallServiceProvider}.
      * TODO(gilad): Rename to callServiceBinders.
      */
-    void onResult(in List<IBinder> callServices);
+    void setCallServices(in List<IBinder> callServices);
 }