Add docs and more annotations
Add docs to some constants in PhoneAccountSuggestion and add @TestApi
annotations to enable CTS testing for the new APIs.
Test: compiles
Bug: 111455117
Change-Id: I2b55a411ff4f0da37eefa0996f7316ea53bca41d
diff --git a/telecomm/java/android/telecom/Call.java b/telecomm/java/android/telecom/Call.java
index cef99865..bf0ffb9 100644
--- a/telecomm/java/android/telecom/Call.java
+++ b/telecomm/java/android/telecom/Call.java
@@ -123,10 +123,21 @@
* The key to retrieve the optional {@code PhoneAccount}s Telecom can bundle with its Call
* extras. Used to pass the phone accounts to display on the front end to the user in order to
* select phone accounts to (for example) place a call.
+ * @deprecated Use the list from {@link #EXTRA_SUGGESTED_PHONE_ACCOUNTS} instead.
*/
+ @Deprecated
public static final String AVAILABLE_PHONE_ACCOUNTS = "selectPhoneAccountAccounts";
/**
+ * Key for extra used to pass along a list of {@link PhoneAccountSuggestion}s to the in-call
+ * UI when a call enters the {@link #STATE_SELECT_PHONE_ACCOUNT} state. The list included here
+ * will have the same length and be in the same order as the list passed with
+ * {@link #AVAILABLE_PHONE_ACCOUNTS}.
+ */
+ public static final String EXTRA_SUGGESTED_PHONE_ACCOUNTS =
+ "android.telecom.extra.SUGGESTED_PHONE_ACCOUNTS";
+
+ /**
* Extra key used to indicate the time (in milliseconds since midnight, January 1, 1970 UTC)
* when the last outgoing emergency call was made. This is used to identify potential emergency
* callbacks.
diff --git a/telecomm/java/android/telecom/PhoneAccountSuggestion.java b/telecomm/java/android/telecom/PhoneAccountSuggestion.java
index cea5bee..4e6a178 100644
--- a/telecomm/java/android/telecom/PhoneAccountSuggestion.java
+++ b/telecomm/java/android/telecom/PhoneAccountSuggestion.java
@@ -1,7 +1,24 @@
+/*
+ * Copyright (C) 2018 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 android.telecom;
import android.annotation.IntDef;
import android.annotation.SystemApi;
+import android.annotation.TestApi;
import android.os.Parcel;
import android.os.Parcelable;
@@ -16,10 +33,33 @@
REASON_USER_SET, REASON_OTHER}, prefix = { "REASON_" })
public @interface SuggestionReason {}
+ /**
+ * Indicates that this account is not suggested for use, but is still available.
+ */
public static final int REASON_NONE = 0;
+
+ /**
+ * Indicates that the {@link PhoneAccountHandle} is suggested because the number we're calling
+ * is on the same carrier, and therefore may have lower rates.
+ */
public static final int REASON_INTRA_CARRIER = 1;
+
+ /**
+ * Indicates that the {@link PhoneAccountHandle} is suggested because the user uses it
+ * frequently for the number that we are calling.
+ */
public static final int REASON_FREQUENT = 2;
+
+ /**
+ * Indicates that the {@link PhoneAccountHandle} is suggested because the user explicitly
+ * specified that it be used for the number we are calling.
+ */
public static final int REASON_USER_SET = 3;
+
+ /**
+ * Indicates that the {@link PhoneAccountHandle} is suggested for a reason not otherwise
+ * enumerated here.
+ */
public static final int REASON_OTHER = 4;
private PhoneAccountHandle mHandle;
@@ -30,6 +70,7 @@
* @hide
*/
@SystemApi
+ @TestApi
public PhoneAccountSuggestion(PhoneAccountHandle handle, @SuggestionReason int reason,
boolean shouldAutoSelect) {
this.mHandle = handle;
@@ -56,14 +97,26 @@
}
};
- public PhoneAccountHandle getHandle() {
+ /**
+ * @return The {@link PhoneAccountHandle} for this suggestion.
+ */
+ public PhoneAccountHandle getPhoneAccountHandle() {
return mHandle;
}
+ /**
+ * @return The reason for this suggestion
+ */
public @SuggestionReason int getReason() {
return mReason;
}
+ /**
+ * Suggests whether the dialer should automatically place the call using this account without
+ * user interaction. This may be set on multiple {@link PhoneAccountSuggestion}s, and the dialer
+ * is free to choose which one to use.
+ * @return {@code true} if the hint is to auto-select, {@code false} otherwise.
+ */
public boolean shouldAutoSelect() {
return mShouldAutoSelect;
}