Merge "NFC API updates."

7 files changed, 69 insertions, 51 deletions

diff --git a/core/java/android/nfc/NdefRecord.java b/core/java/android/nfc/NdefRecord.java
index 6ba3451..26571ff 100644
--- a/core/java/android/nfc/NdefRecord.java
+++ b/core/java/android/nfc/NdefRecord.java
@@ -152,8 +152,6 @@ public final class NdefRecord implements Parcelable {
      * RTD_ANDROID_APP records.
      * @hide
      */
-    // TODO unhide for ICS
-    // TODO recheck docs
     public static final byte[] RTD_ANDROID_APP = "android.com:pkg".getBytes();
 
     private static final byte FLAG_MB = (byte) 0x80;
@@ -352,21 +350,29 @@ public final class NdefRecord implements Parcelable {
     /**
      * Creates an Android application NDEF record.
      * <p>
+     * This record indicates to other Android devices the package
+     * that should be used to handle the rest of the NDEF message.
+     * You can embed this record anywhere into your NDEF message
+     * to ensure that the intended package receives the message.
+     * <p>
      * When an Android device dispatches an {@link NdefMessage}
      * containing one or more Android application records,
      * the applications contained in those records will be the
      * preferred target for the NDEF_DISCOVERED intent, in
      * the order in which they appear in the {@link NdefMessage}.
+     * This dispatch behavior was first added to Android in
+     * Ice Cream Sandwich.
      * <p>
      * If none of the applications are installed on the device,
      * a Market link will be opened to the first application.
      * <p>
      * Note that Android application records do not overrule
-     * applications that have called {@link NfcAdapter#enableForegroundDispatch}.
-     * @hide
+     * applications that have called
+     * {@link NfcAdapter#enableForegroundDispatch}.
+     *
+     * @param packageName Android package name
+     * @return Android application NDEF record
      */
-    // TODO unhide for ICS
-    // TODO recheck javadoc - should mention this works from ICS only
     public static NdefRecord createApplicationRecord(String packageName) {
         return new NdefRecord(TNF_EXTERNAL_TYPE, RTD_ANDROID_APP, new byte[] {},
                 packageName.getBytes(Charsets.US_ASCII));
diff --git a/core/java/android/nfc/NfcAdapter.java b/core/java/android/nfc/NfcAdapter.java
index d58b249..e392bca 100644
--- a/core/java/android/nfc/NfcAdapter.java
+++ b/core/java/android/nfc/NfcAdapter.java
@@ -507,16 +507,24 @@ public final class NfcAdapter {
      * <p>Pass a null NDEF message to disable foreground NDEF push in the
      * specified activities.
      *
+     * <p>One or more activities must be specified.
+     *
      * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
      *
      * @param message NDEF message to push over NFC, or null to disable
-     * @param activities one or more {@link Activity} to enable for NDEF push
+     * @param activity an activity to enable for NDEF push (at least one is required)
+     * @param activities zero or more additional activities to enable for NDEF Push
      */
-    public void setNdefPushMessage(NdefMessage message, Activity ... activities) {
-        if (activities.length == 0) {
-            throw new NullPointerException("Must specificy one or more activities");
+    public void setNdefPushMessage(NdefMessage message, Activity activity,
+            Activity ... activities) {
+        if (activity == null) {
+            throw new NullPointerException("activity cannot be null");
         }
+        mNfcActivityManager.setNdefPushMessage(activity, message);
         for (Activity a : activities) {
+            if (a == null) {
+                throw new NullPointerException("activities cannot contain null");
+            }
             mNfcActivityManager.setNdefPushMessage(a, message);
         }
     }
@@ -536,17 +544,24 @@ public final class NfcAdapter {
      * <p>Pass a null callback to disable the callback in the
      * specified activities.
      *
+     * <p>One or more activities must be specified.
+     *
      * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
      *
      * @param callback callback, or null to disable
-     * @param activities one or more {@link Activity} to enable for NDEF push
+     * @param activity an activity to enable for NDEF push (at least one is required)
+     * @param activities zero or more additional activities to enable for NDEF Push
      */
-    public void setNdefPushMessageCallback(CreateNdefMessageCallback callback,
+    public void setNdefPushMessageCallback(CreateNdefMessageCallback callback, Activity activity,
             Activity ... activities) {
-        if (activities.length == 0) {
-            throw new NullPointerException("Must specificy one or more activities");
+        if (activity == null) {
+            throw new NullPointerException("activity cannot be null");
         }
+        mNfcActivityManager.setNdefPushMessageCallback(activity, callback);
         for (Activity a : activities) {
+            if (a == null) {
+                throw new NullPointerException("activities cannot contain null");
+            }
             mNfcActivityManager.setNdefPushMessageCallback(a, callback);
         }
     }
@@ -558,17 +573,24 @@ public final class NfcAdapter {
      * can only occur when one of the specified activities is in resumed
      * (foreground) state.
      *
+     * <p>One or more activities must be specified.
+     *
      * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
      *
      * @param callback callback, or null to disable
-     * @param activities one or more {@link Activity} to enable the callback
+     * @param activity an activity to enable the callback (at least one is required)
+     * @param activities zero or more additional activities to enable to callback
      */
     public void setOnNdefPushCompleteCallback(OnNdefPushCompleteCallback callback,
-            Activity ... activities) {
-        if (activities.length == 0) {
-            throw new NullPointerException("Must specificy one or more activities");
+            Activity activity, Activity ... activities) {
+        if (activity == null) {
+            throw new NullPointerException("activity cannot be null");
         }
+        mNfcActivityManager.setOnNdefPushCompleteCallback(activity, callback);
         for (Activity a : activities) {
+            if (a == null) {
+                throw new NullPointerException("activities cannot contain null");
+            }
             mNfcActivityManager.setOnNdefPushCompleteCallback(a, callback);
         }
     }
diff --git a/core/java/android/nfc/tech/IsoDep.java b/core/java/android/nfc/tech/IsoDep.java
index 6054fe8..1859877 100644
--- a/core/java/android/nfc/tech/IsoDep.java
+++ b/core/java/android/nfc/tech/IsoDep.java
@@ -101,14 +101,12 @@ public final class IsoDep extends BasicTagTechnology {
     }
 
     /**
-     * Gets the currently set timeout of {@link #transceive} in milliseconds.
+     * Get the current timeout for {@link #transceive} in milliseconds.
      *
      * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
      *
      * @return timeout value in milliseconds
-     * @hide
      */
-    // TODO Unhide for ICS
     public int getTimeout() {
         try {
             return mTag.getTagService().getTimeout(TagTechnology.ISO_DEP);
diff --git a/core/java/android/nfc/tech/MifareClassic.java b/core/java/android/nfc/tech/MifareClassic.java
index ce923ae..9d1e6a1 100644
--- a/core/java/android/nfc/tech/MifareClassic.java
+++ b/core/java/android/nfc/tech/MifareClassic.java
@@ -584,9 +584,11 @@ public final class MifareClassic extends BasicTagTechnology {
     }
 
     /**
-     * Set the timeout of {@link #transceive} in milliseconds.
-     * <p>The timeout only applies to MifareUltralight {@link #transceive},
+     * Set the {@link #transceive} timeout in milliseconds.
+     *
+     * <p>The timeout only applies to {@link #transceive} on this object,
      * and is reset to a default value when {@link #close} is called.
+     *
      * <p>Setting a longer timeout may be useful when performing
      * transactions that require a long processing time on the tag
      * such as key generation.
@@ -594,9 +596,7 @@ public final class MifareClassic extends BasicTagTechnology {
      * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
      *
      * @param timeout timeout value in milliseconds
-     * @hide
      */
-    // TODO Unhide for ICS
     public void setTimeout(int timeout) {
         try {
             int err = mTag.getTagService().setTimeout(TagTechnology.MIFARE_CLASSIC, timeout);
@@ -609,14 +609,12 @@ public final class MifareClassic extends BasicTagTechnology {
     }
 
     /**
-     * Gets the currently set timeout of {@link #transceive} in milliseconds.
+     * Get the current {@link #transceive} timeout in milliseconds.
      *
      * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
      *
      * @return timeout value in milliseconds
-     * @hide
      */
-    // TODO Unhide for ICS
     public int getTimeout() {
         try {
             return mTag.getTagService().getTimeout(TagTechnology.MIFARE_CLASSIC);
diff --git a/core/java/android/nfc/tech/MifareUltralight.java b/core/java/android/nfc/tech/MifareUltralight.java
index 890b735..dec2c65 100644
--- a/core/java/android/nfc/tech/MifareUltralight.java
+++ b/core/java/android/nfc/tech/MifareUltralight.java
@@ -224,9 +224,11 @@ public final class MifareUltralight extends BasicTagTechnology {
     }
 
     /**
-     * Set the timeout of {@link #transceive} in milliseconds.
-     * <p>The timeout only applies to MifareUltralight {@link #transceive},
+     * Set the {@link #transceive} timeout in milliseconds.
+     *
+     * <p>The timeout only applies to {@link #transceive} on this object,
      * and is reset to a default value when {@link #close} is called.
+     *
      * <p>Setting a longer timeout may be useful when performing
      * transactions that require a long processing time on the tag
      * such as key generation.
@@ -234,9 +236,7 @@ public final class MifareUltralight extends BasicTagTechnology {
      * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
      *
      * @param timeout timeout value in milliseconds
-     * @hide
      */
-    // TODO Unhide for ICS
     public void setTimeout(int timeout) {
         try {
             int err = mTag.getTagService().setTimeout(
@@ -250,14 +250,12 @@ public final class MifareUltralight extends BasicTagTechnology {
     }
 
     /**
-     * Gets the currently set timeout of {@link #transceive} in milliseconds.
+     * Get the current {@link #transceive} timeout in milliseconds.
      *
      * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
      *
      * @return timeout value in milliseconds
-     * @hide
      */
-    // TODO Unhide for ICS
     public int getTimeout() {
         try {
             return mTag.getTagService().getTimeout(TagTechnology.MIFARE_ULTRALIGHT);
diff --git a/core/java/android/nfc/tech/NfcA.java b/core/java/android/nfc/tech/NfcA.java
index bb8aec9..88730f9 100644
--- a/core/java/android/nfc/tech/NfcA.java
+++ b/core/java/android/nfc/tech/NfcA.java
@@ -129,9 +129,11 @@ public final class NfcA extends BasicTagTechnology {
     }
 
     /**
-     * Set the timeout of {@link #transceive} in milliseconds.
-     * <p>The timeout only applies to NfcA {@link #transceive}, and is
-     * reset to a default value when {@link #close} is called.
+     * Set the {@link #transceive} timeout in milliseconds.
+     *
+     * <p>The timeout only applies to {@link #transceive} on this object,
+     * and is reset to a default value when {@link #close} is called.
+     *
      * <p>Setting a longer timeout may be useful when performing
      * transactions that require a long processing time on the tag
      * such as key generation.
@@ -139,9 +141,7 @@ public final class NfcA extends BasicTagTechnology {
      * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
      *
      * @param timeout timeout value in milliseconds
-     * @hide
      */
-    // TODO Unhide for ICS
     public void setTimeout(int timeout) {
         try {
             int err = mTag.getTagService().setTimeout(TagTechnology.NFC_A, timeout);
@@ -154,14 +154,12 @@ public final class NfcA extends BasicTagTechnology {
     }
 
     /**
-     * Gets the currently set timeout of {@link #transceive} in milliseconds.
+     * Get the current {@link #transceive} timeout in milliseconds.
      *
      * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
      *
      * @return timeout value in milliseconds
-     * @hide
      */
-    // TODO Unhide for ICS
     public int getTimeout() {
         try {
             return mTag.getTagService().getTimeout(TagTechnology.NFC_A);
diff --git a/core/java/android/nfc/tech/NfcF.java b/core/java/android/nfc/tech/NfcF.java
index 0938fb4..b3e3ab6 100644
--- a/core/java/android/nfc/tech/NfcF.java
+++ b/core/java/android/nfc/tech/NfcF.java
@@ -128,9 +128,11 @@ public final class NfcF extends BasicTagTechnology {
     }
 
     /**
-     * Set the timeout of {@link #transceive} in milliseconds.
-     * <p>The timeout only applies to NfcF {@link #transceive}, and is
-     * reset to a default value when {@link #close} is called.
+     * Set the {@link #transceive} timeout in milliseconds.
+     *
+     * <p>The timeout only applies to {@link #transceive} on this object,
+     * and is reset to a default value when {@link #close} is called.
+     *
      * <p>Setting a longer timeout may be useful when performing
      * transactions that require a long processing time on the tag
      * such as key generation.
@@ -138,9 +140,7 @@ public final class NfcF extends BasicTagTechnology {
      * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
      *
      * @param timeout timeout value in milliseconds
-     * @hide
      */
-    // TODO Unhide for ICS
     public void setTimeout(int timeout) {
         try {
             int err = mTag.getTagService().setTimeout(TagTechnology.NFC_F, timeout);
@@ -153,14 +153,12 @@ public final class NfcF extends BasicTagTechnology {
     }
 
     /**
-     * Gets the currently set timeout of {@link #transceive} in milliseconds.
+     * Get the current {@link #transceive} timeout in milliseconds.
      *
      * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
      *
      * @return timeout value in milliseconds
-     * @hide
      */
-    // TODO Unhide for ICS
     public int getTimeout() {
         try {
             return mTag.getTagService().getTimeout(TagTechnology.NFC_F);