[Telephony] Add description about location permission

- Hold ACCESS_FINE_LOCATION: full service state - Hold ACCESS_COARSE_LOCATION: set cellIdentity is null - No local permission: set cellIdentity, mOperatorAlphaLong, mOperatorAlphaShort and mOperatorNumeric are null Bug: 165014401 Test: make Change-Id: I9ada08a530d9b8bc8483edfad783ff3b7434faa3
2021-05-27 20:16:35 +08:00
parent a38c45adde
commit 6d33beea88
4 changed files with 63 additions and 2 deletions
--- a/core/java/android/telephony/PhoneStateListener.java
+++ b/core/java/android/telephony/PhoneStateListener.java
@@ -621,7 +621,11 @@ public class PhoneStateListener {
     * The instance of {@link ServiceState} passed as an argument here will have various levels of
     * location information stripped from it depending on the location permissions that your app
     * holds. Only apps holding the {@link Manifest.permission#ACCESS_FINE_LOCATION} permission will
-     * receive all the information in {@link ServiceState}.
+     * receive all the information in {@link ServiceState}, otherwise the cellIdentity will be null
+     * if apps only holding the {@link Manifest.permission#ACCESS_COARSE_LOCATION} permission.
+     * Network operator name in long/short alphanumeric format and numeric id will be null if apps
+     * holding neither {@link android.Manifest.permission#ACCESS_FINE_LOCATION} nor
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}.
     *
     * @see ServiceState#STATE_EMERGENCY_ONLY
     * @see ServiceState#STATE_IN_SERVICE
--- a/core/java/android/telephony/TelephonyCallback.java
+++ b/core/java/android/telephony/TelephonyCallback.java
@@ -663,7 +663,12 @@ public class TelephonyCallback {
         * levels of location information stripped from it depending on the location permissions
         * that your app holds.
         * Only apps holding the {@link Manifest.permission#ACCESS_FINE_LOCATION} permission will
-         * receive all the information in {@link ServiceState}.
+         * receive all the information in {@link ServiceState}, otherwise the cellIdentity
+         * will be null if apps only holding the {@link Manifest.permission#ACCESS_COARSE_LOCATION}
+         * permission.
+         * Network operator name in long/short alphanumeric format and numeric id will be null if
+         * apps holding neither {@link android.Manifest.permission#ACCESS_FINE_LOCATION} nor
+         * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}.
         *
         * @see ServiceState#STATE_EMERGENCY_ONLY
         * @see ServiceState#STATE_IN_SERVICE
--- a/telephony/java/android/telephony/NetworkRegistrationInfo.java
+++ b/telephony/java/android/telephony/NetworkRegistrationInfo.java
@@ -506,6 +506,8 @@ public final class NetworkRegistrationInfo implements Parcelable {
    }

    /**
+     * Require {@link android.Manifest.permission#ACCESS_FINE_LOCATION}, otherwise return null.
+     *
     * @return The cell information.
     */
    @Nullable
--- a/telephony/java/android/telephony/ServiceState.java
+++ b/telephony/java/android/telephony/ServiceState.java
@@ -758,6 +758,11 @@ public class ServiceState implements Parcelable {
     * In GSM/UMTS, long format can be up to 16 characters long.
     * In CDMA, returns the ERI text, if set. Otherwise, returns the ONS.
     *
+     * Require at least {@link android.Manifest.permission#ACCESS_FINE_LOCATION} or
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}. Otherwise return null if the
+     * caller does not hold neither {@link android.Manifest.permission#ACCESS_FINE_LOCATION} nor
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}.
+     *
     * @return long name of operator, null if unregistered or unknown
     */
    public String getOperatorAlphaLong() {
@@ -766,6 +771,12 @@ public class ServiceState implements Parcelable {

    /**
     * Get current registered voice network operator name in long alphanumeric format.
+     *
+     * Require at least {@link android.Manifest.permission#ACCESS_FINE_LOCATION} or
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}. Otherwise return null if the
+     * caller does not hold neither {@link android.Manifest.permission#ACCESS_FINE_LOCATION} nor
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}.
+     *
     * @return long name of operator
     * @hide
     */
@@ -780,6 +791,11 @@ public class ServiceState implements Parcelable {
     *
     * In GSM/UMTS, short format can be up to 8 characters long.
     *
+     * Require at least {@link android.Manifest.permission#ACCESS_FINE_LOCATION} or
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}. Otherwise return null if the
+     * caller does not hold neither {@link android.Manifest.permission#ACCESS_FINE_LOCATION} nor
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}.
+     *
     * @return short name of operator, null if unregistered or unknown
     */
    public String getOperatorAlphaShort() {
@@ -788,6 +804,12 @@ public class ServiceState implements Parcelable {

    /**
     * Get current registered voice network operator name in short alphanumeric format.
+     *
+     * Require at least {@link android.Manifest.permission#ACCESS_FINE_LOCATION} or
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}. Otherwise return null if the
+     * caller does not have neither {@link android.Manifest.permission#ACCESS_FINE_LOCATION} nor
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}.
+     *
     * @return short name of operator, null if unregistered or unknown
     * @hide
     */
@@ -799,6 +821,12 @@ public class ServiceState implements Parcelable {

    /**
     * Get current registered data network operator name in short alphanumeric format.
+     *
+     * Require at least {@link android.Manifest.permission#ACCESS_FINE_LOCATION} or
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}. Otherwise return null if the
+     * caller does not have neither {@link android.Manifest.permission#ACCESS_FINE_LOCATION} nor
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}.
+     *
     * @return short name of operator, null if unregistered or unknown
     * @hide
     */
@@ -812,6 +840,11 @@ public class ServiceState implements Parcelable {
     * Get current registered operator name in long alphanumeric format if
     * available or short otherwise.
     *
+     * Require at least {@link android.Manifest.permission#ACCESS_FINE_LOCATION} or
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}. Otherwise return null if the
+     * caller does not hold neither {@link android.Manifest.permission#ACCESS_FINE_LOCATION} nor
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}.
+     *
     * @see #getOperatorAlphaLong
     * @see #getOperatorAlphaShort
     *
@@ -832,6 +865,11 @@ public class ServiceState implements Parcelable {
     * In GSM/UMTS, numeric format is 3 digit country code plus 2 or 3 digit
     * network code.
     *
+     * Require at least {@link android.Manifest.permission#ACCESS_FINE_LOCATION} or
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}. Otherwise return null if the
+     * caller does not hold neither {@link android.Manifest.permission#ACCESS_FINE_LOCATION} nor
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}.
+     *
     * @return numeric format of operator, null if unregistered or unknown
     */
    /*
@@ -844,6 +882,12 @@ public class ServiceState implements Parcelable {

    /**
     * Get current registered voice network operator numeric id.
+     *
+     * Require at least {@link android.Manifest.permission#ACCESS_FINE_LOCATION} or
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}. Otherwise return null if the
+     * caller does not hold neither {@link android.Manifest.permission#ACCESS_FINE_LOCATION} nor
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}.
+     *
     * @return numeric format of operator, null if unregistered or unknown
     * @hide
     */
@@ -854,6 +898,12 @@ public class ServiceState implements Parcelable {

    /**
     * Get current registered data network operator numeric id.
+     *
+     * Require at least {@link android.Manifest.permission#ACCESS_FINE_LOCATION} or
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}. Otherwise return null if the
+     * caller does not hold neither {@link android.Manifest.permission#ACCESS_FINE_LOCATION} nor
+     * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION}.
+     *
     * @return numeric format of operator, null if unregistered or unknown
     * @hide
     */