Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

API Documentation and Constant cleanup.

Browse Source 
1. Update handover API docs for clarity.
2. Added an unknown value per API review comments.
3. Renamed HANDOVER_FAILURE_DEST_USER_REJECTED to
HANDOVER_FAILURE_USER_REJECTED
3. Removed the HANDOVER_FAILURE_DEST_INVALID_PERM constant since it isn't
used (methods which deal with permissions throw security exceptions).

Test: Make doc and verify documentation.
Change-Id: Id21d6b4c83d5c773ab38d78eb6b1886a1ac4dadf
Fixes: 73751004
Fixes: 73750515
Fixes: 73750817
This commit is contained in:
Tyler Gunn
2018-03-02 15:45:51 -08:00
parent d7187c90d0
commit 9d12773b51
5 changed files with 227 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
telecomm/java/android/telecom/ConnectionService.java
View File

@@ -2219,12 +2219,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) {
@@ -2232,12 +2270,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) {
@@ -2247,11 +2319,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;
}