Update preferred payment related APIs

Add API docs for ACTION_PREFERRED_PAYMENT_CHANGED and the constants(PREFERRED_PAYMENT_*).
Change return type from String to CharSequence for
getDescriptionForPreferredPaymentService.

Test: build pass
Bug: 149998286
Change-Id: Ibe0c77bb25da2673cc8f46cd1e2735c0a1e30523

3 files changed, 32 insertions, 13 deletions

diff --git a/api/current.txt b/api/current.txt
index 4118bcc6baf8..084b1fece51d 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -31170,7 +31170,7 @@ package android.nfc.cardemulation {
     method public boolean categoryAllowsForegroundPreference(String);
     method @Nullable @RequiresPermission(android.Manifest.permission.NFC_PREFERRED_PAYMENT_INFO) public java.util.List<java.lang.String> getAidsForPreferredPaymentService();
     method public java.util.List<java.lang.String> getAidsForService(android.content.ComponentName, String);
-    method @Nullable @RequiresPermission(android.Manifest.permission.NFC_PREFERRED_PAYMENT_INFO) public String getDescriptionForPreferredPaymentService();
+    method @Nullable @RequiresPermission(android.Manifest.permission.NFC_PREFERRED_PAYMENT_INFO) public CharSequence getDescriptionForPreferredPaymentService();
     method public static android.nfc.cardemulation.CardEmulation getInstance(android.nfc.NfcAdapter);
     method @Nullable @RequiresPermission(android.Manifest.permission.NFC_PREFERRED_PAYMENT_INFO) public String getRouteDestinationForPreferredPaymentService();
     method public int getSelectionModeForCategory(String);
diff --git a/core/java/android/nfc/NfcAdapter.java b/core/java/android/nfc/NfcAdapter.java
index d320f61a3657..c61f10f50c93 100644
--- a/core/java/android/nfc/NfcAdapter.java
+++ b/core/java/android/nfc/NfcAdapter.java
@@ -245,13 +245,25 @@ public final class NfcAdapter {
 
     /**
      * Mandatory String extra field in {@link #ACTION_PREFERRED_PAYMENT_CHANGED}
-     * Indicates the condition when trigger this event.
+     * Indicates the condition when trigger this event. Possible values are:
+     * {@link #PREFERRED_PAYMENT_LOADED},
+     * {@link #PREFERRED_PAYMENT_CHANGED},
+     * {@link #PREFERRED_PAYMENT_UPDATED},
      */
     public static final String EXTRA_PREFERRED_PAYMENT_CHANGED_REASON =
             "android.nfc.extra.PREFERRED_PAYMENT_CHANGED_REASON";
-
+    /**
+     * Nfc is enabled and the preferred payment aids are registered.
+     */
     public static final int PREFERRED_PAYMENT_LOADED = 1;
+    /**
+     * User selected another payment application as the preferred payment.
+     */
     public static final int PREFERRED_PAYMENT_CHANGED = 2;
+    /**
+     * Current preferred payment has issued an update (registered/unregistered new aids or has been
+     * updated itself).
+     */
     public static final int PREFERRED_PAYMENT_UPDATED = 3;
 
     public static final int STATE_OFF = 1;
diff --git a/core/java/android/nfc/cardemulation/CardEmulation.java b/core/java/android/nfc/cardemulation/CardEmulation.java
index f1c74a6331c4..7bf82e84927f 100644
--- a/core/java/android/nfc/cardemulation/CardEmulation.java
+++ b/core/java/android/nfc/cardemulation/CardEmulation.java
@@ -672,7 +672,7 @@ public final class CardEmulation {
             recoverService();
             if (sService == null) {
                 Log.e(TAG, "Failed to recover CardEmulationService.");
-                return null;
+                throw e.rethrowFromSystemServer();
             }
             try {
                 ApduServiceInfo serviceInfo =
@@ -680,7 +680,7 @@ public final class CardEmulation {
                 return (serviceInfo != null ? serviceInfo.getAids() : null);
             } catch (RemoteException ee) {
                 Log.e(TAG, "Failed to recover CardEmulationService.");
-                return null;
+                throw e.rethrowFromSystemServer();
             }
         }
     }
@@ -690,9 +690,16 @@ public final class CardEmulation {
      *
      * @return The route destination secure element name of the preferred payment service.
      *         HCE payment: "Host"
-     *         OffHost payment: prefix SIM or prefix eSE string.
-     *                          "OffHost" if the payment service does not specify secure element
-     *                          name.
+     *         OffHost payment: 1. String with prefix SIM or prefix eSE string.
+     *                             Ref: GSMA TS.26 - NFC Handset Requirements
+     *                             TS26_NFC_REQ_069: For UICC, Secure Element Name SHALL be
+     *                                               SIM[smartcard slot]
+     *                                               (e.g. SIM/SIM1, SIM2… SIMn).
+     *                             TS26_NFC_REQ_070: For embedded SE, Secure Element Name SHALL be
+     *                                               eSE[number]
+     *                                               (e.g. eSE/eSE1, eSE2, etc.).
+     *                          2. "OffHost" if the payment service does not specify secure element
+     *                             name.
      */
     @RequiresPermission(android.Manifest.permission.NFC_PREFERRED_PAYMENT_INFO)
     @Nullable
@@ -711,7 +718,7 @@ public final class CardEmulation {
             recoverService();
             if (sService == null) {
                 Log.e(TAG, "Failed to recover CardEmulationService.");
-                return null;
+                throw e.rethrowFromSystemServer();
             }
             try {
                 ApduServiceInfo serviceInfo =
@@ -727,7 +734,7 @@ public final class CardEmulation {
 
             } catch (RemoteException ee) {
                 Log.e(TAG, "Failed to recover CardEmulationService.");
-                return null;
+                throw e.rethrowFromSystemServer();
             }
         }
     }
@@ -739,7 +746,7 @@ public final class CardEmulation {
      */
     @RequiresPermission(android.Manifest.permission.NFC_PREFERRED_PAYMENT_INFO)
     @Nullable
-    public String getDescriptionForPreferredPaymentService() {
+    public CharSequence getDescriptionForPreferredPaymentService() {
         try {
             ApduServiceInfo serviceInfo = sService.getPreferredPaymentService(mContext.getUserId());
             return (serviceInfo != null ? serviceInfo.getDescription() : null);
@@ -747,7 +754,7 @@ public final class CardEmulation {
             recoverService();
             if (sService == null) {
                 Log.e(TAG, "Failed to recover CardEmulationService.");
-                return null;
+                throw e.rethrowFromSystemServer();
             }
             try {
                 ApduServiceInfo serviceInfo =
@@ -755,7 +762,7 @@ public final class CardEmulation {
                 return (serviceInfo != null ? serviceInfo.getDescription() : null);
             } catch (RemoteException ee) {
                 Log.e(TAG, "Failed to recover CardEmulationService.");
-                return null;
+                throw e.rethrowFromSystemServer();
             }
         }
     }