API Review cleanups.
- New @SystemApis on Conference and PhoneAccount were missing the required
permissions annotations.
- Rename PROPERTY_ASSISTED_DIALING_USED to PROPERTY_ASSISTED_DIALING
- Standardize get/setConnectionStartElapsedRealtimeMillis method naming
across Connection and Conference classes.
- Clarify Conference#sendConferenceEvent API documentation to match the
docs present for similar method in Connection; include some examples of
valid event/extras combinations.
- Update TelecomManager#getDefaultdialerPackage to use UserHandle instead
of userId.
- Move Conference#getConnectionStartElapsedRealtimeMillis to public API
since the setter is already part of the public API.
Test: Run Telecom and Telephony CTS tests.
Test: Run Telephony unit tests.
Test: Perform manual single-party-conference regression test to confirm
that conference behavior does not regress.
Bug: 147301297
Bug: 148286830
Bug: 148284863
Bug: 148284843
Bug: 148287068
Bug: 148285484
Bug: 148285560
Change-Id: I1f446d81859fa109d74af3661a42a0bd224de5aa
Merged-In: I1f446d81859fa109d74af3661a42a0bd224de5aa
diff --git a/telecomm/java/android/telecom/Call.java b/telecomm/java/android/telecom/Call.java
index f54f8d1..005fcac 100644
--- a/telecomm/java/android/telecom/Call.java
+++ b/telecomm/java/android/telecom/Call.java
@@ -539,7 +539,7 @@
*
* @see TelecomManager#EXTRA_USE_ASSISTED_DIALING
*/
- public static final int PROPERTY_ASSISTED_DIALING_USED = 0x00000200;
+ public static final int PROPERTY_ASSISTED_DIALING = 0x00000200;
/**
* Indicates that the call is an RTT call. Use {@link #getRttCall()} to get the
@@ -743,7 +743,7 @@
if (hasProperty(properties, PROPERTY_HAS_CDMA_VOICE_PRIVACY)) {
builder.append(" PROPERTY_HAS_CDMA_VOICE_PRIVACY");
}
- if (hasProperty(properties, PROPERTY_ASSISTED_DIALING_USED)) {
+ if (hasProperty(properties, PROPERTY_ASSISTED_DIALING)) {
builder.append(" PROPERTY_ASSISTED_DIALING_USED");
}
if (hasProperty(properties, PROPERTY_NETWORK_IDENTIFIED_EMERGENCY_CALL)) {
diff --git a/telecomm/java/android/telecom/Conference.java b/telecomm/java/android/telecom/Conference.java
index 6b0845f..97fa2b4 100644
--- a/telecomm/java/android/telecom/Conference.java
+++ b/telecomm/java/android/telecom/Conference.java
@@ -16,8 +16,13 @@
package android.telecom;
+import static android.Manifest.permission.MODIFY_PHONE_STATE;
+
+import android.annotation.ElapsedRealtimeLong;
+import android.annotation.IntRange;
import android.annotation.NonNull;
import android.annotation.Nullable;
+import android.annotation.RequiresPermission;
import android.annotation.SystemApi;
import android.annotation.TestApi;
import android.net.Uri;
@@ -620,12 +625,12 @@
* Should be specified in wall-clock time returned by {@link System#currentTimeMillis()}.
* <p>
* When setting the connection time, you should always set the connection elapsed time via
- * {@link #setConnectionStartElapsedRealTime(long)} to ensure the duration is reflected.
+ * {@link #setConnectionStartElapsedRealtimeMillis(long)} to ensure the duration is reflected.
*
* @param connectionTimeMillis The connection time, in milliseconds, as returned by
* {@link System#currentTimeMillis()}.
*/
- public final void setConnectionTime(long connectionTimeMillis) {
+ public final void setConnectionTime(@IntRange(from = 0) long connectionTimeMillis) {
mConnectTimeMillis = connectionTimeMillis;
}
@@ -641,8 +646,28 @@
*
* @param connectionStartElapsedRealTime The connection time, as measured by
* {@link SystemClock#elapsedRealtime()}.
+ * @deprecated use {@link #setConnectionStartElapsedRealtimeMillis(long)} instead.
*/
+ @Deprecated
public final void setConnectionStartElapsedRealTime(long connectionStartElapsedRealTime) {
+ setConnectionStartElapsedRealtimeMillis(connectionStartElapsedRealTime);
+ }
+
+ /**
+ * Sets the start time of the {@link Conference} which is the basis for the determining the
+ * duration of the {@link Conference}.
+ * <p>
+ * You should use a value returned by {@link SystemClock#elapsedRealtime()} to ensure that time
+ * zone changes do not impact the conference duration.
+ * <p>
+ * When setting this, you should also set the connection time via
+ * {@link #setConnectionTime(long)}.
+ *
+ * @param connectionStartElapsedRealTime The connection time, as measured by
+ * {@link SystemClock#elapsedRealtime()}.
+ */
+ public final void setConnectionStartElapsedRealtimeMillis(
+ @ElapsedRealtimeLong long connectionStartElapsedRealTime) {
mConnectionStartElapsedRealTime = connectionStartElapsedRealTime;
}
@@ -663,7 +688,7 @@
*
* @return The time at which the {@code Conference} was connected.
*/
- public final long getConnectionTime() {
+ public final @IntRange(from = 0) long getConnectionTime() {
return mConnectTimeMillis;
}
@@ -680,11 +705,8 @@
* has no general use other than to the Telephony framework.
*
* @return The elapsed time at which the {@link Conference} was connected.
- * @hide
*/
- @SystemApi
- @TestApi
- public final long getConnectionStartElapsedRealTime() {
+ public final @ElapsedRealtimeLong long getConnectionStartElapsedRealtimeMillis() {
return mConnectionStartElapsedRealTime;
}
@@ -981,6 +1003,7 @@
*/
@SystemApi
@TestApi
+ @RequiresPermission(MODIFY_PHONE_STATE)
public void setConferenceState(boolean isConference) {
for (Listener l : mListeners) {
l.onConferenceStateChanged(this, isConference);
@@ -1001,6 +1024,7 @@
*/
@SystemApi
@TestApi
+ @RequiresPermission(MODIFY_PHONE_STATE)
public final void setAddress(@NonNull Uri address,
@TelecomManager.Presentation int presentation) {
Log.d(this, "setAddress %s", address);
@@ -1107,12 +1131,52 @@
}
/**
- * Sends an event associated with this {@code Conference} with associated event extras to the
- * {@link InCallService} (note: this is identical in concept to
- * {@link Connection#sendConnectionEvent(String, Bundle)}).
- * @see Connection#sendConnectionEvent(String, Bundle)
+ * Sends an event associated with this {@link Conference} with associated event extras to the
+ * {@link InCallService}.
+ * <p>
+ * Connection events are used to communicate point in time information from a
+ * {@link ConnectionService} to an {@link InCallService} implementation. An example of a
+ * custom connection event includes notifying the UI when a WIFI call has been handed over to
+ * LTE, which the InCall UI might use to inform the user that billing charges may apply. The
+ * Android Telephony framework will send the {@link Connection#EVENT_MERGE_COMPLETE}
+ * connection event when a call to {@link Call#mergeConference()} has completed successfully.
+ * <p>
+ * Events are exposed to {@link InCallService} implementations via
+ * {@link Call.Callback#onConnectionEvent(Call, String, Bundle)}.
+ * <p>
+ * No assumptions should be made as to how an In-Call UI or service will handle these events.
+ * The {@link ConnectionService} must assume that the In-Call UI could even chose to ignore
+ * some events altogether.
+ * <p>
+ * Events should be fully qualified (e.g. {@code com.example.event.MY_EVENT}) to avoid
+ * conflicts between {@link ConnectionService} implementations. Further, custom
+ * {@link ConnectionService} implementations shall not re-purpose events in the
+ * {@code android.*} namespace, nor shall they define new event types in this namespace. When
+ * defining a custom event type, ensure the contents of the extras {@link Bundle} is clearly
+ * defined. Extra keys for this bundle should be named similar to the event type (e.g.
+ * {@code com.example.extra.MY_EXTRA}).
+ * <p>
+ * When defining events and the associated extras, it is important to keep their behavior
+ * consistent when the associated {@link ConnectionService} is updated. Support for deprecated
+ * events/extras should me maintained to ensure backwards compatibility with older
+ * {@link InCallService} implementations which were built to support the older behavior.
+ * <p>
+ * Expected connection events from the Telephony stack are:
+ * <p>
+ * <ul>
+ * <li>{@link Connection#EVENT_CALL_HOLD_FAILED} with {@code null} {@code extras} when the
+ * {@link Conference} could not be held.</li>
+ * <li>{@link Connection#EVENT_MERGE_START} with {@code null} {@code extras} when a new
+ * call is being merged into the conference.</li>
+ * <li>{@link Connection#EVENT_MERGE_COMPLETE} with {@code null} {@code extras} a new call
+ * has completed being merged into the conference.</li>
+ * <li>{@link Connection#EVENT_CALL_MERGE_FAILED} with {@code null} {@code extras} a new
+ * call has failed to merge into the conference (the dialer app can determine which call
+ * failed to merge based on the fact that the call still exists outside of the conference
+ * at the end of the merge process).</li>
+ * </ul>
*
- * @param event The connection event.
+ * @param event The conference event.
* @param extras Optional bundle containing extra information associated with the event.
*/
public void sendConferenceEvent(@NonNull String event, @Nullable Bundle extras) {
diff --git a/telecomm/java/android/telecom/Connection.java b/telecomm/java/android/telecom/Connection.java
index 72c66d2..7e5e32d 100644
--- a/telecomm/java/android/telecom/Connection.java
+++ b/telecomm/java/android/telecom/Connection.java
@@ -16,9 +16,14 @@
package android.telecom;
+import static android.Manifest.permission.MODIFY_PHONE_STATE;
+
+import android.annotation.ElapsedRealtimeLong;
import android.annotation.IntDef;
+import android.annotation.IntRange;
import android.annotation.NonNull;
import android.annotation.Nullable;
+import android.annotation.RequiresPermission;
import android.annotation.SystemApi;
import android.annotation.TestApi;
import android.app.Notification;
@@ -474,7 +479,7 @@
*
* @see TelecomManager#EXTRA_USE_ASSISTED_DIALING
*/
- public static final int PROPERTY_ASSISTED_DIALING_USED = 1 << 9;
+ public static final int PROPERTY_ASSISTED_DIALING = 1 << 9;
/**
* Set by the framework to indicate that the network has identified a Connection as an emergency
@@ -2109,19 +2114,24 @@
*/
@SystemApi
@TestApi
- public final long getConnectTimeMillis() {
+ public final @IntRange(from = 0) long getConnectTimeMillis() {
return mConnectTimeMillis;
}
/**
* Retrieves the connection start time of the {@link Connection}, if specified. A value of
* {@link Conference#CONNECT_TIME_NOT_SPECIFIED} indicates that Telecom should determine the
- * start time of the conference.
+ * start time of the connection.
* <p>
* Based on the value of {@link SystemClock#elapsedRealtime()}, which ensures that wall-clock
* changes do not impact the call duration.
* <p>
* Used internally in Telephony when migrating conference participant data for IMS conferences.
+ * <p>
+ * The value returned is the same one set using
+ * {@link #setConnectionStartElapsedRealtimeMillis(long)}. This value is never updated from
+ * the Telecom framework, so no permission enforcement occurs when retrieving the value with
+ * this method.
*
* @return The time at which the {@link Connection} was connected.
*
@@ -2129,7 +2139,7 @@
*/
@SystemApi
@TestApi
- public final long getConnectElapsedTimeMillis() {
+ public final @ElapsedRealtimeLong long getConnectionStartElapsedRealtimeMillis() {
return mConnectElapsedTimeMillis;
}
@@ -2550,6 +2560,9 @@
* Sets the time at which a call became active on this Connection. This is set only
* when a conference call becomes active on this connection.
* <p>
+ * This time corresponds to the date/time of connection and is stored in the call log in
+ * {@link android.provider.CallLog.Calls#DATE}.
+ * <p>
* Used by telephony to maintain calls associated with an IMS Conference.
*
* @param connectTimeMillis The connection time, in milliseconds. Should be set using a value
@@ -2559,7 +2572,8 @@
*/
@SystemApi
@TestApi
- public final void setConnectTimeMillis(long connectTimeMillis) {
+ @RequiresPermission(MODIFY_PHONE_STATE)
+ public final void setConnectTimeMillis(@IntRange(from = 0) long connectTimeMillis) {
mConnectTimeMillis = connectTimeMillis;
}
@@ -2567,15 +2581,23 @@
* Sets the time at which a call became active on this Connection. This is set only
* when a conference call becomes active on this connection.
* <p>
+ * This time is used to establish the duration of a call. It uses
+ * {@link SystemClock#elapsedRealtime()} to ensure that the call duration is not impacted by
+ * time zone changes during a call. The difference between the current
+ * {@link SystemClock#elapsedRealtime()} and the value set at the connection start time is used
+ * to populate {@link android.provider.CallLog.Calls#DURATION} in the call log.
+ * <p>
* Used by telephony to maintain calls associated with an IMS Conference.
+ *
* @param connectElapsedTimeMillis The connection time, in milliseconds. Stored in the format
* {@link SystemClock#elapsedRealtime()}.
- *
* @hide
*/
@SystemApi
@TestApi
- public final void setConnectionStartElapsedRealTime(long connectElapsedTimeMillis) {
+ @RequiresPermission(MODIFY_PHONE_STATE)
+ public final void setConnectionStartElapsedRealtimeMillis(
+ @ElapsedRealtimeLong long connectElapsedTimeMillis) {
mConnectElapsedTimeMillis = connectElapsedTimeMillis;
}
diff --git a/telecomm/java/android/telecom/ConnectionService.java b/telecomm/java/android/telecom/ConnectionService.java
index 00c2918..f77e529 100644
--- a/telecomm/java/android/telecom/ConnectionService.java
+++ b/telecomm/java/android/telecom/ConnectionService.java
@@ -18,7 +18,6 @@
import android.annotation.NonNull;
import android.annotation.Nullable;
-import android.annotation.RequiresPermission;
import android.annotation.SdkConstant;
import android.annotation.SystemApi;
import android.app.Service;
@@ -1778,7 +1777,7 @@
null : conference.getVideoProvider().getInterface(),
conference.getVideoState(),
conference.getConnectTimeMillis(),
- conference.getConnectionStartElapsedRealTime(),
+ conference.getConnectionStartElapsedRealtimeMillis(),
conference.getStatusHints(),
conference.getExtras(),
conference.getAddress(),
@@ -1884,7 +1883,7 @@
connection.isRingbackRequested(),
connection.getAudioModeIsVoip(),
connection.getConnectTimeMillis(),
- connection.getConnectElapsedTimeMillis(),
+ connection.getConnectionStartElapsedRealtimeMillis(),
connection.getStatusHints(),
connection.getDisconnectCause(),
createIdList(connection.getConferenceables()),
@@ -2374,7 +2373,7 @@
null : conference.getVideoProvider().getInterface(),
conference.getVideoState(),
conference.getConnectTimeMillis(),
- conference.getConnectionStartElapsedRealTime(),
+ conference.getConnectionStartElapsedRealtimeMillis(),
conference.getStatusHints(),
conference.getExtras(),
conference.getAddress(),
@@ -2465,7 +2464,7 @@
connection.isRingbackRequested(),
connection.getAudioModeIsVoip(),
connection.getConnectTimeMillis(),
- connection.getConnectElapsedTimeMillis(),
+ connection.getConnectionStartElapsedRealtimeMillis(),
connection.getStatusHints(),
connection.getDisconnectCause(),
emptyList,
diff --git a/telecomm/java/android/telecom/PhoneAccount.java b/telecomm/java/android/telecom/PhoneAccount.java
index abb210f..6ae4a08 100644
--- a/telecomm/java/android/telecom/PhoneAccount.java
+++ b/telecomm/java/android/telecom/PhoneAccount.java
@@ -16,7 +16,10 @@
package android.telecom;
+import static android.Manifest.permission.MODIFY_PHONE_STATE;
+
import android.annotation.NonNull;
+import android.annotation.RequiresPermission;
import android.annotation.SystemApi;
import android.annotation.TestApi;
import android.content.Intent;
@@ -605,7 +608,8 @@
* time. By default, there is no group Id for a {@link PhoneAccount} (an empty String). Only
* grouped {@link PhoneAccount}s with the same {@link ConnectionService} can be replaced.
* <p>
- * Note: This is an API specific to the Telephony stack.
+ * Note: This is an API specific to the Telephony stack; the group Id will be ignored for
+ * callers not holding the correct permission.
*
* @param groupId The group Id of the {@link PhoneAccount} that will replace any other
* registered {@link PhoneAccount} in Telecom with the same Group Id.
@@ -614,6 +618,7 @@
*/
@SystemApi
@TestApi
+ @RequiresPermission(MODIFY_PHONE_STATE)
public @NonNull Builder setGroupId(@NonNull String groupId) {
if (groupId != null) {
mGroupId = groupId;
diff --git a/telecomm/java/android/telecom/TelecomManager.java b/telecomm/java/android/telecom/TelecomManager.java
index f1dca03..5c4c3b1c 100644
--- a/telecomm/java/android/telecom/TelecomManager.java
+++ b/telecomm/java/android/telecom/TelecomManager.java
@@ -802,8 +802,8 @@
* automatically add dialing prefixes when placing international calls.
* <p>
* Setting this extra on the outgoing call extras will cause the
- * {@link Connection#PROPERTY_ASSISTED_DIALING_USED} property and
- * {@link Call.Details#PROPERTY_ASSISTED_DIALING_USED} property to be set on the
+ * {@link Connection#PROPERTY_ASSISTED_DIALING} property and
+ * {@link Call.Details#PROPERTY_ASSISTED_DIALING} property to be set on the
* {@link Connection}/{@link Call} in question. When the call is logged to the call log, the
* {@link android.provider.CallLog.Calls#FEATURES_ASSISTED_DIALING_USED} call feature is set to
* indicate that assisted dialing was used for the call.
@@ -1368,7 +1368,7 @@
/**
* Used to determine the currently selected default dialer package for a specific user.
*
- * @param userId the user id to query the default dialer package for.
+ * @param userHandle the user id to query the default dialer package for.
* @return package name for the default dialer package or null if no package has been
* selected as the default dialer.
* @hide
@@ -1376,10 +1376,11 @@
@SystemApi
@TestApi
@RequiresPermission(READ_PRIVILEGED_PHONE_STATE)
- public @Nullable String getDefaultDialerPackage(int userId) {
+ public @Nullable String getDefaultDialerPackage(@NonNull UserHandle userHandle) {
try {
if (isServiceConnected()) {
- return getTelecomService().getDefaultDialerPackageForUser(userId);
+ return getTelecomService().getDefaultDialerPackageForUser(
+ userHandle.getIdentifier());
}
} catch (RemoteException e) {
Log.e(TAG, "RemoteException attempting to get the default dialer package name.", e);