Merge "API Documentation and Constant cleanup." am: 8882c55b21 am: 8917fc21cc (c7a86b14) · Commits · e / os / android_frameworks_base

api/current.txt

+4 −4

Original line number	Diff line number	Diff line
		@@ -41379,10 +41379,10 @@ package android.telecom {
		method public void onStateChanged(android.telecom.Call, int);
		method public void onVideoCallChanged(android.telecom.Call, android.telecom.InCallService.VideoCall);
		field public static final int HANDOVER_FAILURE_DEST_APP_REJECTED = 1; // 0x1
		field public static final int HANDOVER_FAILURE_DEST_INVALID_PERM = 3; // 0x3
		field public static final int HANDOVER_FAILURE_DEST_NOT_SUPPORTED = 2; // 0x2
		field public static final int HANDOVER_FAILURE_DEST_USER_REJECTED = 4; // 0x4
		field public static final int HANDOVER_FAILURE_ONGOING_EMERG_CALL = 5; // 0x5
		field public static final int HANDOVER_FAILURE_NOT_SUPPORTED = 2; // 0x2
		field public static final int HANDOVER_FAILURE_ONGOING_EMERG_CALL = 4; // 0x4
		field public static final int HANDOVER_FAILURE_UNKNOWN = 5; // 0x5
		field public static final int HANDOVER_FAILURE_USER_REJECTED = 3; // 0x3
		}

		public static class Call.Details {

telecomm/java/android/telecom/Call.java

+114 −23

Original line number	Diff line number	Diff line
		@@ -879,42 +879,76 @@ public final class Call {
		/**
		* @hide
		*/
		@IntDef({HANDOVER_FAILURE_DEST_APP_REJECTED, HANDOVER_FAILURE_DEST_NOT_SUPPORTED,
		HANDOVER_FAILURE_DEST_INVALID_PERM, HANDOVER_FAILURE_DEST_USER_REJECTED,
		HANDOVER_FAILURE_ONGOING_EMERG_CALL})
		@IntDef(prefix = { "HANDOVER_" },
		value = {HANDOVER_FAILURE_DEST_APP_REJECTED, HANDOVER_FAILURE_NOT_SUPPORTED,
		HANDOVER_FAILURE_USER_REJECTED, HANDOVER_FAILURE_ONGOING_EMERG_CALL,
		HANDOVER_FAILURE_UNKNOWN})
		@Retention(RetentionPolicy.SOURCE)
		public @interface HandoverFailureErrors {}

		/**
		* Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when the app
		* to handover the call rejects handover.
		* to handover the call to rejects the handover request.
		* <p>
		* Will be returned when {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} is called
		* and the destination {@link PhoneAccountHandle}'s {@link ConnectionService} returns a
		* {@code null} {@link Connection} from
		* {@link ConnectionService#onCreateOutgoingHandoverConnection(PhoneAccountHandle,
		* ConnectionRequest)}.
		* <p>
		* For more information on call handovers, see
		* {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
		*/
		public static final int HANDOVER_FAILURE_DEST_APP_REJECTED = 1;

		/**
		* Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when there is
		* an error associated with unsupported handover.
		*/
		public static final int HANDOVER_FAILURE_DEST_NOT_SUPPORTED = 2;

		/**
		* Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when there
		* are some permission errors associated with APIs doing handover.
		* Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when a handover
		* is initiated but the source or destination app does not support handover.
		* <p>
		* Will be returned when a handover is requested via
		* {@link #handoverTo(PhoneAccountHandle, int, Bundle)} and the destination
		* {@link PhoneAccountHandle} does not declare
		* {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_TO}. May also be returned when a handover is
		* requested at the {@link PhoneAccountHandle} for the current call (i.e. the source call's
		* {@link Details#getAccountHandle()}) does not declare
		* {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_FROM}.
		* <p>
		* For more information on call handovers, see
		* {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
		*/
		public static final int HANDOVER_FAILURE_DEST_INVALID_PERM = 3;
		public static final int HANDOVER_FAILURE_NOT_SUPPORTED = 2;

		/**
		* Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when user
		* rejects handover.
		* Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when the remote
		* user rejects the handover request.
		* <p>
		* For more information on call handovers, see
		* {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
		*/
		public static final int HANDOVER_FAILURE_DEST_USER_REJECTED = 4;
		public static final int HANDOVER_FAILURE_USER_REJECTED = 3;

		/**
		* Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when there
		* is ongoing emergency call.
		* <p>
		* This error code is returned when {@link #handoverTo(PhoneAccountHandle, int, Bundle)} is
		* called on an emergency call, or if any other call is an emergency call.
		* <p>
		* Handovers are not permitted while there are ongoing emergency calls.
		* <p>
		* For more information on call handovers, see
		* {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
		*/
		public static final int HANDOVER_FAILURE_ONGOING_EMERG_CALL = 5;
		public static final int HANDOVER_FAILURE_ONGOING_EMERG_CALL = 4;

		/**
		* Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when a handover
		* fails for an unknown reason.
		* <p>
		* For more information on call handovers, see
		* {@link #handoverTo(PhoneAccountHandle, int, Bundle)}.
		*/
		public static final int HANDOVER_FAILURE_UNKNOWN = 5;

		/**
		* Invoked when the state of this {@code Call} has changed. See {@link #getState()}.
		@@ -1055,6 +1089,10 @@ public final class Call {
		/**
		* Invoked when Call handover from one {@link PhoneAccount} to other {@link PhoneAccount}
		* has completed successfully.
		* <p>
		* For a full discussion of the handover process and the APIs involved, see
		* {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}.
		*
		* @param call The call which had initiated handover.
		*/
		public void onHandoverComplete(Call call) {}
		@@ -1062,8 +1100,12 @@ public final class Call {
		/**
		* Invoked when Call handover from one {@link PhoneAccount} to other {@link PhoneAccount}
		* has failed.
		* <p>
		* For a full discussion of the handover process and the APIs involved, see
		* {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}.
		*
		* @param call The call which had initiated handover.
		* @param failureReason Error reason for failure
		* @param failureReason Error reason for failure.
		*/
		public void onHandoverFailed(Call call, @HandoverFailureErrors int failureReason) {}
		}
		@@ -1260,7 +1302,7 @@ public final class Call {
		* Instructs this {@link #STATE_RINGING} {@code Call} to answer.
		* @param videoState The video state in which to answer the call.
		*/
		public void answer(int videoState) {
		public void answer(@VideoProfile.VideoState int videoState) {
		mInCallAdapter.answerCall(mTelecomCallId, videoState);
		}

		@@ -1474,16 +1516,65 @@ public final class Call {
		* by {@code toHandle}. The videoState specified indicates the desired video state after the
		* handover.
		* <p>
		* A handover request is initiated by the user from one app to indicate a desire
		* to handover a call to another.
		* A call handover is the process where an ongoing call is transferred from one app (i.e.
		* {@link ConnectionService} to another app. The user could, for example, choose to continue a
		* mobile network call in a video calling app. The mobile network call via the Telephony stack
		* is referred to as the source of the handover, and the video calling app is referred to as the
		* destination.
		* <p>
		* When considering a handover scenario the device this method is called on is considered the
		* <em>initiating</em> device (since the user initiates the handover from this device), and the
		* other device is considered the <em>receiving</em> device.
		* <p>
		* When this method is called on the <em>initiating</em> device, the Telecom framework will bind
		* to the {@link ConnectionService} defined by the {@code toHandle} {@link PhoneAccountHandle}
		* and invoke
		* {@link ConnectionService#onCreateOutgoingHandoverConnection(PhoneAccountHandle,
		* ConnectionRequest)} to inform the destination app that a request has been made to handover a
		* call to it. The app returns an instance of {@link Connection} to represent the handover call
		* At this point the app should display UI to indicate to the user that a call
		* handover is in process.
		* <p>
		* The destination app is responsible for communicating the handover request from the
		* <em>initiating</em> device to the <em>receiving</em> device.
		* <p>
		* When the app on the <em>receiving</em> device receives the handover request, it calls
		* {@link TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle)} to continue the handover
		* process from the <em>initiating</em> device to the <em>receiving</em> device. At this point
		* the destination app on the <em>receiving</em> device should show UI to allow the user to
		* choose whether they want to continue their call in the destination app.
		* <p>
		* When the destination app on the <em>receiving</em> device calls
		* {@link TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle)}, Telecom will bind to its
		* {@link ConnectionService} and call
		* {@link ConnectionService#onCreateIncomingHandoverConnection(PhoneAccountHandle,
		* ConnectionRequest)} to inform it of the handover request. The app returns an instance of
		* {@link Connection} to represent the handover call.
		* <p>
		* If the user of the <em>receiving</em> device accepts the handover, the app calls
		* {@link Connection#setActive()} to complete the handover process; Telecom will disconnect the
		* original call. If the user rejects the handover, the app calls
		* {@link Connection#setDisconnected(DisconnectCause)} and specifies a {@link DisconnectCause}
		* of {@link DisconnectCause#CANCELED} to indicate that the handover has been cancelled.
		* <p>
		* Telecom will only allow handovers from {@link PhoneAccount}s which declare
		* {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_FROM}. Similarly, the {@link PhoneAccount}
		* specified by {@code toHandle} must declare {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_TO}.
		* <p>
		* Errors in the handover process are reported to the {@link InCallService} via
		* {@link Callback#onHandoverFailed(Call, int)}. Errors in the handover process are reported to
		* the involved {@link ConnectionService}s via
		* {@link ConnectionService#onHandoverFailed(ConnectionRequest, int)}.
		*
		* @param toHandle {@link PhoneAccountHandle} of the {@link ConnectionService} to handover
		* this call to.
		* @param videoState Indicates the video state desired after the handover.
		* @param videoState Indicates the video state desired after the handover (see the
		* {@code STATE_*} constants defined in {@link VideoProfile}).
		* @param extras Bundle containing extra information to be passed to the
		* {@link ConnectionService}
		*/
		public void handoverTo(PhoneAccountHandle toHandle, int videoState, Bundle extras) {
		public void handoverTo(PhoneAccountHandle toHandle, @VideoProfile.VideoState int videoState,
		Bundle extras) {
		mInCallAdapter.handoverTo(mTelecomCallId, toHandle, videoState, extras);
		}

telecomm/java/android/telecom/ConnectionService.java

+87 −11

Original line number	Diff line number	Diff line
		@@ -2223,12 +2223,50 @@ public abstract class ConnectionService extends Service {
		}

		/**
		* Called by Telecom on the initiating side of the handover to create an instance of a
		* handover connection.
		* Called by Telecom to request that a {@link ConnectionService} creates an instance of an
		* outgoing handover {@link Connection}.
		* <p>
		* A call handover is the process where an ongoing call is transferred from one app (i.e.
		* {@link ConnectionService} to another app. The user could, for example, choose to continue a
		* mobile network call in a video calling app. The mobile network call via the Telephony stack
		* is referred to as the source of the handover, and the video calling app is referred to as the
		* destination.
		* <p>
		* When considering a handover scenario the <em>initiating</em> device is where a user initiated
		* the handover process (e.g. by calling {@link android.telecom.Call#handoverTo(
		* PhoneAccountHandle, int, Bundle)}, and the other device is considered the <em>receiving</em>
		* device.
		* <p>
		* This method is called on the destination {@link ConnectionService} on <em>initiating</em>
		* device when the user initiates a handover request from one app to another. The user request
		* originates in the {@link InCallService} via
		* {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}.
		* <p>
		* For a full discussion of the handover process and the APIs involved, see
		* {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}.
		* <p>
		* Implementations of this method should return an instance of {@link Connection} which
		* represents the handover. If your app does not wish to accept a handover to it at this time,
		* you can return {@code null}. The code below shows an example of how this is done.
		* <pre>
		* {@code
		* public Connection onCreateIncomingHandoverConnection(PhoneAccountHandle
		* fromPhoneAccountHandle, ConnectionRequest request) {
		* if (!isHandoverAvailable()) {
		* return null;
		* }
		* MyConnection connection = new MyConnection();
		* connection.setAddress(request.getAddress(), TelecomManager.PRESENTATION_ALLOWED);
		* connection.setVideoState(request.getVideoState());
		* return connection;
		* }
		* }
		* </pre>
		*
		* @param fromPhoneAccountHandle {@link PhoneAccountHandle} associated with the
		* ConnectionService which needs to handover the call.
		* @param request Details about the call which needs to be handover.
		* @return Connection object corresponding to the handover call.
		* @param request Details about the call to handover.
		* @return {@link Connection} instance corresponding to the handover call.
		*/
		public Connection onCreateOutgoingHandoverConnection(PhoneAccountHandle fromPhoneAccountHandle,
		ConnectionRequest request) {
		@@ -2236,12 +2274,46 @@ public abstract class ConnectionService extends Service {
		}

		/**
		* Called by Telecom on the receiving side of the handover to request the
		* {@link ConnectionService} to create an instance of a handover connection.
		* Called by Telecom to request that a {@link ConnectionService} creates an instance of an
		* incoming handover {@link Connection}.
		* <p>
		* A call handover is the process where an ongoing call is transferred from one app (i.e.
		* {@link ConnectionService} to another app. The user could, for example, choose to continue a
		* mobile network call in a video calling app. The mobile network call via the Telephony stack
		* is referred to as the source of the handover, and the video calling app is referred to as the
		* destination.
		* <p>
		* When considering a handover scenario the <em>initiating</em> device is where a user initiated
		* the handover process (e.g. by calling {@link android.telecom.Call#handoverTo(
		* PhoneAccountHandle, int, Bundle)}, and the other device is considered the <em>receiving</em>
		* device.
		* <p>
		* This method is called on the destination app on the <em>receiving</em> device when the
		* destination app calls {@link TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle)} to
		* accept an incoming handover from the <em>initiating</em> device.
		* <p>
		* For a full discussion of the handover process and the APIs involved, see
		* {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}.
		* <p>
		* Implementations of this method should return an instance of {@link Connection} which
		* represents the handover. The code below shows an example of how this is done.
		* <pre>
		* {@code
		* public Connection onCreateIncomingHandoverConnection(PhoneAccountHandle
		* fromPhoneAccountHandle, ConnectionRequest request) {
		* // Given that your app requested to accept the handover, you should not return null here.
		* MyConnection connection = new MyConnection();
		* connection.setAddress(request.getAddress(), TelecomManager.PRESENTATION_ALLOWED);
		* connection.setVideoState(request.getVideoState());
		* return connection;
		* }
		* }
		* </pre>
		*
		* @param fromPhoneAccountHandle {@link PhoneAccountHandle} associated with the
		* ConnectionService which needs to handover the call.
		* @param request Details about the call which needs to be handover.
		* @return {@link Connection} object corresponding to the handover call.
		* @return {@link Connection} instance corresponding to the handover call.
		*/
		public Connection onCreateIncomingHandoverConnection(PhoneAccountHandle fromPhoneAccountHandle,
		ConnectionRequest request) {
		@@ -2251,11 +2323,15 @@ public abstract class ConnectionService extends Service {
		/**
		* Called by Telecom in response to a {@code TelecomManager#acceptHandover()}
		* invocation which failed.
		* @param request Details about the call which needs to be handover.
		* @param error Reason for handover failure as defined in
		* {@link android.telecom.Call.Callback#HANDOVER_FAILURE_DEST_INVALID_PERM}
		* <p>
		* For a full discussion of the handover process and the APIs involved, see
		* {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}
		*
		* @param request Details about the call which failed to handover.
		* @param error Reason for handover failure. Will be one of the
		*/
		public void onHandoverFailed(ConnectionRequest request, int error) {
		public void onHandoverFailed(ConnectionRequest request,
		@Call.Callback.HandoverFailureErrors int error) {
		return;
		}

telecomm/java/android/telecom/TelecomManager.java

+21 −3

Original line number	Diff line number	Diff line
		@@ -1794,8 +1794,25 @@ public class TelecomManager {
		}

		/**
		* Called from the recipient side of a handover to indicate a desire to accept the handover
		* of an ongoing call to another {@link ConnectionService} identified by
		* Called by an app to indicate that it wishes to accept the handover of an ongoing call to a
		* {@link PhoneAccountHandle} it defines.
		* <p>
		* A call handover is the process where an ongoing call is transferred from one app (i.e.
		* {@link ConnectionService} to another app. The user could, for example, choose to continue a
		* mobile network call in a video calling app. The mobile network call via the Telephony stack
		* is referred to as the source of the handover, and the video calling app is referred to as the
		* destination.
		* <p>
		* When considering a handover scenario the <em>initiating</em> device is where a user initiated
		* the handover process (e.g. by calling {@link android.telecom.Call#handoverTo(
		* PhoneAccountHandle, int, Bundle)}, and the other device is considered the <em>receiving</em>
		* device.
		* <p>
		* For a full discussion of the handover process and the APIs involved, see
		* {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}.
		* <p>
		* This method is called from the <em>receiving</em> side of a handover to indicate a desire to
		* accept the handover of an ongoing call to another {@link ConnectionService} identified by
		* {@link PhoneAccountHandle} destAcct. For managed {@link ConnectionService}s, the specified
		* {@link PhoneAccountHandle} must have been registered with {@link #registerPhoneAccount} and
		* the user must have enabled the corresponding {@link PhoneAccount}. This can be checked using
		@@ -1819,7 +1836,8 @@ public class TelecomManager {
		* @param videoState Video state after the handover.
		* @param destAcct The {@link PhoneAccountHandle} registered to the calling package.
		*/
		public void acceptHandover(Uri srcAddr, int videoState, PhoneAccountHandle destAcct) {
		public void acceptHandover(Uri srcAddr, @VideoProfile.VideoState int videoState,
		PhoneAccountHandle destAcct) {
		try {
		if (isServiceConnected()) {
		getTelecomService().acceptHandover(srcAddr, videoState, destAcct);

telecomm/java/android/telecom/VideoProfile.java

+1 −0

Original line number	Diff line number	Diff line
		@@ -62,6 +62,7 @@ public class VideoProfile implements Parcelable {
		@Retention(RetentionPolicy.SOURCE)
		@IntDef(
		flag = true,
		prefix = { "STATE_" },
		value = {STATE_AUDIO_ONLY, STATE_TX_ENABLED, STATE_RX_ENABLED, STATE_BIDIRECTIONAL,
		STATE_PAUSED})
		public @interface VideoState {}