Add wrappers around telecomm interfaces

This CL adds wrappers for:
  CallServiceLookupResponse
  CallServiceAdapter
  IInCallAdapter
  IInCallService

This CL also moves all the aidl files into
com.android.internal.telecomm.

Change-Id: I840f023bc545643e8bb719825e7bc78344ee46ee

9 files changed, 591 insertions, 0 deletions

diff --git a/telecomm/java/com/android/internal/telecomm/ICallService.aidl b/telecomm/java/com/android/internal/telecomm/ICallService.aidl
new file mode 100644
index 0000000..1df3f80
--- /dev/null
+++ b/telecomm/java/com/android/internal/telecomm/ICallService.aidl
@@ -0,0 +1,123 @@
+/*
+ * Copyright (C) 2013 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.internal.telecomm;
+
+import android.os.Bundle;
+import android.telecomm.CallInfo;
+
+import com.android.internal.telecomm.ICallServiceAdapter;
+
+/**
+ * Service interface for services which would like to provide calls to be
+ * managed by the system in-call UI.
+ *
+ * This interface provides methods that the android framework can use to deliver commands
+ * for calls provided by this call service including making new calls and disconnecting
+ * existing ones. A binding to ICallService implementations exists for two conditions:
+ * 1) There exists one or more live calls for that call service,
+ * 2) Prior to an outbound call to test if this call service is compatible with the outgoing call.
+ *
+ * TODO(santoscordon): Need final public-facing comments in this file.
+ * {@hide}
+ */
+oneway interface ICallService {
+
+    /**
+     * Sets an implementation of ICallServiceAdapter which the call service can use to add new calls
+     * and communicate state changes of existing calls. This is the first method that is called
+     * after a the framework binds to the call service.
+     *
+     * @param callServiceAdapter Interface to CallsManager for adding and updating calls.
+     */
+    void setCallServiceAdapter(in ICallServiceAdapter callServiceAdapter);
+
+    /**
+     * Determines if the ICallService can place the specified call. Response is sent via
+     * {@link ICallServiceAdapter#setCompatibleWith}.  When responding, the correct call ID must be
+     * 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.  Only used in the context of outgoing calls and call switching (handoff).
+     *
+     * @param callInfo The details of the relevant call.
+     */
+    void isCompatibleWith(in CallInfo callInfo);
+
+    /**
+     * Attempts to call the relevant party using the specified call's 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#handleSuccessfulOutgoingCall} if it can
+     * 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.
+     */
+    void call(in CallInfo callInfo);
+
+    /**
+     * 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 ICallServiceAdapter.markCallAsDisconnected.
+     *
+     * @param callId The identifier of the call to abort.
+     */
+    void abort(String callId);
+
+    /**
+     * Receives a new call ID to use with an incoming call. Invoked by Telecomm after it is notified
+     * that this call service has a pending incoming call, see
+     * {@link TelecommConstants#ACTION_INCOMING_CALL}. The call service must first give Telecomm
+     * additional information of the call through {@link ICallServiceAdapter#handleIncomingCall}.
+     * Following that, the call service can update the call at will using the specified call ID.
+     *
+     * As part of the {@link TelecommConstants#ACTION_INCOMING_CALL} Intent, a  Bundle of extra
+     * data could be sent via {@link TelecommConstants#EXTRA_INCOMING_CALL_EXTRAS}, which is
+     * returned through this method. If no data was given, an empty Bundle will be returned.
+     *
+     * @param callId The ID of the call.
+     * @param extras The Bundle of extra information passed via
+     *     {@link TelecommConstants#EXTRA_INCOMING_CALL_EXTRAS}.
+     */
+    void setIncomingCallId(String callId, in Bundle extras);
+
+    /**
+     * Answers a ringing call identified by callId. Telecomm invokes this method as a result of the
+     * user hitting the "answer" button in the incoming call screen.
+     *
+     * @param callId The ID of the call.
+     */
+    void answer(String callId);
+
+    /**
+     * Rejects a ringing call identified by callId. Telecomm invokes this method as a result of the
+     * user hitting the "reject" button in the incoming call screen.
+     *
+     * @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);
+}
diff --git a/telecomm/java/com/android/internal/telecomm/ICallServiceAdapter.aidl b/telecomm/java/com/android/internal/telecomm/ICallServiceAdapter.aidl
new file mode 100644
index 0000000..7920b64
--- /dev/null
+++ b/telecomm/java/com/android/internal/telecomm/ICallServiceAdapter.aidl
@@ -0,0 +1,94 @@
+/*
+ * Copyright (C) 2013 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.internal.telecomm;
+
+import android.telecomm.CallInfo;
+
+/**
+ * Provides methods for ICallService implementations to interact with the system phone app.
+ * TODO(santoscordon): Need final public-facing comments in this file.
+ * {@hide}
+ */
+oneway interface ICallServiceAdapter {
+
+    /**
+     * Receives confirmation of a call service's ability to place a call. This method is used in
+     * response to {@link ICallService#isCompatibleWith}.
+     *
+     * @param callId The identifier of the call for which compatibility is being received. This ID
+     *     should correspond to the ID given as part of the call information in
+     *     {@link ICallService#isCompatibleWith}.
+     * @param isCompatible True if the call service can place the call.
+     */
+    void setIsCompatibleWith(String callId, boolean isCompatible);
+
+    /**
+     * Provides Telecomm with the details of an incoming call. An invocation of this method must
+     * follow {@link CallService#setIncomingCallId} and use the call ID specified therein. Upon
+     * the invocation of this method, Telecomm will bring up the incoming-call interface where the
+     * user can elect to answer or reject a call.
+     *
+     * @param callInfo The details of the relevant call.
+     */
+    void notifyIncomingCall(in CallInfo callInfo);
+
+    /**
+     * Tells Telecomm that an attempt to place the specified outgoing call succeeded.
+     * TODO(santoscordon): Consider adding a CallState parameter in case this outgoing call is
+     * somehow no longer in the DIALING state.
+     *
+     * @param callId The ID of the outgoing call.
+     */
+    void handleSuccessfulOutgoingCall(String callId);
+
+    /**
+     * Tells Telecomm that an attempt to place the specified outgoing call failed.
+     *
+     * @param callId The ID of the outgoing call.
+     * @param errorMessage The error associated with the failed call attempt.
+     */
+    void handleFailedOutgoingCall(String callId, String errorMessage);
+
+    /**
+     * Sets a call's state to active (e.g., an ongoing call where two parties can actively
+     * communicate).
+     *
+     * @param callId The unique ID of the call whose state is changing to active.
+     */
+    void setActive(String callId);
+
+    /**
+     * Sets a call's state to ringing (e.g., an inbound ringing call).
+     *
+     * @param callId The unique ID of the call whose state is changing to ringing.
+     */
+    void setRinging(String callId);
+
+    /**
+     * Sets a call's state to dialing (e.g., dialing an outbound call).
+     *
+     * @param callId The unique ID of the call whose state is changing to dialing.
+     */
+    void setDialing(String callId);
+
+    /**
+     * Sets a call's state to disconnected.
+     *
+     * @param callId The unique ID of the call whose state is changing to disconnected.
+     */
+    void setDisconnected(String callId);
+}
diff --git a/telecomm/java/com/android/internal/telecomm/ICallServiceLookupResponse.aidl b/telecomm/java/com/android/internal/telecomm/ICallServiceLookupResponse.aidl
new file mode 100644
index 0000000..97fa834
--- /dev/null
+++ b/telecomm/java/com/android/internal/telecomm/ICallServiceLookupResponse.aidl
@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.internal.telecomm;
+
+import android.os.IBinder;
+import android.telecomm.CallServiceDescriptor;
+import java.util.List;
+
+/**
+ * Used by {@link ICallServiceProvider} to return a list of {@link CallServiceDescriptor}s.
+ * {@hide}
+ */
+oneway interface ICallServiceLookupResponse {
+    /**
+     * Passes the sorted list of preferred {@link CallServiceDescriptor}s back to Telecomm.  Used
+     * in the context of attempting to place a pending outgoing call.
+     *
+     * @param callServiceDescriptors The set of call-service descriptors from
+     * {@link ICallServiceProvider}.
+     */
+    void setCallServiceDescriptors(in List<CallServiceDescriptor> callServiceDescriptors);
+}
diff --git a/telecomm/java/com/android/internal/telecomm/ICallServiceProvider.aidl b/telecomm/java/com/android/internal/telecomm/ICallServiceProvider.aidl
new file mode 100644
index 0000000..39feddd
--- /dev/null
+++ b/telecomm/java/com/android/internal/telecomm/ICallServiceProvider.aidl
@@ -0,0 +1,48 @@
+/*
+ * Copyright (C) 2013 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.internal.telecomm;
+
+import android.telecomm.CallServiceDescriptor;
+
+import com.android.internal.telecomm.ICallServiceLookupResponse;
+
+/**
+ * Interface for applications interested in providing call-service implementations.  Only used in
+ * outgoing-call scenarios where the best-candidate service to issue the call over may need to be
+ * decided dynamically (unlike incoming call scenario where the call-service is known).
+ *
+ * Intended usage at time of writing is: Call intent received by the CallsManager, which in turn
+ * gathers and binds all ICallServiceProvider implementations (using the framework). Once bound, the
+ * CallsManager invokes the lookupCallServices API of each bound provider and waits until
+ * either all providers reply (asynchronously) or some timeout is met. The resulted list is then
+ * processed by the CallsManager and its helpers (potentially requesting input from the user) to
+ * identify the best CallService.  The user should obviously be notified upon zero candidates as
+ * well as all (one or more) candidates failing to issue the call.
+ * {@hide}
+ */
+oneway interface ICallServiceProvider {
+
+    /**
+     * Initiates the process to retrieve the list of {@link CallServiceDescriptor}s implemented by
+     * this provider.
+     * TODO(santoscordon): Needs comments on how to populate the list within
+     * ICallServiceLookupResponse and how to handle error conditions.
+     *
+     * @param response The response object through which the list of call services is sent.
+     */
+    void lookupCallServices(in ICallServiceLookupResponse response);
+}
diff --git a/telecomm/java/com/android/internal/telecomm/ICallServiceSelectionResponse.aidl b/telecomm/java/com/android/internal/telecomm/ICallServiceSelectionResponse.aidl
new file mode 100644
index 0000000..8270aa5
--- /dev/null
+++ b/telecomm/java/com/android/internal/telecomm/ICallServiceSelectionResponse.aidl
@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.internal.telecomm;
+
+import android.os.IBinder;
+import android.telecomm.CallServiceDescriptor;
+import java.util.List;
+
+/**
+ * Used by {@link ICallServiceSelector} to return the preferred list of {@link ICallService}
+ * implementations with which to connect the corresponding outgoing call.
+ * {@hide}
+ */
+oneway interface ICallServiceSelectionResponse {
+    /**
+     * Records the sorted set of call services that are preferred by the corresponding
+     * call-service selector.
+     *
+     * @param selectedCallServiceDescriptors The prioritized list of preferred call-service
+     *        descriptors to use for completing the call.
+     */
+    void setSelectedCallServiceDescriptors(
+            in List<CallServiceDescriptor> selectedCallServiceDescriptors);
+}
diff --git a/telecomm/java/com/android/internal/telecomm/ICallServiceSelector.aidl b/telecomm/java/com/android/internal/telecomm/ICallServiceSelector.aidl
new file mode 100644
index 0000000..3b73d9b
--- /dev/null
+++ b/telecomm/java/com/android/internal/telecomm/ICallServiceSelector.aidl
@@ -0,0 +1,91 @@
+/*
+ * Copyright (C) 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.internal.telecomm;
+
+import android.telecomm.CallInfo;
+import android.telecomm.CallServiceDescriptor;
+
+import com.android.internal.telecomm.ICallService;
+import com.android.internal.telecomm.ICallServiceSelectionResponse;
+import com.android.internal.telecomm.ICallSwitchabilityResponse;
+
+import java.util.List;
+
+/**
+ * Interface for call-service selector implementations.
+ *
+ * Call-service selectors are ultimately responsible for deciding which of the available call
+ * service implementations should be used to place an outgoing call, as well as which service
+ * to switch the call to upon system-provided opportunities to switch call services.
+ *
+ * Outgoing call scenario:
+ *
+ * Telecomm maintains a prioritized list of call-service selectors.  Upon attempting to issue
+ * outgoing calls, the switchboard iterates through these (starting with the highest-priority
+ * selector). It then invokes the "select" API below passing -- among other parameters -- the
+ * list of available call services, excluding fully-utilized services that temporarily aren't
+ * capable of accommodating additional calls.  Once invoked, selectors return a sorted subset
+ * from the specified list, containing the preferred services through which to place the call.
+ * Upon empty selection the switchboard continues to the next selector.  Otherwise, upon non-
+ * empty selection, the returned call services are attempted in the specified order. The flow
+ * is concluded either when the call is placed by one of the specified services (e.g. ringing)
+ * or upon failure to connect by the time the set of selectors is exhausted. Failed calls are
+ * essentially abandoned by this flow and then picked up by the switchboard's monitor.
+ *
+ * Note that attempted-yet-failed call services within one outgoing-call cycle may be omitted
+ * from the set passed to the next selector. As for selector priority, at the time of writing
+ * this is intended to be a blend of built-in priorities (e.g. to handle emergency calls) and
+ * user-specified preferences (via settings, e.g. electing to use a particular selector prior
+ * to attempting the system-default call-service selector).
+ *
+ * Call-services switching scenario (applying to both incoming and outgoing calls):
+ *
+ * The switchboard may invoke any active selector (a selector associated with one or more on-
+ * going calls) up to once per ongoing call at its discretion (e.g. periodically), once again
+ * passing the available call services to the "select" API.  As in the outgoing-call scenario
+ * above, returning the empty list means "pass" -- basically indicating that the current call
+ * service for this call need not be switched at this time. In cases where switching isn't at
+ * all supported (either for a given call or globally across a given selector) , isSwitchable
+ * below can return false blindly to suppress all "select" calls beyond the initial one (that
+ * is used to establish outgoing calls).
+ * {@hide}
+ */
+oneway interface ICallServiceSelector {
+
+    /**
+     * Initiates the process to retrieve the sorted set of call services that are preferred by
+     * this call-service selector.
+     *
+     * @param callInfo The details of the relevant call.
+     * @param callServiceDescriptors The list of call-service descriptors to select from.
+     * @param response The response object through which the selected service IDs are passed back
+     *         to Telecomm.
+     */
+    void select(
+            in CallInfo callInfo,
+            in List<CallServiceDescriptor> callServiceDescriptors,
+            in ICallServiceSelectionResponse response);
+
+    /**
+     * Determines if the specified ongoing call can/should be switched from the currently-used
+     * call service to another.
+     *
+     * @param callInfo The details of the relevant call.
+     * @param response The response object to be populated and returned to switchboard.
+     */
+    void isSwitchable(in CallInfo callInfo, in ICallSwitchabilityResponse response);
+}
diff --git a/telecomm/java/com/android/internal/telecomm/ICallSwitchabilityResponse.aidl b/telecomm/java/com/android/internal/telecomm/ICallSwitchabilityResponse.aidl
new file mode 100644
index 0000000..9a7e9e5
--- /dev/null
+++ b/telecomm/java/com/android/internal/telecomm/ICallSwitchabilityResponse.aidl
@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.internal.telecomm;
+
+/**
+ * Used by {@link ICallServiceSelector}s to return whether or not the relevant
+ * call is switchable.
+ * {@hide}
+ */
+oneway interface ICallSwitchabilityResponse {
+    /**
+     * Records whether or not the corresponding call can potentially be switched to another
+     * call service.
+     *
+     * @param isSwitchable True if the associated call-service selector may be interested
+     *         in switching call services.  Setting isSwitchable to true should generally
+     *         guarantee the "select" API of the associated selector to be invoked, hence
+     *         allowing the selector to return either the empty list (meaning pass, don't
+     *         switch) or the prioritized list of call-services to attempt switching to.
+     */
+    void setIsSwitchable(boolean isSwitchable);
+}
diff --git a/telecomm/java/com/android/internal/telecomm/IInCallAdapter.aidl b/telecomm/java/com/android/internal/telecomm/IInCallAdapter.aidl
new file mode 100644
index 0000000..d4e67fc
--- /dev/null
+++ b/telecomm/java/com/android/internal/telecomm/IInCallAdapter.aidl
@@ -0,0 +1,56 @@
+/*
+ * Copyright (C) 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.internal.telecomm;
+
+/**
+ * Receives commands from {@link IInCallService} implementations which should be executed by
+ * Telecomm. When Telecomm binds to a {@link IInCallService}, an instance of this class is given to
+ * the in-call service through which it can manipulate live (active, dialing, ringing) calls. When
+ * the in-call service is notified of new calls ({@link IInCallService#addCall}), it can use the
+ * given call IDs to execute commands such as {@link #answerCall} for incoming calls or
+ * {@link #disconnectCall} for active calls the user would like to end. Some commands are only
+ * appropriate for calls in certain states; please consult each method for such limitations.
+ * TODO(santoscordon): Needs more/better comments once the API is finalized.
+ * TODO(santoscordon): Specify the adapter will stop functioning when there are no more calls.
+ * TODO(santoscordon): Once we have proper "CallState" constant definitions, consider rewording
+ * the javadoc to reference those states precisely.
+ * {@hide}
+ */
+oneway interface IInCallAdapter {
+    /**
+     * Instructs Telecomm to answer the specified call.
+     *
+     * @param callId The identifier of the call to answer.
+     */
+    void answerCall(String callId);
+
+    /**
+     * Instructs Telecomm to reject the specified call.
+     * TODO(santoscordon): Add reject-with-text-message parameter when that feature
+     * is ported over.
+     *
+     * @param callId The identifier of the call to reject.
+     */
+    void rejectCall(String callId);
+
+    /**
+     * Instructs Telecomm to disconnect the specified call.
+     *
+     * @param callId The identifier of the call to disconnect.
+     */
+    void disconnectCall(String callId);
+}
diff --git a/telecomm/java/com/android/internal/telecomm/IInCallService.aidl b/telecomm/java/com/android/internal/telecomm/IInCallService.aidl
new file mode 100644
index 0000000..05b0d20
--- /dev/null
+++ b/telecomm/java/com/android/internal/telecomm/IInCallService.aidl
@@ -0,0 +1,69 @@
+/*
+ * Copyright (C) 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.internal.telecomm;
+
+import android.telecomm.CallInfo;
+
+import com.android.internal.telecomm.IInCallAdapter;
+
+/**
+ * This service is implemented by any app that wishes to provide the user-interface for managing
+ * phone calls. Telecomm binds to this service while there exists a live (active or incoming)
+ * call, and uses it to notify the in-call app of any live and and recently disconnected calls.
+ * TODO(santoscordon): Needs more/better description of lifecycle once the interface is better
+ * defined.
+ * TODO(santoscordon): What happens if two or more apps on a given device implement this interface?
+ * {@hide}
+ */
+oneway interface IInCallService {
+
+    /**
+     * Provides the in-call app an adapter object through which to send call-commands such as
+     * answering and rejecting incoming calls, disconnecting active calls, and putting calls in
+     * special states (mute, hold, etc).
+     *
+     * @param inCallAdapter Adapter through which an in-call app can send call-commands to Telecomm.
+     */
+    void setInCallAdapter(in IInCallAdapter inCallAdapter);
+
+    /**
+     * Indicates to the in-call app that a new call has been created and an appropriate
+     * user-interface should be built and shown to notify the user. Information about the call
+     * including its current state is passed in through the callInfo object.
+     *
+     * @param callInfo Information about the new call.
+     */
+    void addCall(in CallInfo callInfo);
+
+    /**
+     * Indicates to the in-call app that a call has moved to the
+     * {@link android.telecomm.CallState#ACTIVE} state.
+     *
+     * @param callId The identifier of the call that became active.
+     */
+    void setActive(String callId);
+
+    /**
+     * Indicates to the in-call app that a call has been moved to the
+     * {@link android.telecomm.CallState#DISCONNECTED} and the user should be notified.
+     * TODO(santoscordon): Needs disconnect-cause either as a numberical constant, string or both
+     * depending on what is ultimately needed to support all scenarios.
+     *
+     * @param callId The identifier of the call that was disconnected.
+     */
+    void setDisconnected(String callId);
+}