Merge "Introduce SignalStrengthUpdateRequest to customize signal update request" am: 775a1db2c2 am: b581010b53

Original change: https://android-review.googlesource.com/c/platform/frameworks/base/+/1532958

MUST ONLY BE SUBMITTED BY AUTOMERGER

Change-Id: I32e98901cc44b5bda2b369020ca1381a1e0b5d2a

core/api/current.txt

@@ -40796,8 +40796,25 @@ package android.telephony {
     field public static final int INVALID = 2147483647; // 0x7fffffff
   }
 
+  public final class SignalStrengthUpdateRequest implements android.os.Parcelable {
+    method public int describeContents();
+    method @NonNull public java.util.Collection<android.telephony.SignalThresholdInfo> getSignalThresholdInfos();
+    method public boolean isReportingRequestedWhileIdle();
+    method public void writeToParcel(@NonNull android.os.Parcel, int);
+    field @NonNull public static final android.os.Parcelable.Creator<android.telephony.SignalStrengthUpdateRequest> CREATOR;
+  }
+
+  public static final class SignalStrengthUpdateRequest.Builder {
+    ctor public SignalStrengthUpdateRequest.Builder();
+    method @NonNull public android.telephony.SignalStrengthUpdateRequest build();
+    method @NonNull public android.telephony.SignalStrengthUpdateRequest.Builder setReportingRequestedWhileIdle(boolean);
+    method @NonNull public android.telephony.SignalStrengthUpdateRequest.Builder setSignalThresholdInfos(@NonNull java.util.Collection<android.telephony.SignalThresholdInfo>);
+  }
+
   public final class SignalThresholdInfo implements android.os.Parcelable {
     method public int describeContents();
+    method public static int getMaximumNumberOfThresholdsAllowed();
+    method public static int getMinimumNumberOfThresholdsAllowed();
     method public int getRadioAccessNetworkType();
     method public int getSignalMeasurementType();
     method @NonNull public int[] getThresholds();

telephony/java/android/telephony/SignalStrengthUpdateRequest.java

@@ -0,0 +1,251 @@
+/*
+ * Copyright (C) 2020 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.telephony;
+
+import android.annotation.NonNull;
+import android.os.Parcel;
+import android.os.Parcelable;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
+
+/**
+ * Request used to register {@link SignalThresholdInfo} to be notified when the signal strength
+ * breach the specified thresholds.
+ */
+public final class SignalStrengthUpdateRequest implements Parcelable {
+    /**
+     * List of SignalThresholdInfo for the request.
+     */
+    private final List<SignalThresholdInfo> mSignalThresholdInfos;
+
+    /**
+     * Whether the reporting is required for thresholds in the request while device is idle.
+     */
+    private final boolean mIsReportingRequestedWhileIdle;
+
+    /**
+     * Whether the reporting requested for system thresholds while device is idle.
+     *
+     * System signal thresholds are loaded from carrier config items and mainly used for UI
+     * displaying. By default, they are ignored when device is idle. When setting the value to true,
+     * modem will continue reporting signal strength changes over the system signal thresholds even
+     * device is idle.
+     *
+     * This should only set to true by the system caller.
+     */
+    private final boolean mIsSystemThresholdReportingRequestedWhileIdle;
+
+    private SignalStrengthUpdateRequest(
+            @NonNull List<SignalThresholdInfo> signalThresholdInfos,
+            boolean isReportingRequestedWhileIdle,
+            boolean isSystemThresholdReportingRequestedWhileIdle) {
+        validate(signalThresholdInfos);
+
+        mSignalThresholdInfos = signalThresholdInfos;
+        mIsReportingRequestedWhileIdle = isReportingRequestedWhileIdle;
+        mIsSystemThresholdReportingRequestedWhileIdle =
+                isSystemThresholdReportingRequestedWhileIdle;
+    }
+
+    /**
+     * Builder class to create {@link SignalStrengthUpdateRequest} object.
+     */
+    public static final class Builder {
+        private List<SignalThresholdInfo> mSignalThresholdInfos = null;
+        private boolean mIsReportingRequestedWhileIdle = false;
+        private boolean mIsSystemThresholdReportingRequestedWhileIdle = false;
+
+        /**
+         * Set the collection of SignalThresholdInfo for the builder object
+         *
+         * @param signalThresholdInfos the collection of SignalThresholdInfo
+         *
+         * @return the builder to facilitate the chaining
+         */
+        public @NonNull Builder setSignalThresholdInfos(
+                @NonNull Collection<SignalThresholdInfo> signalThresholdInfos) {
+            Objects.requireNonNull(signalThresholdInfos,
+                    "SignalThresholdInfo collection must not be null");
+            for (SignalThresholdInfo info : signalThresholdInfos) {
+                Objects.requireNonNull(info,
+                        "SignalThresholdInfo in the collection must not be null");
+            }
+
+            mSignalThresholdInfos = new ArrayList<>(signalThresholdInfos);
+            // Sort the collection with RAN ascending order, make the ordering not matter for equals
+            mSignalThresholdInfos.sort(
+                    Comparator.comparingInt(SignalThresholdInfo::getRadioAccessNetworkType));
+            return this;
+        }
+
+        /**
+         * Set the builder object if require reporting on thresholds in this request when device is
+         * idle.
+         *
+         * @param isReportingRequestedWhileIdle true if request reporting when device is idle
+         *
+         * @return the builder to facilitate the chaining
+         */
+        public @NonNull Builder setReportingRequestedWhileIdle(
+                boolean isReportingRequestedWhileIdle) {
+            mIsReportingRequestedWhileIdle = isReportingRequestedWhileIdle;
+            return this;
+        }
+
+        /**
+         * Set the builder object if require reporting on the system thresholds when device is idle.
+         *
+         * This can only used by the system caller.
+         *
+         * @param isSystemThresholdReportingRequestedWhileIdle true if request reporting on the
+         *                                                     system thresholds when device is idle
+         * @return the builder to facilitate the chaining
+         * @hide
+         */
+        public @NonNull Builder setSystemThresholdReportingRequestedWhileIdle(
+                boolean isSystemThresholdReportingRequestedWhileIdle) {
+            mIsSystemThresholdReportingRequestedWhileIdle =
+                    isSystemThresholdReportingRequestedWhileIdle;
+            return this;
+        }
+
+        /**
+         * Build a {@link SignalStrengthUpdateRequest} object.
+         *
+         * @return the SignalStrengthUpdateRequest object
+         *
+         * @throws IllegalArgumentException if the SignalThresholdInfo collection is empty size, the
+         * radio access network type in the collection is not unique
+         */
+        public @NonNull SignalStrengthUpdateRequest build() {
+            return new SignalStrengthUpdateRequest(mSignalThresholdInfos,
+                    mIsReportingRequestedWhileIdle, mIsSystemThresholdReportingRequestedWhileIdle);
+        }
+    }
+
+    private SignalStrengthUpdateRequest(Parcel in) {
+        mSignalThresholdInfos = in.createTypedArrayList(SignalThresholdInfo.CREATOR);
+        mIsReportingRequestedWhileIdle = in.readBoolean();
+        mIsSystemThresholdReportingRequestedWhileIdle = in.readBoolean();
+    }
+
+    /**
+     * Get the collection of SignalThresholdInfo in the request.
+     *
+     * @return the collection of SignalThresholdInfo
+     */
+    @NonNull
+    public Collection<SignalThresholdInfo> getSignalThresholdInfos() {
+        return Collections.unmodifiableList(mSignalThresholdInfos);
+    }
+
+    /**
+     * Get whether reporting is requested for the threshold in the request while device is idle.
+     *
+     * @return true if reporting requested while device is idle
+     */
+    public boolean isReportingRequestedWhileIdle() {
+        return mIsReportingRequestedWhileIdle;
+    }
+
+    /**
+     * @return true if reporting requested for system thresholds while device is idle
+     *
+     * @hide
+     */
+    public boolean isSystemThresholdReportingRequestedWhileIdle() {
+        return mIsSystemThresholdReportingRequestedWhileIdle;
+    }
+
+    @Override
+    public int describeContents() {
+        return 0;
+    }
+
+    @Override
+    public void writeToParcel(@NonNull Parcel dest, int flags) {
+        dest.writeTypedList(mSignalThresholdInfos);
+        dest.writeBoolean(mIsReportingRequestedWhileIdle);
+        dest.writeBoolean(mIsSystemThresholdReportingRequestedWhileIdle);
+    }
+
+    @Override
+    public boolean equals(Object other) {
+        if (this == other) return true;
+
+        if (!(other instanceof SignalStrengthUpdateRequest)) {
+            return false;
+        }
+
+        SignalStrengthUpdateRequest request = (SignalStrengthUpdateRequest) other;
+        return request.mSignalThresholdInfos.equals(mSignalThresholdInfos)
+                && request.mIsReportingRequestedWhileIdle == mIsReportingRequestedWhileIdle
+                && request.mIsSystemThresholdReportingRequestedWhileIdle
+                == mIsSystemThresholdReportingRequestedWhileIdle;
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(mSignalThresholdInfos, mIsReportingRequestedWhileIdle,
+                mIsSystemThresholdReportingRequestedWhileIdle);
+    }
+
+    public static final @NonNull Parcelable.Creator<SignalStrengthUpdateRequest> CREATOR =
+            new Parcelable.Creator<SignalStrengthUpdateRequest>() {
+                @Override
+                public SignalStrengthUpdateRequest createFromParcel(Parcel source) {
+                    return new SignalStrengthUpdateRequest(source);
+                }
+
+                @Override
+                public SignalStrengthUpdateRequest[] newArray(int size) {
+                    return new SignalStrengthUpdateRequest[size];
+                }
+            };
+
+    @Override
+    public String toString() {
+        return new StringBuilder("SignalStrengthUpdateRequest{")
+                .append("mSignalThresholdInfos=")
+                .append(mSignalThresholdInfos)
+                .append(" mIsReportingRequestedWhileIdle=")
+                .append(mIsReportingRequestedWhileIdle)
+                .append(" mIsSystemThresholdReportingRequestedWhileIdle=")
+                .append(mIsSystemThresholdReportingRequestedWhileIdle)
+                .append("}").toString();
+    }
+
+    /**
+     * Throw IAE when the RAN in the collection is not unique.
+     */
+    private static void validate(Collection<SignalThresholdInfo> infos) {
+        Set<Integer> uniqueRan = new HashSet<>(infos.size());
+        for (SignalThresholdInfo info : infos) {
+            final int ran = info.getRadioAccessNetworkType();
+            if (!uniqueRan.add(ran)) {
+                throw new IllegalArgumentException("RAN: " + ran + " is not unique");
+            }
+        }
+    }
+}

telephony/java/android/telephony/SignalThresholdInfo.java

@@ -279,6 +279,20 @@ public final class SignalThresholdInfo implements Parcelable {
      */
     public static final int SIGNAL_SSSINR_MAX_VALUE = 40;
 
+    /**
+     * The minimum number of thresholds allowed in each SignalThresholdInfo.
+     *
+     * @hide
+     */
+    public static final int MINIMUM_NUMBER_OF_THRESHOLDS_ALLOWED = 1;
+
+    /**
+     * The maximum number of thresholds allowed in each SignalThresholdInfo.
+     *
+     * @hide
+     */
+    public static final int MAXIMUM_NUMBER_OF_THRESHOLDS_ALLOWED = 4;
+
     /**
      * Constructor
      *
@@ -368,7 +382,11 @@ public final class SignalThresholdInfo implements Parcelable {
         /**
          * Set the signal strength thresholds of the corresponding signal measurement type.
          *
-         * The range and unit must reference specific SignalMeasurementType.
+         * The range and unit must reference specific SignalMeasurementType. The length of the
+         * thresholds should between the numbers return from
+         * {@link #getMinimumNumberOfThresholdsAllowed()} and
+         * {@link #getMaximumNumberOfThresholdsAllowed()}. An IllegalArgumentException will throw
+         * otherwise.
          *
          * @param thresholds array of integer as the signal threshold values
          * @return the builder to facilitate the chaining
@@ -385,11 +403,34 @@ public final class SignalThresholdInfo implements Parcelable {
          */
         public @NonNull Builder setThresholds(@NonNull int[] thresholds) {
             Objects.requireNonNull(thresholds, "thresholds must not be null");
+            if (thresholds.length < MINIMUM_NUMBER_OF_THRESHOLDS_ALLOWED
+                    || thresholds.length > MAXIMUM_NUMBER_OF_THRESHOLDS_ALLOWED) {
+                throw new IllegalArgumentException(
+                        "thresholds length must between " + MINIMUM_NUMBER_OF_THRESHOLDS_ALLOWED
+                                + " and " + MAXIMUM_NUMBER_OF_THRESHOLDS_ALLOWED);
+            }
             mThresholds = thresholds.clone();
             Arrays.sort(mThresholds);
             return this;
         }
 
+        /**
+         * Set the signal strength thresholds for the corresponding signal measurement type without
+         * the length limitation.
+         *
+         * @param thresholds array of integer as the signal threshold values
+         * @return the builder to facilitate the chaining
+         *
+         * @hide
+         */
+        public @NonNull Builder setThresholdsUnlimited(@NonNull int[] thresholds) {
+            Objects.requireNonNull(thresholds, "thresholds must not be null");
+            mThresholds = thresholds.clone();
+            Arrays.sort(mThresholds);
+            return this;
+        }
+
+
         /**
          * Set if the modem should trigger the report based on the criteria.
          *
@@ -474,6 +515,24 @@ public final class SignalThresholdInfo implements Parcelable {
         return mThresholds.clone();
     }
 
+    /**
+     * Get the minimum number of thresholds allowed in each SignalThresholdInfo.
+     *
+     * @return the minimum number of thresholds allowed
+     */
+    public static int getMinimumNumberOfThresholdsAllowed() {
+        return MINIMUM_NUMBER_OF_THRESHOLDS_ALLOWED;
+    }
+
+    /**
+     * Get the maximum number of threshold allowed in each SignalThresholdInfo.
+     *
+     * @return the maximum number of thresholds allowed
+     */
+    public static int getMaximumNumberOfThresholdsAllowed() {
+        return MAXIMUM_NUMBER_OF_THRESHOLDS_ALLOWED;
+    }
+
     @Override
     public int describeContents() {
         return 0;