TelephonyManager Carrier Network Change Notification

Adds a way for a carrier app to notify the system that an intended network
change is starting or ending. This can be used by a system PhoneStateListener
to provide custom UI or perform other actions during this period.

- Adds new public TelephonyManager API: notifyCarrierNetworkChange(boolean)
- Adds new @hide PhoneStateListener method: onCarrierNetworkChange(boolean)
- Functionality merely serves as a pass-through of data from an app to a
  PhoneStateListener (SystemUI for the intended use case)
- Protected by MODIFY_PHONE_STATE permission or hasCarrierPrivileges().

Bug: 11392659

Change-Id: I3199e21ec1ac124198f44b86c1534dd3ff1f6858

2 files changed, 61 insertions, 0 deletions

diff --git a/telephony/java/android/telephony/PhoneStateListener.java b/telephony/java/android/telephony/PhoneStateListener.java
index 611dd7bd..d192288 100644
--- a/telephony/java/android/telephony/PhoneStateListener.java
+++ b/telephony/java/android/telephony/PhoneStateListener.java
@@ -219,6 +219,15 @@ public class PhoneStateListener {
      */
     public static final int LISTEN_OEM_HOOK_RAW_EVENT                       = 0x00008000;
 
+    /**
+     * Listen for carrier network changes indicated by a carrier app.
+     *
+     * @see #onCarrierNetworkRequest
+     * @see TelephonyManager#notifyCarrierNetworkChange(boolean)
+     * @hide
+     */
+    public static final int LISTEN_CARRIER_NETWORK_CHANGE                   = 0x00010000;
+
      /*
      * Subscription used to listen to the phone state changes
      * @hide
@@ -321,6 +330,9 @@ public class PhoneStateListener {
                     case LISTEN_OEM_HOOK_RAW_EVENT:
                         PhoneStateListener.this.onOemHookRawEvent((byte[])msg.obj);
                         break;
+                    case LISTEN_CARRIER_NETWORK_CHANGE:
+                        PhoneStateListener.this.onCarrierNetworkChange((boolean)msg.obj);
+                        break;
 
                 }
             }
@@ -500,6 +512,22 @@ public class PhoneStateListener {
     }
 
     /**
+     * Callback invoked when telephony has received notice from a carrier
+     * app that a network action that could result in connectivity loss
+     * has been requested by an app using
+     * {@link android.telephony.TelephonyManager#notifyCarrierNetworkChange(boolean)}
+     *
+     * @param active Whether the carrier network change is or shortly
+     *               will be active. This value is true to indicate
+     *               showing alternative UI and false to stop.
+     *
+     * @hide
+     */
+    public void onCarrierNetworkChange(boolean active) {
+        // default implementation empty
+    }
+
+    /**
      * The callback methods need to be called on the handler thread where
      * this object was created.  If the binder did that for us it'd be nice.
      */
@@ -575,6 +603,10 @@ public class PhoneStateListener {
         public void onOemHookRawEvent(byte[] rawData) {
             Message.obtain(mHandler, LISTEN_OEM_HOOK_RAW_EVENT, 0, 0, rawData).sendToTarget();
         }
+
+        public void onCarrierNetworkChange(boolean active) {
+            Message.obtain(mHandler, LISTEN_CARRIER_NETWORK_CHANGE, 0, 0, active).sendToTarget();
+        }
     };
 
     private void log(String s) {
diff --git a/telephony/java/android/telephony/TelephonyManager.java b/telephony/java/android/telephony/TelephonyManager.java
index c5573ba..39ff283 100644
--- a/telephony/java/android/telephony/TelephonyManager.java
+++ b/telephony/java/android/telephony/TelephonyManager.java
@@ -2041,6 +2041,35 @@ public class TelephonyManager {
     }
 
     /**
+     * Informs the system of an intentional upcoming carrier network change by
+     * a carrier app. This call is optional and is only used to allow the
+     * system to provide alternative UI while telephony is performing an action
+     * that may result in intentional, temporary network lack of connectivity.
+     * <p>
+     * Based on the active parameter passed in, this method will either show or
+     * hide the alternative UI. There is no timeout associated with showing
+     * this UX, so a carrier app must be sure to call with active set to false
+     * sometime after calling with it set to true.
+     * <p>
+     * Requires Permission:
+     *   {@link android.Manifest.permission#MODIFY_PHONE_STATE MODIFY_PHONE_STATE}
+     * Or the calling app has carrier privileges.
+     *   @see #hasCarrierPrivileges
+     *
+     * @param active Whether the carrier network change is or shortly will be
+     *               active. Set this value to true to begin showing
+     *               alternative UI and false to stop.
+     */
+    public void notifyCarrierNetworkChange(boolean active) {
+        try {
+            if (sRegistry != null)
+                sRegistry.notifyCarrierNetworkChange(active);
+        } catch (RemoteException ex) {
+        } catch (NullPointerException ex) {
+        }
+    }
+
+    /**
      * Returns the alphabetic identifier associated with the line 1 number.
      * Return null if it is unavailable.
      * <p>