Skip to content

Commit

Permalink
Merge changes from topic "phonenumber"
Browse files Browse the repository at this point in the history 
* changes:
  Update javadocs based on API council feedback.
  Deprecate get/setLine1Number in favor of get/setPhoneNumber
  • Loading branch information
Meng Wang authored and Gerrit Code Review committed Jan 7, 2022
2 parents d35cd45 + 72afc76 commit 886bf03
Show file tree
Hide file tree
Showing 5 changed files with 45 additions and 23 deletions.
14 changes: 7 additions & 7 deletions core/api/current.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40517,7 +40517,7 @@ package android.telecom {
method @RequiresPermission(android.Manifest.permission.READ_PHONE_STATE) public java.util.List<android.telecom.PhoneAccountHandle> getCallCapablePhoneAccounts();
method public String getDefaultDialerPackage();
method @RequiresPermission(android.Manifest.permission.READ_PHONE_STATE) public android.telecom.PhoneAccountHandle getDefaultOutgoingPhoneAccount(String);
method @RequiresPermission(anyOf={android.Manifest.permission.READ_PHONE_STATE, android.Manifest.permission.READ_SMS, android.Manifest.permission.READ_PHONE_NUMBERS}, conditional=true) public String getLine1Number(android.telecom.PhoneAccountHandle);
method @Deprecated @RequiresPermission(anyOf={android.Manifest.permission.READ_PHONE_STATE, android.Manifest.permission.READ_SMS, android.Manifest.permission.READ_PHONE_NUMBERS}, conditional=true) public String getLine1Number(android.telecom.PhoneAccountHandle);
method public android.telecom.PhoneAccount getPhoneAccount(android.telecom.PhoneAccountHandle);
method @RequiresPermission(android.Manifest.permission.READ_PHONE_STATE) public java.util.List<android.telecom.PhoneAccountHandle> getSelfManagedPhoneAccounts();
method public android.telecom.PhoneAccountHandle getSimCallManager();
Expand Down Expand Up @@ -42583,7 +42583,7 @@ package android.telephony {
method @Nullable public String getMccString();
method @Deprecated public int getMnc();
method @Nullable public String getMncString();
method public String getNumber();
method @Deprecated public String getNumber();
method public int getPortIndex();
method public int getSimSlotIndex();
method public int getSubscriptionId();
Expand Down Expand Up @@ -42617,8 +42617,8 @@ package android.telephony {
method @NonNull public java.util.List<android.net.Uri> getDeviceToDeviceStatusSharingContacts(int);
method public int getDeviceToDeviceStatusSharingPreference(int);
method @NonNull @RequiresPermission(android.Manifest.permission.READ_PHONE_STATE) public java.util.List<android.telephony.SubscriptionInfo> getOpportunisticSubscriptions();
method @NonNull @RequiresPermission(anyOf={android.Manifest.permission.READ_PHONE_NUMBERS, "android.permission.READ_PRIVILEGED_PHONE_STATE"}) public String getPhoneNumber(int, int);
method @NonNull @RequiresPermission(anyOf={android.Manifest.permission.READ_PHONE_NUMBERS, "android.permission.READ_PRIVILEGED_PHONE_STATE"}) public String getPhoneNumber(int);
method @NonNull @RequiresPermission(anyOf={android.Manifest.permission.READ_PHONE_NUMBERS, "android.permission.READ_PRIVILEGED_PHONE_STATE", "carrier privileges"}) public String getPhoneNumber(int, int);
method @NonNull @RequiresPermission(anyOf={android.Manifest.permission.READ_PHONE_NUMBERS, "android.permission.READ_PRIVILEGED_PHONE_STATE", "carrier privileges"}) public String getPhoneNumber(int);
method public static int getSlotIndex(int);
method @Nullable public int[] getSubscriptionIds(int);
method @NonNull public java.util.List<android.telephony.SubscriptionPlan> getSubscriptionPlans(int);
Expand All @@ -42630,7 +42630,7 @@ package android.telephony {
method public void removeOnOpportunisticSubscriptionsChangedListener(@NonNull android.telephony.SubscriptionManager.OnOpportunisticSubscriptionsChangedListener);
method public void removeOnSubscriptionsChangedListener(android.telephony.SubscriptionManager.OnSubscriptionsChangedListener);
method @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public void removeSubscriptionsFromGroup(@NonNull java.util.List<java.lang.Integer>, @NonNull android.os.ParcelUuid);
method public void setCarrierPhoneNumber(int, @NonNull String);
method @RequiresPermission("carrier privileges") public void setCarrierPhoneNumber(int, @NonNull String);
method @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public void setDeviceToDeviceStatusSharingContacts(int, @NonNull java.util.List<android.net.Uri>);
method @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public void setDeviceToDeviceStatusSharingPreference(int, int);
method @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public boolean setOpportunistic(boolean, int);
Expand Down Expand Up @@ -42838,7 +42838,7 @@ package android.telephony {
method public String getIccAuthentication(int, int, String);
method @RequiresPermission("android.permission.READ_PRIVILEGED_PHONE_STATE") public String getImei();
method @RequiresPermission("android.permission.READ_PRIVILEGED_PHONE_STATE") public String getImei(int);
method @RequiresPermission(anyOf={android.Manifest.permission.READ_PHONE_STATE, android.Manifest.permission.READ_SMS, android.Manifest.permission.READ_PHONE_NUMBERS}) public String getLine1Number();
method @Deprecated @RequiresPermission(anyOf={android.Manifest.permission.READ_PHONE_STATE, android.Manifest.permission.READ_SMS, android.Manifest.permission.READ_PHONE_NUMBERS}) public String getLine1Number();
method @NonNull @RequiresPermission(android.Manifest.permission.READ_PRECISE_PHONE_STATE) public String getManualNetworkSelectionPlmn();
method @Nullable public String getManufacturerCode();
method @Nullable public String getManufacturerCode(int);
Expand Down Expand Up @@ -42926,7 +42926,7 @@ package android.telephony {
method @Deprecated @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public void setDataEnabled(boolean);
method @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public void setDataEnabledForReason(int, boolean);
method @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public int setForbiddenPlmns(@NonNull java.util.List<java.lang.String>);
method public boolean setLine1NumberForDisplay(String, String);
method @Deprecated public boolean setLine1NumberForDisplay(String, String);
method @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public void setNetworkSelectionModeAutomatic();
method @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public boolean setNetworkSelectionModeManual(String, boolean);
method @RequiresPermission(android.Manifest.permission.MODIFY_PHONE_STATE) public boolean setNetworkSelectionModeManual(@NonNull String, boolean, int);
Expand Down
4 changes: 4 additions & 0 deletions telecomm/java/android/telecom/TelecomManager.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1692,7 +1692,11 @@ public String getVoiceMailNumber(PhoneAccountHandle accountHandle) {
*
* @param accountHandle The handle for the account retrieve a number for.
* @return A string representation of the line 1 phone number.
* @deprecated use {@link SubscriptionManager#getPhoneNumber(int)} instead, which takes a
* Telephony Subscription ID that can be retrieved with the {@code accountHandle}
* from {@link TelephonyManager#getSubscriptionId(PhoneAccountHandle)}.
*/
@Deprecated
@SuppressAutoDoc // Blocked by b/72967236 - no support for carrier privileges or default SMS app
@RequiresPermission(anyOf = {
android.Manifest.permission.READ_PHONE_STATE,
Expand Down
3 changes: 3 additions & 0 deletions telephony/java/android/telephony/SubscriptionInfo.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -498,7 +498,10 @@ public void setIconTint(int iconTint) {
*
* @return the number of this subscription, or an empty string if one of these requirements is
* not met
* @deprecated use {@link SubscriptionManager#getPhoneNumber(int)} instead, which takes a
* {@link #getSubscriptionId() subscription ID}.
*/
@Deprecated
public String getNumber() {
return mNumber;
}
Expand Down
38 changes: 22 additions & 16 deletions telephony/java/android/telephony/SubscriptionManager.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3811,14 +3811,21 @@ public void restoreAllSimSpecificSettingsFromBackup(@NonNull byte[] data) {
}

/**
* Returns the phone number for the given {@code subId} and {@code source},
* Returns the phone number for the given {@code subscriptionId} and {@code source},
* or an empty string if not available.
*
* <p>Requires Permission:
* {@link android.Manifest.permission#READ_PHONE_NUMBERS READ_PHONE_NUMBERS}, or
* READ_PRIVILEGED_PHONE_STATE permission (can only be granted to apps preloaded on device),
* or that the calling app has carrier privileges
* (see {@link TelephonyManager#hasCarrierPrivileges}).
* <p>General apps that need to know the phone number should use {@link #getPhoneNumber(int)}
* instead. This API may be suitable specific apps that needs to know the phone number from
* a specific source. For example, a carrier app needs to know exactly what's on
* {@link #PHONE_NUMBER_SOURCE_UICC UICC} and decide if the previously set phone number
* of source {@link #PHONE_NUMBER_SOURCE_CARRIER carrier} should be updated.
*
* <p>Note the assumption is that one subscription (which usually means one SIM) has
* only one phone number. The multiple sources backup each other so hopefully at least one
* is availavle. For example, for a carrier that doesn't typically set phone numbers
* on {@link #PHONE_NUMBER_SOURCE_UICC UICC}, the source {@link #PHONE_NUMBER_SOURCE_IMS IMS}
* may provide one. Or, a carrier may decide to provide the phone number via source
* {@link #PHONE_NUMBER_SOURCE_CARRIER carrier} if neither source UICC nor IMS is available.
*
* @param subscriptionId the subscription ID, or {@link #DEFAULT_SUBSCRIPTION_ID}
* for the default one.
Expand All @@ -3831,10 +3838,10 @@ public void restoreAllSimSpecificSettingsFromBackup(@NonNull byte[] data) {
* @see #PHONE_NUMBER_SOURCE_CARRIER
* @see #PHONE_NUMBER_SOURCE_IMS
*/
@SuppressAutoDoc // No support for carrier privileges (b/72967236)
@RequiresPermission(anyOf = {
android.Manifest.permission.READ_PHONE_NUMBERS,
android.Manifest.permission.READ_PRIVILEGED_PHONE_STATE,
"carrier privileges",
})
@NonNull
public String getPhoneNumber(int subscriptionId, @PhoneNumberSource int source) {
Expand Down Expand Up @@ -3863,27 +3870,25 @@ public String getPhoneNumber(int subscriptionId, @PhoneNumberSource int source)
* Returns the phone number for the given {@code subId}, or an empty string if
* not available.
*
* <p>This API is suitable for general apps that needs to know the phone number.
* For specific apps that needs to know the phone number provided by a specific source,
* {@link #getPhoneNumber(int, int)} may be suitable.
*
* <p>This API is built up on {@link #getPhoneNumber(int, int)}, but picks
* from available sources in the following order: {@link #PHONE_NUMBER_SOURCE_CARRIER}
* > {@link #PHONE_NUMBER_SOURCE_UICC} > {@link #PHONE_NUMBER_SOURCE_IMS}.
*
* <p>Requires Permission:
* {@link android.Manifest.permission#READ_PHONE_NUMBERS READ_PHONE_NUMBERS}, or
* READ_PRIVILEGED_PHONE_STATE permission (can only be granted to apps preloaded on device),
* or that the calling app has carrier privileges
* (see {@link TelephonyManager#hasCarrierPrivileges}).
*
* @param subscriptionId the subscription ID, or {@link #DEFAULT_SUBSCRIPTION_ID}
* for the default one.
* @return the phone number, or an empty string if not available.
* @throws IllegalStateException if the telephony process is not currently available.
* @throws SecurityException if the caller doesn't have permissions required.
* @see #getPhoneNumber(int, int)
*/
@SuppressAutoDoc // No support for carrier privileges (b/72967236)
@RequiresPermission(anyOf = {
android.Manifest.permission.READ_PHONE_NUMBERS,
android.Manifest.permission.READ_PRIVILEGED_PHONE_STATE,
"carrier privileges",
})
@NonNull
public String getPhoneNumber(int subscriptionId) {
Expand All @@ -3908,8 +3913,8 @@ public String getPhoneNumber(int subscriptionId) {
* {@link #PHONE_NUMBER_SOURCE_CARRIER carrier}.
* Sets an empty string to remove the previously set phone number.
*
* <p>Requires Permission: the calling app has carrier privileges
* (see {@link TelephonyManager#hasCarrierPrivileges}).
* <p>The API is suitable for carrier apps to provide a phone number, for example when
* it's not possible to update {@link #PHONE_NUMBER_SOURCE_UICC UICC} directly.
*
* @param subscriptionId the subscription ID, or {@link #DEFAULT_SUBSCRIPTION_ID}
* for the default one.
Expand All @@ -3918,6 +3923,7 @@ public String getPhoneNumber(int subscriptionId) {
* @throws NullPointerException if {@code number} is {@code null}.
* @throws SecurityException if the caller doesn't have permissions required.
*/
@RequiresPermission("carrier privileges")
public void setCarrierPhoneNumber(int subscriptionId, @NonNull String number) {
if (subscriptionId == DEFAULT_SUBSCRIPTION_ID) {
subscriptionId = getDefaultSubscriptionId();
Expand Down
9 changes: 9 additions & 0 deletions telephony/java/android/telephony/TelephonyManager.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4801,7 +4801,10 @@ public String getGroupIdLevel1(int subId) {
* for any API level.
* {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE}
* for apps targeting SDK API level 29 and below.
*
* @deprecated use {@link SubscriptionManager#getPhoneNumber(int)} instead.
*/
@Deprecated
@SuppressAutoDoc // Blocked by b/72967236 - no support for carrier privileges or default SMS app
@RequiresPermission(anyOf = {
android.Manifest.permission.READ_PHONE_STATE,
Expand Down Expand Up @@ -4874,7 +4877,9 @@ public String getLine1Number(int subId) {
* @param alphaTag alpha-tagging of the dailing nubmer
* @param number The dialing number
* @return true if the operation was executed correctly.
* @deprecated use {@link SubscriptionManager#setCarrierPhoneNumber(int, String)} instead.
*/
@Deprecated
public boolean setLine1NumberForDisplay(String alphaTag, String number) {
return setLine1NumberForDisplay(getSubId(), alphaTag, number);
}
Expand All @@ -4895,6 +4900,10 @@ public boolean setLine1NumberForDisplay(String alphaTag, String number) {
*/
public boolean setLine1NumberForDisplay(int subId, String alphaTag, String number) {
try {
// This API is deprecated; call the new API to allow smooth migartion.
// The new API doesn't accept null so convert null to empty string.
mSubscriptionManager.setCarrierPhoneNumber(subId, (number == null ? "" : number));

ITelephony telephony = getITelephony();
if (telephony != null)
return telephony.setLine1NumberForDisplayForSubscriber(subId, alphaTag, number);
Expand Down

0 comments on commit 886bf03

Please sign in to comment.