nfc(api): Address API council feedback for always on API
Comments addressed:
1. Since setControllerAlwaysOn takes an integer, should this be named
“setControllerAlwaysOnMode” instead?
2. How does the setControllerAlwaysOn in NfcOemExtension work?
Is it a replacement for the version in NfcAdapter? Should this be documented?
3. spelling : “operation has bee initiated” -> should be “operation has been initiated”
Bug: 368149547
Test: atest CtsNfcTestCases
Change-Id: If02c65a99797cc7221a58bef04da4756034d5d23
diff --git a/nfc/api/system-current.txt b/nfc/api/system-current.txt
index 9603c0a..d17a9b6 100644
--- a/nfc/api/system-current.txt
+++ b/nfc/api/system-current.txt
@@ -60,7 +60,7 @@
method @FlaggedApi("android.nfc.nfc_oem_extension") @NonNull public java.util.List<java.lang.String> getActiveNfceeList();
method @FlaggedApi("android.nfc.nfc_oem_extension") @RequiresPermission(android.Manifest.permission.WRITE_SECURE_SETTINGS) public void maybeTriggerFirmwareUpdate();
method @FlaggedApi("android.nfc.nfc_oem_extension") @RequiresPermission(android.Manifest.permission.WRITE_SECURE_SETTINGS) public void registerCallback(@NonNull java.util.concurrent.Executor, @NonNull android.nfc.NfcOemExtension.Callback);
- method @FlaggedApi("android.nfc.nfc_oem_extension") @RequiresPermission(android.Manifest.permission.NFC_SET_CONTROLLER_ALWAYS_ON) public void setControllerAlwaysOn(int);
+ method @FlaggedApi("android.nfc.nfc_oem_extension") @RequiresPermission(android.Manifest.permission.NFC_SET_CONTROLLER_ALWAYS_ON) public void setControllerAlwaysOnMode(int);
method @FlaggedApi("android.nfc.nfc_oem_extension") @RequiresPermission(android.Manifest.permission.WRITE_SECURE_SETTINGS) public void synchronizeScreenState();
method @FlaggedApi("android.nfc.nfc_oem_extension") @RequiresPermission(android.Manifest.permission.WRITE_SECURE_SETTINGS) public void unregisterCallback(@NonNull android.nfc.NfcOemExtension.Callback);
field @FlaggedApi("android.nfc.nfc_oem_extension") public static final int DISABLE = 0; // 0x0
diff --git a/nfc/java/android/nfc/NfcAdapter.java b/nfc/java/android/nfc/NfcAdapter.java
index 2804546..951702c 100644
--- a/nfc/java/android/nfc/NfcAdapter.java
+++ b/nfc/java/android/nfc/NfcAdapter.java
@@ -560,13 +560,13 @@
public @interface TagIntentAppPreferenceResult {}
/**
- * Mode Type for {@link NfcOemExtension#setControllerAlwaysOn(int)}.
+ * Mode Type for {@link NfcOemExtension#setControllerAlwaysOnMode(int)}.
* @hide
*/
public static final int CONTROLLER_ALWAYS_ON_MODE_DEFAULT = 1;
/**
- * Mode Type for {@link NfcOemExtension#setControllerAlwaysOn(int)}.
+ * Mode Type for {@link NfcOemExtension#setControllerAlwaysOnMode(int)}.
* @hide
*/
public static final int CONTROLLER_ALWAYS_ON_DISABLE = 0;
@@ -2323,7 +2323,7 @@
* <p>This API is for the NFCC internal state management. It allows to discriminate
* the controller function from the NFC function by keeping the NFC controller on without
* any NFC RF enabled if necessary.
- * <p>This call is asynchronous. Register a listener {@link #ControllerAlwaysOnListener}
+ * <p>This call is asynchronous. Register a listener {@link ControllerAlwaysOnListener}
* by {@link #registerControllerAlwaysOnListener} to find out when the operation is
* complete.
* <p>If this returns true, then either NFCC always on state has been set based on the value,
@@ -2337,7 +2337,7 @@
* FEATURE_NFC_HOST_CARD_EMULATION, FEATURE_NFC_HOST_CARD_EMULATION_NFCF,
* FEATURE_NFC_OFF_HOST_CARD_EMULATION_UICC and FEATURE_NFC_OFF_HOST_CARD_EMULATION_ESE
* are unavailable
- * @return true if feature is supported by the device and operation has bee initiated,
+ * @return true if feature is supported by the device and operation has been initiated,
* false if the feature is not supported by the device.
* @hide
*/
diff --git a/nfc/java/android/nfc/NfcOemExtension.java b/nfc/java/android/nfc/NfcOemExtension.java
index 45038d4..011c60b 100644
--- a/nfc/java/android/nfc/NfcOemExtension.java
+++ b/nfc/java/android/nfc/NfcOemExtension.java
@@ -70,7 +70,7 @@
private boolean mRfDiscoveryStarted = false;
/**
- * Mode Type for {@link #setControllerAlwaysOn(int)}.
+ * Mode Type for {@link #setControllerAlwaysOnMode(int)}.
* Enables the controller in default mode when NFC is disabled (existing API behavior).
* works same as {@link NfcAdapter#setControllerAlwaysOn(boolean)}.
* @hide
@@ -80,7 +80,7 @@
public static final int ENABLE_DEFAULT = NfcAdapter.CONTROLLER_ALWAYS_ON_MODE_DEFAULT;
/**
- * Mode Type for {@link #setControllerAlwaysOn(int)}.
+ * Mode Type for {@link #setControllerAlwaysOnMode(int)}.
* Enables the controller in transparent mode when NFC is disabled.
* @hide
*/
@@ -89,7 +89,7 @@
public static final int ENABLE_TRANSPARENT = 2;
/**
- * Mode Type for {@link #setControllerAlwaysOn(int)}.
+ * Mode Type for {@link #setControllerAlwaysOnMode(int)}.
* Enables the controller and initializes and enables the EE subsystem when NFC is disabled.
* @hide
*/
@@ -98,7 +98,7 @@
public static final int ENABLE_EE = 3;
/**
- * Mode Type for {@link #setControllerAlwaysOn(int)}.
+ * Mode Type for {@link #setControllerAlwaysOnMode(int)}.
* Disable the Controller Always On Mode.
* works same as {@link NfcAdapter#setControllerAlwaysOn(boolean)}.
* @hide
@@ -108,7 +108,7 @@
public static final int DISABLE = NfcAdapter.CONTROLLER_ALWAYS_ON_DISABLE;
/**
- * Possible controller modes for {@link #setControllerAlwaysOn(int)}.
+ * Possible controller modes for {@link #setControllerAlwaysOnMode(int)}.
*
* @hide
*/
@@ -449,6 +449,9 @@
* <p>This call is asynchronous, register listener {@link NfcAdapter.ControllerAlwaysOnListener}
* by {@link NfcAdapter#registerControllerAlwaysOnListener} to find out when the operation is
* complete.
+ * <p> Note: This adds more always on modes on top of existing
+ * {@link NfcAdapter#setControllerAlwaysOn(boolean)} API which can be used to set the NFCC in
+ * only {@link #ENABLE_DEFAULT} and {@link #DISABLE} modes.
* @param mode one of {@link ControllerMode} modes
* @throws UnsupportedOperationException if
* <li> if FEATURE_NFC, FEATURE_NFC_HOST_CARD_EMULATION, FEATURE_NFC_HOST_CARD_EMULATION_NFCF,
@@ -456,11 +459,12 @@
* are unavailable </li>
* <li> if the feature is unavailable @see NfcAdapter#isNfcControllerAlwaysOnSupported() </li>
* @hide
+ * @see NfcAdapter#setControllerAlwaysOn(boolean)
*/
@SystemApi
@FlaggedApi(Flags.FLAG_NFC_OEM_EXTENSION)
@RequiresPermission(android.Manifest.permission.NFC_SET_CONTROLLER_ALWAYS_ON)
- public void setControllerAlwaysOn(@ControllerMode int mode) {
+ public void setControllerAlwaysOnMode(@ControllerMode int mode) {
if (!NfcAdapter.sHasNfcFeature && !NfcAdapter.sHasCeFeature) {
throw new UnsupportedOperationException();
}