API Change: add isNdefPushEnabled() & ACTION_NFC_SETTINGS.

Modify isNdefPushEnabled() semantics slightly - true only if isNfcEnabled && NDEF push enabled.

Fix up docs.

Change-Id: Icd2df9c636ecf2d8274851bbda423f2eae7bac5f

3 files changed, 48 insertions, 12 deletions

diff --git a/api/current.txt b/api/current.txt
index c963b4e4885d..d9d9b7695925 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -12636,6 +12636,7 @@ package android.nfc {
     method public static android.nfc.NfcAdapter getDefaultAdapter(android.content.Context);
     method public static deprecated android.nfc.NfcAdapter getDefaultAdapter();
     method public boolean isEnabled();
+    method public boolean isNdefPushEnabled();
     method public void setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...);
     method public void setNdefPushMessageCallback(android.nfc.NfcAdapter.CreateNdefMessageCallback, android.app.Activity, android.app.Activity...);
     method public void setOnNdefPushCompleteCallback(android.nfc.NfcAdapter.OnNdefPushCompleteCallback, android.app.Activity, android.app.Activity...);
@@ -17298,6 +17299,7 @@ package android.provider {
     field public static final java.lang.String ACTION_MEMORY_CARD_SETTINGS = "android.settings.MEMORY_CARD_SETTINGS";
     field public static final java.lang.String ACTION_NETWORK_OPERATOR_SETTINGS = "android.settings.NETWORK_OPERATOR_SETTINGS";
     field public static final java.lang.String ACTION_NFCSHARING_SETTINGS = "android.settings.NFCSHARING_SETTINGS";
+    field public static final java.lang.String ACTION_NFC_SETTINGS = "android.settings.NFC_SETTINGS";
     field public static final java.lang.String ACTION_PRIVACY_SETTINGS = "android.settings.PRIVACY_SETTINGS";
     field public static final java.lang.String ACTION_QUICK_LAUNCH_SETTINGS = "android.settings.QUICK_LAUNCH_SETTINGS";
     field public static final java.lang.String ACTION_SEARCH_SETTINGS = "android.search.action.SEARCH_SETTINGS";
diff --git a/core/java/android/nfc/NfcAdapter.java b/core/java/android/nfc/NfcAdapter.java
index 33310dfd0ad8..f2bccaa72d84 100644
--- a/core/java/android/nfc/NfcAdapter.java
+++ b/core/java/android/nfc/NfcAdapter.java
@@ -412,11 +412,13 @@ public final class NfcAdapter {
     /**
      * Return true if this NFC Adapter has any features enabled.
      *
-     * <p>Application may use this as a helper to suggest that the user
-     * should turn on NFC in Settings.
      * <p>If this method returns false, the NFC hardware is guaranteed not to
-     * generate or respond to any NFC transactions.
+     * generate or respond to any NFC communication over its NFC radio.
+     * <p>Applications can use this to check if NFC is enabled. Applications
+     * can request Settings UI allowing the user to toggle NFC using:
+     * <p><pre>startActivity(new Intent(Settings.ACTION_NFC_SETTINGS))</pre>
      *
+     * @see android.provider.Settings#ACTION_NFC_SETTINGS
      * @return true if this NFC Adapter has any features enabled
      */
     public boolean isEnabled() {
@@ -796,16 +798,28 @@ public final class NfcAdapter {
     }
 
     /**
-     * Return true if NDEF Push feature is enabled.
-     * <p>This function can return true even if NFC is currently turned-off.
-     * This indicates that NDEF Push is not currently active, but it has
-     * been requested by the user and will be active as soon as NFC is turned
-     * on.
-     * <p>If you want to check if NDEF PUsh sharing is currently active, use
-     * <code>{@link #isEnabled()} && {@link #isNdefPushEnabled()}</code>
+     * Return true if the NDEF Push (Android Beam) feature is enabled.
+     * <p>This function will return true only if both NFC is enabled, and the
+     * NDEF Push feature is enabled.
+     * <p>Note that if NFC is enabled but NDEF Push is disabled then this
+     * device can still <i>receive</i> NDEF messages, it just cannot send them.
+     * <p>Applications cannot directly toggle the NDEF Push feature, but they
+     * can request Settings UI allowing the user to toggle NDEF Push using
+     * <code>startActivity(new Intent(Settings.ACTION_NFCSHARING_SETTINGS))</code>
+     * <p>Example usage in an Activity that requires NDEF Push:
+     * <p><pre>
+     * protected void onResume() {
+     *     super.onResume();
+     *     if (!nfcAdapter.isEnabled()) {
+     *         startActivity(new Intent(Settings.ACTION_NFC_SETTINGS));
+     *     } else if (!nfcAdapter.isNdefPushEnabled()) {
+     *         startActivity(new Intent(Settings.ACTION_NFCSHARING_SETTINGS));
+     *     }
+     * }
+     * </pre>
      *
+     * @see android.provider.Settings#ACTION_NFCSHARING_SETTINGS
      * @return true if NDEF Push feature is enabled
-     * @hide
      */
     public boolean isNdefPushEnabled() {
         try {
diff --git a/core/java/android/provider/Settings.java b/core/java/android/provider/Settings.java
index 5754e60d0815..0b59866f7b0f 100644
--- a/core/java/android/provider/Settings.java
+++ b/core/java/android/provider/Settings.java
@@ -569,7 +569,26 @@ public final class Settings {
         "android.settings.DEVICE_INFO_SETTINGS";
 
     /**
-     * Activity Action: Show NFC sharing settings.
+     * Activity Action: Show NFC settings.
+     * <p>
+     * This shows UI that allows NFC to be turned on or off.
+     * <p>
+     * In some cases, a matching Activity may not exist, so ensure you
+     * safeguard against this.
+     * <p>
+     * Input: Nothing.
+     * <p>
+     * Output: Nothing
+     * @see android.nfc.NfcAdapter#isEnabled()
+     */
+    @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
+    public static final String ACTION_NFC_SETTINGS = "android.settings.NFC_SETTINGS";
+
+    /**
+     * Activity Action: Show NFC Sharing settings.
+     * <p>
+     * This shows UI that allows NDEF Push (Android Beam) to be turned on or
+     * off.
      * <p>
      * In some cases, a matching Activity may not exist, so ensure you
      * safeguard against this.
@@ -577,6 +596,7 @@ public final class Settings {
      * Input: Nothing.
      * <p>
      * Output: Nothing
+     * @see android.nfc.NfcAdapter#isNdefPushEnabled()
      */
     @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
     public static final String ACTION_NFCSHARING_SETTINGS =