Add additional info to device ID docs in TelephonyManager and Build
Android 10 introduced additional restrictions to access persistent
device identifiers. This commit updates the javadocs for
TelephonyManager and Build to provide additional details regarding
the requirements and how to check if these requirements are met.
Fixes: 158471988
Test: m docs -j
Change-Id: I02932a22ecc5b761aa1a92d59d09d31863c34235
diff --git a/core/java/android/os/Build.java b/core/java/android/os/Build.java
index ef2a8a1..b36aeb8 100755
--- a/core/java/android/os/Build.java
+++ b/core/java/android/os/Build.java
@@ -133,12 +133,23 @@
* <a href="/training/articles/security-key-attestation.html">key attestation</a> to obtain
* proof of the device's original identifiers.
*
- * <p>Requires Permission: READ_PRIVILEGED_PHONE_STATE, for the calling app to be the device or
- * profile owner and have the READ_PHONE_STATE permission, or that the calling app has carrier
- * privileges (see {@link android.telephony.TelephonyManager#hasCarrierPrivileges}). The profile
- * owner is an app that owns a managed profile on the device; for more details see <a
- * href="https://developer.android.com/work/managed-profiles">Work profiles</a>. Profile owner
- * access is deprecated and will be removed in a future release.
+ * <p>Starting with API level 29, persistent device identifiers are guarded behind additional
+ * restrictions, and apps are recommended to use resettable identifiers (see <a
+ * href="c"> Best practices for unique identifiers</a>). This method can be invoked if one of
+ * the following requirements is met:
+ * <ul>
+ * <li>If the calling app has been granted the READ_PRIVILEGED_PHONE_STATE permission; this
+ * is a privileged permission that can only be granted to apps preloaded on the device.
+ * <li>If the calling app is the device or profile owner and has been granted the
+ * {@link Manifest.permission#READ_PHONE_STATE} permission. The profile owner is an app that
+ * owns a managed profile on the device; for more details see <a
+ * href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
+ * Profile owner access is deprecated and will be removed in a future release.
+ * <li>If the calling app has carrier privileges (see {@link
+ * android.telephony.TelephonyManager#hasCarrierPrivileges}) on any active subscription.
+ * <li>If the calling app is the default SMS role holder (see {@link
+ * android.app.role.RoleManager#isRoleHeld(String)}).
+ * </ul>
*
* <p>If the calling app does not meet one of these requirements then this method will behave
* as follows:
@@ -150,7 +161,7 @@
* the READ_PHONE_STATE permission, or if the calling app is targeting API level 29 or
* higher, then a SecurityException is thrown.</li>
* </ul>
- * *
+ *
* @return The serial number if specified.
*/
@SuppressAutoDoc // No support for device / profile owner.
diff --git a/telephony/java/android/telephony/TelephonyManager.java b/telephony/java/android/telephony/TelephonyManager.java
index fadebaa..09dcc1e 100644
--- a/telephony/java/android/telephony/TelephonyManager.java
+++ b/telephony/java/android/telephony/TelephonyManager.java
@@ -38,6 +38,7 @@
import android.annotation.TestApi;
import android.annotation.WorkerThread;
import android.app.PendingIntent;
+import android.app.role.RoleManager;
import android.compat.Compatibility;
import android.compat.annotation.ChangeId;
import android.compat.annotation.EnabledAfter;
@@ -1885,12 +1886,23 @@
* Returns the unique device ID, for example, the IMEI for GSM and the MEID
* or ESN for CDMA phones. Return null if device ID is not available.
*
- * <p>Requires Permission: READ_PRIVILEGED_PHONE_STATE, for the calling app to be the device or
- * profile owner and have the READ_PHONE_STATE permission, or that the calling app has carrier
- * privileges (see {@link #hasCarrierPrivileges}) on any active subscription. The profile owner
- * is an app that owns a managed profile on the device; for more details see <a
- * href="https://developer.android.com/work/managed-profiles">Work profiles</a>. Profile owner
- * access is deprecated and will be removed in a future release.
+ * <p>Starting with API level 29, persistent device identifiers are guarded behind additional
+ * restrictions, and apps are recommended to use resettable identifiers (see <a
+ * href="c"> Best practices for unique identifiers</a>). This method can be invoked if one of
+ * the following requirements is met:
+ * <ul>
+ * <li>If the calling app has been granted the READ_PRIVILEGED_PHONE_STATE permission; this
+ * is a privileged permission that can only be granted to apps preloaded on the device.
+ * <li>If the calling app is the device or profile owner and has been granted the
+ * {@link Manifest.permission#READ_PHONE_STATE} permission. The profile owner is an app that
+ * owns a managed profile on the device; for more details see <a
+ * href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
+ * Profile owner access is deprecated and will be removed in a future release.
+ * <li>If the calling app has carrier privileges (see {@link #hasCarrierPrivileges}) on any
+ * active subscription.
+ * <li>If the calling app is the default SMS role holder (see {@link
+ * RoleManager#isRoleHeld(String)}).
+ * </ul>
*
* <p>If the calling app does not meet one of these requirements then this method will behave
* as follows:
@@ -1927,12 +1939,23 @@
* Returns the unique device ID of a subscription, for example, the IMEI for
* GSM and the MEID for CDMA phones. Return null if device ID is not available.
*
- * <p>Requires Permission: READ_PRIVILEGED_PHONE_STATE, for the calling app to be the device or
- * profile owner and have the READ_PHONE_STATE permission, or that the calling app has carrier
- * privileges (see {@link #hasCarrierPrivileges}) on any active subscription. The profile owner
- * is an app that owns a managed profile on the device; for more details see <a
- * href="https://developer.android.com/work/managed-profiles">Work profiles</a>. Profile owner
- * access is deprecated and will be removed in a future release.
+ * <p>Starting with API level 29, persistent device identifiers are guarded behind additional
+ * restrictions, and apps are recommended to use resettable identifiers (see <a
+ * href="c"> Best practices for unique identifiers</a>). This method can be invoked if one of
+ * the following requirements is met:
+ * <ul>
+ * <li>If the calling app has been granted the READ_PRIVILEGED_PHONE_STATE permission; this
+ * is a privileged permission that can only be granted to apps preloaded on the device.
+ * <li>If the calling app is the device or profile owner and has been granted the
+ * {@link Manifest.permission#READ_PHONE_STATE} permission. The profile owner is an app that
+ * owns a managed profile on the device; for more details see <a
+ * href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
+ * Profile owner access is deprecated and will be removed in a future release.
+ * <li>If the calling app has carrier privileges (see {@link #hasCarrierPrivileges}) on any
+ * active subscription.
+ * <li>If the calling app is the default SMS role holder (see {@link
+ * RoleManager#isRoleHeld(String)}).
+ * </ul>
*
* <p>If the calling app does not meet one of these requirements then this method will behave
* as follows:
@@ -1985,18 +2008,23 @@
* Returns the IMEI (International Mobile Equipment Identity). Return null if IMEI is not
* available.
*
- * <p>This API requires one of the following:
+ * <p>Starting with API level 29, persistent device identifiers are guarded behind additional
+ * restrictions, and apps are recommended to use resettable identifiers (see <a
+ * href="c"> Best practices for unique identifiers</a>). This method can be invoked if one of
+ * the following requirements is met:
* <ul>
- * <li>The caller holds the READ_PRIVILEGED_PHONE_STATE permission.</li>
- * <li>If the caller is the device or profile owner, the caller holds the
- * {@link Manifest.permission#READ_PHONE_STATE} permission.</li>
- * <li>The caller has carrier privileges (see {@link #hasCarrierPrivileges()} on any
- * active subscription.</li>
- * <li>The caller is the default SMS app for the device.</li>
+ * <li>If the calling app has been granted the READ_PRIVILEGED_PHONE_STATE permission; this
+ * is a privileged permission that can only be granted to apps preloaded on the device.
+ * <li>If the calling app is the device or profile owner and has been granted the
+ * {@link Manifest.permission#READ_PHONE_STATE} permission. The profile owner is an app that
+ * owns a managed profile on the device; for more details see <a
+ * href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
+ * Profile owner access is deprecated and will be removed in a future release.
+ * <li>If the calling app has carrier privileges (see {@link #hasCarrierPrivileges}) on any
+ * active subscription.
+ * <li>If the calling app is the default SMS role holder (see {@link
+ * RoleManager#isRoleHeld(String)}).
* </ul>
- * <p>The profile owner is an app that owns a managed profile on the device; for more details
- * see <a href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
- * Access by profile owners is deprecated and will be removed in a future release.
*
* <p>If the calling app does not meet one of these requirements then this method will behave
* as follows:
@@ -2058,12 +2086,23 @@
/**
* Returns the MEID (Mobile Equipment Identifier). Return null if MEID is not available.
*
- * <p>Requires Permission: READ_PRIVILEGED_PHONE_STATE, for the calling app to be the device or
- * profile owner and have the READ_PHONE_STATE permission, or that the calling app has carrier
- * privileges (see {@link #hasCarrierPrivileges}) on any active subscription. The profile owner
- * is an app that owns a managed profile on the device; for more details see <a
- * href="https://developer.android.com/work/managed-profiles">Work profiles</a>. Profile owner
- * access is deprecated and will be removed in a future release.
+ * <p>Starting with API level 29, persistent device identifiers are guarded behind additional
+ * restrictions, and apps are recommended to use resettable identifiers (see <a
+ * href="c"> Best practices for unique identifiers</a>). This method can be invoked if one of
+ * the following requirements is met:
+ * <ul>
+ * <li>If the calling app has been granted the READ_PRIVILEGED_PHONE_STATE permission; this
+ * is a privileged permission that can only be granted to apps preloaded on the device.
+ * <li>If the calling app is the device or profile owner and has been granted the
+ * {@link Manifest.permission#READ_PHONE_STATE} permission. The profile owner is an app that
+ * owns a managed profile on the device; for more details see <a
+ * href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
+ * Profile owner access is deprecated and will be removed in a future release.
+ * <li>If the calling app has carrier privileges (see {@link #hasCarrierPrivileges}) on any
+ * active subscription.
+ * <li>If the calling app is the default SMS role holder (see {@link
+ * RoleManager#isRoleHeld(String)}).
+ * </ul>
*
* <p>If the calling app does not meet one of these requirements then this method will behave
* as follows:
@@ -2085,12 +2124,23 @@
/**
* Returns the MEID (Mobile Equipment Identifier). Return null if MEID is not available.
*
- * <p>Requires Permission: READ_PRIVILEGED_PHONE_STATE, for the calling app to be the device or
- * profile owner and have the READ_PHONE_STATE permission, or that the calling app has carrier
- * privileges (see {@link #hasCarrierPrivileges}) on any active subscription. The profile owner
- * is an app that owns a managed profile on the device; for more details see <a
- * href="https://developer.android.com/work/managed-profiles">Work profiles</a>. Profile owner
- * access is deprecated and will be removed in a future release.
+ * <p>Starting with API level 29, persistent device identifiers are guarded behind additional
+ * restrictions, and apps are recommended to use resettable identifiers (see <a
+ * href="c"> Best practices for unique identifiers</a>). This method can be invoked if one of
+ * the following requirements is met:
+ * <ul>
+ * <li>If the calling app has been granted the READ_PRIVILEGED_PHONE_STATE permission; this
+ * is a privileged permission that can only be granted to apps preloaded on the device.
+ * <li>If the calling app is the device or profile owner and has been granted the
+ * {@link Manifest.permission#READ_PHONE_STATE} permission. The profile owner is an app that
+ * owns a managed profile on the device; for more details see <a
+ * href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
+ * Profile owner access is deprecated and will be removed in a future release.
+ * <li>If the calling app has carrier privileges (see {@link #hasCarrierPrivileges}) on any
+ * active subscription.
+ * <li>If the calling app is the default SMS role holder (see {@link
+ * RoleManager#isRoleHeld(String)}).
+ * </ul>
*
* <p>If the calling app does not meet one of these requirements then this method will behave
* as follows:
@@ -2158,12 +2208,25 @@
/**
* Returns the Network Access Identifier (NAI). Return null if NAI is not available.
*
- * <p>Requires Permission: READ_PRIVILEGED_PHONE_STATE, for the calling app to be the device or
- * profile owner and have the READ_PHONE_STATE permission, or that the calling app has carrier
- * privileges (see {@link #hasCarrierPrivileges}). The profile owner is an app that owns a
- * managed profile on the device; for more details see <a
- * href="https://developer.android.com/work/managed-profiles">Work profiles</a>. Profile owner
- * access is deprecated and will be removed in a future release.
+ * <p>Starting with API level 29, persistent device identifiers are guarded behind additional
+ * restrictions, and apps are recommended to use resettable identifiers (see <a
+ * href="c"> Best practices for unique identifiers</a>). This method can be invoked if one of
+ * the following requirements is met:
+ * <ul>
+ * <li>If the calling app has been granted the READ_PRIVILEGED_PHONE_STATE permission; this
+ * is a privileged permission that can only be granted to apps preloaded on the device.
+ * <li>If the calling app is the device or profile owner and has been granted the
+ * {@link Manifest.permission#READ_PHONE_STATE} permission. The profile owner is an app that
+ * owns a managed profile on the device; for more details see <a
+ * href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
+ * Profile owner access is deprecated and will be removed in a future release.
+ * <li>If the calling app has carrier privileges (see {@link #hasCarrierPrivileges}).
+ * <li>If the calling app is the default SMS role holder (see {@link
+ * RoleManager#isRoleHeld(String)}).
+ * </ul>
+ *
+ * <p>If the calling app does not meet one of these requirements then this method will behave
+ * as follows:
*
* <ul>
* <li>If the calling app's target SDK is API level 28 or lower and the app has the
@@ -2182,12 +2245,25 @@
/**
* Returns the NAI. Return null if NAI is not available.
*
- * <p>Requires Permission: READ_PRIVILEGED_PHONE_STATE, for the calling app to be the device or
- * profile owner and have the READ_PHONE_STATE permission, or that the calling app has carrier
- * privileges (see {@link #hasCarrierPrivileges}). The profile owner is an app that owns a
- * managed profile on the device; for more details see <a
- * href="https://developer.android.com/work/managed-profiles">Work profiles</a>. Profile owner
- * access is deprecated and will be removed in a future release.
+ * <p>Starting with API level 29, persistent device identifiers are guarded behind additional
+ * restrictions, and apps are recommended to use resettable identifiers (see <a
+ * href="c"> Best practices for unique identifiers</a>). This method can be invoked if one of
+ * the following requirements is met:
+ * <ul>
+ * <li>If the calling app has been granted the READ_PRIVILEGED_PHONE_STATE permission; this
+ * is a privileged permission that can only be granted to apps preloaded on the device.
+ * <li>If the calling app is the device or profile owner and has been granted the
+ * {@link Manifest.permission#READ_PHONE_STATE} permission. The profile owner is an app that
+ * owns a managed profile on the device; for more details see <a
+ * href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
+ * Profile owner access is deprecated and will be removed in a future release.
+ * <li>If the calling app has carrier privileges (see {@link #hasCarrierPrivileges}).
+ * <li>If the calling app is the default SMS role holder (see {@link
+ * RoleManager#isRoleHeld(String)}).
+ * </ul>
+ *
+ * <p>If the calling app does not meet one of these requirements then this method will behave
+ * as follows:
*
* <ul>
* <li>If the calling app's target SDK is API level 28 or lower and the app has the
@@ -3775,12 +3851,22 @@
* Returns the serial number of the SIM, if applicable. Return null if it is
* unavailable.
*
- * <p>Requires Permission: READ_PRIVILEGED_PHONE_STATE, for the calling app to be the device or
- * profile owner and have the READ_PHONE_STATE permission, or that the calling app has carrier
- * privileges (see {@link #hasCarrierPrivileges}). The profile owner is an app that owns a
- * managed profile on the device; for more details see <a
- * href="https://developer.android.com/work/managed-profiles">Work profiles</a>. Profile owner
- * access is deprecated and will be removed in a future release.
+ * <p>Starting with API level 29, persistent device identifiers are guarded behind additional
+ * restrictions, and apps are recommended to use resettable identifiers (see <a
+ * href="c"> Best practices for unique identifiers</a>). This method can be invoked if one of
+ * the following requirements is met:
+ * <ul>
+ * <li>If the calling app has been granted the READ_PRIVILEGED_PHONE_STATE permission; this
+ * is a privileged permission that can only be granted to apps preloaded on the device.
+ * <li>If the calling app is the device or profile owner and has been granted the
+ * {@link Manifest.permission#READ_PHONE_STATE} permission. The profile owner is an app that
+ * owns a managed profile on the device; for more details see <a
+ * href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
+ * Profile owner access is deprecated and will be removed in a future release.
+ * <li>If the calling app has carrier privileges (see {@link #hasCarrierPrivileges}).
+ * <li>If the calling app is the default SMS role holder (see {@link
+ * RoleManager#isRoleHeld(String)}).
+ * </ul>
*
* <p>If the calling app does not meet one of these requirements then this method will behave
* as follows:
@@ -3803,12 +3889,22 @@
* Returns the serial number for the given subscription, if applicable. Return null if it is
* unavailable.
*
- * <p>Requires Permission: READ_PRIVILEGED_PHONE_STATE, for the calling app to be the device or
- * profile owner and have the READ_PHONE_STATE permission, or that the calling app has carrier
- * privileges (see {@link #hasCarrierPrivileges}). The profile owner is an app that owns a
- * managed profile on the device; for more details see <a
- * href="https://developer.android.com/work/managed-profiles">Work profiles</a>. Profile owner
- * access is deprecated and will be removed in a future release.
+ * <p>Starting with API level 29, persistent device identifiers are guarded behind additional
+ * restrictions, and apps are recommended to use resettable identifiers (see <a
+ * href="c"> Best practices for unique identifiers</a>). This method can be invoked if one of
+ * the following requirements is met:
+ * <ul>
+ * <li>If the calling app has been granted the READ_PRIVILEGED_PHONE_STATE permission; this
+ * is a privileged permission that can only be granted to apps preloaded on the device.
+ * <li>If the calling app is the device or profile owner and has been granted the
+ * {@link Manifest.permission#READ_PHONE_STATE} permission. The profile owner is an app that
+ * owns a managed profile on the device; for more details see <a
+ * href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
+ * Profile owner access is deprecated and will be removed in a future release.
+ * <li>If the calling app has carrier privileges (see {@link #hasCarrierPrivileges}).
+ * <li>If the calling app is the default SMS role holder (see {@link
+ * RoleManager#isRoleHeld(String)}).
+ * </ul>
*
* <p>If the calling app does not meet one of these requirements then this method will behave
* as follows:
@@ -4047,12 +4143,22 @@
* Returns the unique subscriber ID, for example, the IMSI for a GSM phone.
* Return null if it is unavailable.
*
- * <p>Requires Permission: READ_PRIVILEGED_PHONE_STATE, for the calling app to be the device or
- * profile owner and have the READ_PHONE_STATE permission, or that the calling app has carrier
- * privileges (see {@link #hasCarrierPrivileges}). The profile owner is an app that owns a
- * managed profile on the device; for more details see <a
- * href="https://developer.android.com/work/managed-profiles">Work profiles</a>. Profile owner
- * access is deprecated and will be removed in a future release.
+ * <p>Starting with API level 29, persistent device identifiers are guarded behind additional
+ * restrictions, and apps are recommended to use resettable identifiers (see <a
+ * href="c"> Best practices for unique identifiers</a>). This method can be invoked if one of
+ * the following requirements is met:
+ * <ul>
+ * <li>If the calling app has been granted the READ_PRIVILEGED_PHONE_STATE permission; this
+ * is a privileged permission that can only be granted to apps preloaded on the device.
+ * <li>If the calling app is the device or profile owner and has been granted the
+ * {@link Manifest.permission#READ_PHONE_STATE} permission. The profile owner is an app that
+ * owns a managed profile on the device; for more details see <a
+ * href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
+ * Profile owner access is deprecated and will be removed in a future release.
+ * <li>If the calling app has carrier privileges (see {@link #hasCarrierPrivileges}).
+ * <li>If the calling app is the default SMS role holder (see {@link
+ * RoleManager#isRoleHeld(String)}).
+ * </ul>
*
* <p>If the calling app does not meet one of these requirements then this method will behave
* as follows:
@@ -4076,12 +4182,22 @@
* for a subscription.
* Return null if it is unavailable.
*
- * <p>Requires Permission: READ_PRIVILEGED_PHONE_STATE, for the calling app to be the device or
- * profile owner and have the READ_PHONE_STATE permission, or that the calling app has carrier
- * privileges (see {@link #hasCarrierPrivileges}). The profile owner is an app that owns a
- * managed profile on the device; for more details see <a
- * href="https://developer.android.com/work/managed-profiles">Work profiles</a>. Profile owner
- * access is deprecated and will be removed in a future release.
+ * <p>Starting with API level 29, persistent device identifiers are guarded behind additional
+ * restrictions, and apps are recommended to use resettable identifiers (see <a
+ * href="c"> Best practices for unique identifiers</a>). This method can be invoked if one of
+ * the following requirements is met:
+ * <ul>
+ * <li>If the calling app has been granted the READ_PRIVILEGED_PHONE_STATE permission; this
+ * is a privileged permission that can only be granted to apps preloaded on the device.
+ * <li>If the calling app is the device or profile owner and has been granted the
+ * {@link Manifest.permission#READ_PHONE_STATE} permission. The profile owner is an app that
+ * owns a managed profile on the device; for more details see <a
+ * href="https://developer.android.com/work/managed-profiles">Work profiles</a>.
+ * Profile owner access is deprecated and will be removed in a future release.
+ * <li>If the calling app has carrier privileges (see {@link #hasCarrierPrivileges}).
+ * <li>If the calling app is the default SMS role holder (see {@link
+ * RoleManager#isRoleHeld(String)}).
+ * </ul>
*
* <p>If the calling app does not meet one of these requirements then this method will behave
* as follows: