Introduce satellite state change listener APIs
This change introduces the public APIs in SatelliteManager to monitor and query satellite state change.
The first supported case is the satellite modem enabled state change.
Apps with READ_BASIC_PHONE_STATE permission can query the current
satellite modem enabled state on registration and keeps notified on
enabled state change, until unregistration.
Bug: 357638490
Test: atest FrameworksTelephonyTest SatelliteManagerTest
Flag: com.android.internal.telephony.flags.satellite_state_change_listener
Change-Id: I80e04b937f1193a5dbc0cf4c7f7387f582a2e97a
diff --git a/core/api/current.txt b/core/api/current.txt
index 053ba18..a76c685 100644
--- a/core/api/current.txt
+++ b/core/api/current.txt
@@ -47772,6 +47772,12 @@
package android.telephony.satellite {
@FlaggedApi("com.android.internal.telephony.flags.satellite_state_change_listener") public final class SatelliteManager {
+ method @FlaggedApi("com.android.internal.telephony.flags.satellite_state_change_listener") @RequiresPermission(anyOf={android.Manifest.permission.READ_BASIC_PHONE_STATE, "android.permission.READ_PRIVILEGED_PHONE_STATE", android.Manifest.permission.READ_PHONE_STATE, "carrier privileges"}) public void registerStateChangeListener(@NonNull java.util.concurrent.Executor, @NonNull android.telephony.satellite.SatelliteStateChangeListener);
+ method @FlaggedApi("com.android.internal.telephony.flags.satellite_state_change_listener") @RequiresPermission(anyOf={android.Manifest.permission.READ_BASIC_PHONE_STATE, "android.permission.READ_PRIVILEGED_PHONE_STATE", android.Manifest.permission.READ_PHONE_STATE, "carrier privileges"}) public void unregisterStateChangeListener(@NonNull android.telephony.satellite.SatelliteStateChangeListener);
+ }
+
+ @FlaggedApi("com.android.internal.telephony.flags.satellite_state_change_listener") public interface SatelliteStateChangeListener {
+ method public void onEnabledStateChanged(boolean);
}
}
diff --git a/telephony/java/android/telephony/satellite/SatelliteManager.java b/telephony/java/android/telephony/satellite/SatelliteManager.java
index 915ad2c..be02232 100644
--- a/telephony/java/android/telephony/satellite/SatelliteManager.java
+++ b/telephony/java/android/telephony/satellite/SatelliteManager.java
@@ -40,6 +40,7 @@
import android.telephony.TelephonyCallback;
import android.telephony.TelephonyFrameworkInitializer;
import android.telephony.TelephonyManager;
+import android.telephony.TelephonyRegistryManager;
import com.android.internal.telephony.IIntegerConsumer;
import com.android.internal.telephony.ITelephony;
@@ -110,6 +111,8 @@
*/
@Nullable private final Context mContext;
+ private TelephonyRegistryManager mTelephonyRegistryMgr;
+
/**
* Create an instance of the SatelliteManager.
*
@@ -743,6 +746,65 @@
"android.telephony.METADATA_SATELLITE_MANUAL_CONNECT_P2P_SUPPORT";
/**
+ * Registers a {@link SatelliteStateChangeListener} to receive callbacks when the satellite
+ * state may have changed.
+ *
+ * <p>The callback method is immediately triggered with latest state on invoking this method if
+ * the state change has been notified before.
+ *
+ * @param executor The {@link Executor} where the {@code listener} will be invoked
+ * @param listener The listener to monitor the satellite state change
+ *
+ * @see SatelliteStateChangeListener
+ * @see TelephonyManager#hasCarrierPrivileges()
+ */
+ @FlaggedApi(Flags.FLAG_SATELLITE_STATE_CHANGE_LISTENER)
+ @RequiresPermission(anyOf = {android.Manifest.permission.READ_BASIC_PHONE_STATE,
+ android.Manifest.permission.READ_PRIVILEGED_PHONE_STATE,
+ android.Manifest.permission.READ_PHONE_STATE,
+ "carrier privileges"})
+ public void registerStateChangeListener(@NonNull @CallbackExecutor Executor executor,
+ @NonNull SatelliteStateChangeListener listener) {
+ if (mContext == null) {
+ throw new IllegalStateException("Telephony service is null");
+ }
+
+ mTelephonyRegistryMgr = mContext.getSystemService(TelephonyRegistryManager.class);
+ if (mTelephonyRegistryMgr == null) {
+ throw new IllegalStateException("Telephony registry service is null");
+ }
+ mTelephonyRegistryMgr.addSatelliteStateChangeListener(executor, listener);
+ }
+
+ /**
+ * Unregisters the {@link SatelliteStateChangeListener} previously registered with
+ * {@link #registerStateChangeListener(Executor, SatelliteStateChangeListener)}.
+ *
+ * <p>It will be a no-op if the {@code listener} is not currently registered.
+ *
+ * @param listener The listener to unregister
+ *
+ * @see SatelliteStateChangeListener
+ * @see TelephonyManager#hasCarrierPrivileges()
+ */
+ @FlaggedApi(Flags.FLAG_SATELLITE_STATE_CHANGE_LISTENER)
+ @RequiresPermission(anyOf = {android.Manifest.permission.READ_BASIC_PHONE_STATE,
+ android.Manifest.permission.READ_PRIVILEGED_PHONE_STATE,
+ android.Manifest.permission.READ_PHONE_STATE,
+ "carrier privileges"})
+ public void unregisterStateChangeListener(@NonNull SatelliteStateChangeListener listener) {
+ if (mContext == null) {
+ throw new IllegalStateException("Telephony service is null");
+ }
+
+ mTelephonyRegistryMgr = mContext.getSystemService(TelephonyRegistryManager.class);
+ if (mTelephonyRegistryMgr == null) {
+ throw new IllegalStateException("Telephony registry service is null");
+ }
+ mTelephonyRegistryMgr.removeSatelliteStateChangeListener(listener);
+ }
+
+ /**
* Request to enable or disable the satellite modem and demo mode.
* If satellite modem and cellular modem cannot work concurrently,
* then this will disable the cellular modem if satellite modem is enabled,
diff --git a/telephony/java/android/telephony/satellite/SatelliteStateChangeListener.java b/telephony/java/android/telephony/satellite/SatelliteStateChangeListener.java
new file mode 100644
index 0000000..3aa910d
--- /dev/null
+++ b/telephony/java/android/telephony/satellite/SatelliteStateChangeListener.java
@@ -0,0 +1,51 @@
+/*
+ * Copyright (C) 2024 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.satellite;
+
+import android.annotation.FlaggedApi;
+
+import com.android.internal.telephony.flags.Flags;
+
+import java.util.concurrent.Executor;
+
+/**
+ * A listener interface to monitor satellite state change events.
+ *
+ * <p>Call
+ * {@link SatelliteManager#registerStateChangeListener(Executor, SatelliteStateChangeListener)}
+ * to monitor. Call
+ * {@link SatelliteManager#unregisterStateChangeListener(SatelliteStateChangeListener)} to cancel.
+ *
+ * @see SatelliteManager#registerStateChangeListener(Executor, SatelliteStateChangeListener)
+ * @see SatelliteManager#unregisterStateChangeListener(SatelliteStateChangeListener)
+ */
+@FlaggedApi(Flags.FLAG_SATELLITE_STATE_CHANGE_LISTENER)
+public interface SatelliteStateChangeListener {
+ /**
+ * Called when satellite modem enabled state may have changed.
+ *
+ * <p>Note:there is no guarantee that this callback will only be invoked upon a change of state.
+ * In other word, in some cases, the callback may report with the same enabled states. It is the
+ * caller's responsibility to filter uninterested states.
+ *
+ * <p>Note:satellite enabled state is a device state that is NOT associated with subscription or
+ * SIM slot.
+ *
+ * @param isEnabled {@code true} means satellite modem is enabled.
+ */
+ void onEnabledStateChanged(boolean isEnabled);
+}