Document NFC permissions.

Change-Id: Ib1b1625058c9c673692f3fbcb3546ec7c2d54a07

11 files changed, 93 insertions, 12 deletions

diff --git a/core/java/android/nfc/NfcAdapter.java b/core/java/android/nfc/NfcAdapter.java
index 297f15b..b2ff6c4 100644
--- a/core/java/android/nfc/NfcAdapter.java
+++ b/core/java/android/nfc/NfcAdapter.java
@@ -37,7 +37,6 @@ import android.util.Log;
  * <p>
  * Use the helper {@link #getDefaultAdapter(Context)} to get the default NFC
  * adapter for this Android device.
- * <p>
  */
 public final class NfcAdapter {
     private static final String TAG = "NFC";
@@ -437,6 +436,8 @@ public final class NfcAdapter {
      * the completion of their {@link Activity#onPause} callback to disable foreground dispatch
      * after it has been enabled.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param activity the Activity to dispatch to
      * @param intent the PendingIntent to start for the dispatch
      * @param filters the IntentFilters to override dispatching for, or null to always dispatch
@@ -476,6 +477,8 @@ public final class NfcAdapter {
      *
      * <p>This method must be called from the main thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param activity the Activity to disable dispatch to
      * @throws IllegalStateException if the Activity has already been paused
      */
@@ -513,10 +516,12 @@ public final class NfcAdapter {
      *
      * <p>This method must be called from the main thread.
      *
-     * <p><em>NOTE</em> While foreground NDEF push is active standard tag dispatch is disabled.
+     * <p class="note"><em>NOTE:</em> While foreground NDEF push is active standard tag dispatch is disabled.
      * Only the foreground activity may receive tag discovered dispatches via
      * {@link #enableForegroundDispatch}.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param activity the foreground Activity
      * @param msg a NDEF Message to push over P2P
      * @throws IllegalStateException if the Activity is not currently in the foreground
@@ -548,6 +553,8 @@ public final class NfcAdapter {
      *
      * <p>This method must be called from the main thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param activity the Foreground activity
      * @throws IllegalStateException if the Activity has already been paused
      * @throws OperationNotSupportedException if this Android device does not support NDEF push
diff --git a/core/java/android/nfc/tech/IsoDep.java b/core/java/android/nfc/tech/IsoDep.java
index 2a132f9..9c3074b 100644
--- a/core/java/android/nfc/tech/IsoDep.java
+++ b/core/java/android/nfc/tech/IsoDep.java
@@ -26,12 +26,15 @@ import java.io.IOException;
 /**
  * Provides access to ISO-DEP (ISO 14443-4) properties and I/O operations on a {@link Tag}.
  *
- * <p>Acquire a {@link IsoDep} object using {@link #get}.
+ * <p>Acquire an {@link IsoDep} object using {@link #get}.
  * <p>The primary ISO-DEP I/O operation is {@link #transceive}. Applications must
  * implement their own protocol stack on top of {@link #transceive}.
  * <p>Tags that enumerate the {@link IsoDep} technology in {@link Tag#getTechList}
  * will also enumerate
  * {@link NfcA} or {@link NfcB} (since IsoDep builds on top of either of these).
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
  */
 public final class IsoDep extends BasicTagTechnology {
     private static final String TAG = "NFC";
@@ -80,6 +83,9 @@ public final class IsoDep extends BasicTagTechnology {
      * <p>Setting a longer timeout may be useful when performing
      * transactions that require a long processing time on the tag
      * such as key generation.
+     *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param timeout timeout value in milliseconds
      */
     public void setTimeout(int timeout) {
@@ -142,6 +148,8 @@ public final class IsoDep extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param data command bytes to send, must not be null
      * @return response bytes received, will not be null
      * @throws TagLostException if the tag leaves the field
diff --git a/core/java/android/nfc/tech/MifareClassic.java b/core/java/android/nfc/tech/MifareClassic.java
index 3d513b7..9a2f2bd 100644
--- a/core/java/android/nfc/tech/MifareClassic.java
+++ b/core/java/android/nfc/tech/MifareClassic.java
@@ -55,7 +55,7 @@ import java.nio.ByteOrder;
  * MIFARE Classic cards that have been formatted according to the
  * MIFARE Application Directory (MAD) specification.
  * <li>{@link #KEY_NFC_FORUM} is the well-known key for MIFARE Classic cards that
- * have been formatted according to the NFC
+ * have been formatted according to the NXP specification for NDEF on MIFARE Classic.
  *
  * <p>Implementation of this class on a Android NFC device is optional.
  * If it is not implemented, then
@@ -64,6 +64,9 @@ import java.nio.ByteOrder;
  * and {@link Ndef#MIFARE_CLASSIC} NDEF tags will also be supported. In either case,
  * {@link NfcA} will also be enumerated on the tag, because all MIFARE Classic tags are also
  * {@link NfcA}.
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
  */
 public final class MifareClassic extends BasicTagTechnology {
     /**
@@ -319,6 +322,8 @@ public final class MifareClassic extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param sectorIndex index of sector to authenticate, starting from 0
      * @param key 6-byte authentication key
      * @return true on success, false on authentication failure
@@ -344,6 +349,8 @@ public final class MifareClassic extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param sectorIndex index of sector to authenticate, starting from 0
      * @param key 6-byte authentication key
      * @return true on success, false on authentication failure
@@ -398,6 +405,8 @@ public final class MifareClassic extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param blockIndex index of block to read, starting from 0
      * @return 16 byte block
      * @throws TagLostException if the tag leaves the field
@@ -418,6 +427,8 @@ public final class MifareClassic extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param blockIndex index of block to write, starting from 0
      * @param data 16 bytes of data to write
      * @throws TagLostException if the tag leaves the field
@@ -445,6 +456,8 @@ public final class MifareClassic extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param blockIndex index of block to increment, starting from 0
      * @param value non-negative to increment by
      * @throws TagLostException if the tag leaves the field
@@ -471,6 +484,8 @@ public final class MifareClassic extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param blockIndex index of block to decrement, starting from 0
      * @param value non-negative to decrement by
      * @throws TagLostException if the tag leaves the field
@@ -497,6 +512,8 @@ public final class MifareClassic extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param blockIndex index of block to copy to
      * @throws TagLostException if the tag leaves the field
      * @throws IOException if there is an I/O failure, or the operation is canceled
@@ -517,6 +534,8 @@ public final class MifareClassic extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param blockIndex index of block to copy from
      * @throws TagLostException if the tag leaves the field
      * @throws IOException if there is an I/O failure, or the operation is canceled
@@ -541,6 +560,8 @@ public final class MifareClassic extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @see NfcA#transceive
      */
     public byte[] transceive(byte[] data) throws IOException {
diff --git a/core/java/android/nfc/tech/MifareUltralight.java b/core/java/android/nfc/tech/MifareUltralight.java
index 6c8f725..87c8d99 100644
--- a/core/java/android/nfc/tech/MifareUltralight.java
+++ b/core/java/android/nfc/tech/MifareUltralight.java
@@ -51,6 +51,9 @@ import java.io.IOException;
  * If it is enumerated, then all {@link MifareUltralight} I/O operations will be supported.
  * In either case, {@link NfcA} will also be enumerated on the tag,
  * because all MIFARE Ultralight tags are also {@link NfcA} tags.
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
  */
 public final class MifareUltralight extends BasicTagTechnology {
     /** A MIFARE Ultralight compatible tag of unknown type */
@@ -136,6 +139,8 @@ public final class MifareUltralight extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param pageOffset index of first page to read, starting from 0
      * @return 4 pages (16 bytes)
      * @throws TagLostException if the tag leaves the field
@@ -159,6 +164,8 @@ public final class MifareUltralight extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param pageOffset index of page to write, starting from 0
      * @param data 4 bytes to write
      * @throws TagLostException if the tag leaves the field
@@ -187,6 +194,8 @@ public final class MifareUltralight extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @see NfcA#transceive
      */
     public byte[] transceive(byte[] data) throws IOException {
diff --git a/core/java/android/nfc/tech/Ndef.java b/core/java/android/nfc/tech/Ndef.java
index 0467473..657eb64 100644
--- a/core/java/android/nfc/tech/Ndef.java
+++ b/core/java/android/nfc/tech/Ndef.java
@@ -44,7 +44,7 @@ import java.io.IOException;
  * formatted to contain NDEF data.
  * <ul>
  * <li>NFC Forum Type 1 Tag ({@link #NFC_FORUM_TYPE_1}), such as the Innovision Topaz
- * <li>NFC Forum Type 2 Tag ({@link #NFC_FORUM_TYPE_2}), such as the NXP Mifare Ultralight
+ * <li>NFC Forum Type 2 Tag ({@link #NFC_FORUM_TYPE_2}), such as the NXP MIFARE Ultralight
  * <li>NFC Forum Type 3 Tag ({@link #NFC_FORUM_TYPE_3}), such as Sony Felica
  * <li>NFC Forum Type 4 Tag ({@link #NFC_FORUM_TYPE_4}), such as NXP MIFARE Desfire
  * </ul>
@@ -66,9 +66,8 @@ import java.io.IOException;
  * recommended to use NFC Forum Types 1-4 in new deployments of NFC tags
  * with NDEF payload. Vendor NDEF formats will not work on all Android devices.
  *
- * <p class="note"><strong>Note:</strong>
- * Use of this class requires the {@link android.Manifest.permission#NFC}
- * permission.
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
  */
 public final class Ndef extends BasicTagTechnology {
     private static final String TAG = "NFC";
@@ -284,6 +283,8 @@ public final class Ndef extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param msg the NDEF Message to write, must not be null
      * @throws TagLostException if the tag leaves the field
      * @throws IOException if there is an I/O failure, or the operation is canceled
@@ -344,6 +345,8 @@ public final class Ndef extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @return true on success, false if it is not possible to make this tag read-only
      * @throws TagLostException if the tag leaves the field
      * @throws IOException if there is an I/O failure, or the operation is canceled
diff --git a/core/java/android/nfc/tech/NdefFormatable.java b/core/java/android/nfc/tech/NdefFormatable.java
index f667b58..bb2eb94 100644
--- a/core/java/android/nfc/tech/NdefFormatable.java
+++ b/core/java/android/nfc/tech/NdefFormatable.java
@@ -41,9 +41,8 @@ import java.io.IOException;
  * there is no mandatory set of tags for which all Android devices with NFC
  * must support {@link NdefFormatable}.
  *
- * <p class="note"><strong>Note:</strong>
- * Use of this class requires the {@link android.Manifest.permission#NFC}
- * permission.
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
  */
 public final class NdefFormatable extends BasicTagTechnology {
     private static final String TAG = "NFC";
@@ -85,7 +84,9 @@ public final class NdefFormatable extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
-     * @param firstMessage the NDEF message to write after formatting
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
+     * @param firstMessage the NDEF message to write after formatting, can be null
      * @throws TagLostException if the tag leaves the field
      * @throws IOException if there is an I/O failure, or the operation is canceled
      * @throws FormatException if the NDEF Message to write is malformed
@@ -105,6 +106,8 @@ public final class NdefFormatable extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param firstMessage the NDEF message to write after formatting
      * @throws TagLostException if the tag leaves the field
      * @throws IOException if there is an I/O failure, or the operation is canceled
diff --git a/core/java/android/nfc/tech/NfcA.java b/core/java/android/nfc/tech/NfcA.java
index 93d8510..1843eae 100644
--- a/core/java/android/nfc/tech/NfcA.java
+++ b/core/java/android/nfc/tech/NfcA.java
@@ -28,6 +28,9 @@ import java.io.IOException;
  * <p>Acquire a {@link NfcA} object using {@link #get}.
  * <p>The primary NFC-A I/O operation is {@link #transceive}. Applications must
  * implement their own protocol stack on top of {@link #transceive}.
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
  */
 public final class NfcA extends BasicTagTechnology {
     /** @hide */
@@ -99,6 +102,8 @@ public final class NfcA extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param data bytes to send
      * @return bytes received in response
      * @throws TagLostException if the tag leaves the field
diff --git a/core/java/android/nfc/tech/NfcB.java b/core/java/android/nfc/tech/NfcB.java
index 29246ee..22cb11d 100644
--- a/core/java/android/nfc/tech/NfcB.java
+++ b/core/java/android/nfc/tech/NfcB.java
@@ -28,6 +28,9 @@ import java.io.IOException;
  * <p>Acquire a {@link NfcB} object using {@link #get}.
  * <p>The primary NFC-B I/O operation is {@link #transceive}. Applications must
  * implement their own protocol stack on top of {@link #transceive}.
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
  */
 public final class NfcB extends BasicTagTechnology {
     /** @hide */
@@ -98,6 +101,8 @@ public final class NfcB extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param data bytes to send
      * @return bytes received in response
      * @throws TagLostException if the tag leaves the field
diff --git a/core/java/android/nfc/tech/NfcF.java b/core/java/android/nfc/tech/NfcF.java
index 27d1b57..e0ebbe8 100644
--- a/core/java/android/nfc/tech/NfcF.java
+++ b/core/java/android/nfc/tech/NfcF.java
@@ -28,6 +28,9 @@ import java.io.IOException;
  * <p>Acquire a {@link NfcF} object using {@link #get}.
  * <p>The primary NFC-F I/O operation is {@link #transceive}. Applications must
  * implement their own protocol stack on top of {@link #transceive}.
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
  */
 public final class NfcF extends BasicTagTechnology {
     /** @hide */
@@ -98,6 +101,8 @@ public final class NfcF extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param data bytes to send
      * @return bytes received in response
      * @throws TagLostException if the tag leaves the field
diff --git a/core/java/android/nfc/tech/NfcV.java b/core/java/android/nfc/tech/NfcV.java
index 99dc318..fe721c8 100644
--- a/core/java/android/nfc/tech/NfcV.java
+++ b/core/java/android/nfc/tech/NfcV.java
@@ -28,6 +28,9 @@ import java.io.IOException;
  * <p>Acquire a {@link NfcV} object using {@link #get}.
  * <p>The primary NFC-V I/O operation is {@link #transceive}. Applications must
  * implement their own protocol stack on top of {@link #transceive}.
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
  */
 public final class NfcV extends BasicTagTechnology {
     /** @hide */
@@ -98,6 +101,8 @@ public final class NfcV extends BasicTagTechnology {
      * not be called from the main application thread. A blocked call will be canceled with
      * {@link IOException} if {@link #close} is called from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @param data bytes to send
      * @return bytes received in response
      * @throws TagLostException if the tag leaves the field
diff --git a/core/java/android/nfc/tech/TagTechnology.java b/core/java/android/nfc/tech/TagTechnology.java
index be6ccd0..be5cbd2 100644
--- a/core/java/android/nfc/tech/TagTechnology.java
+++ b/core/java/android/nfc/tech/TagTechnology.java
@@ -75,6 +75,9 @@ import java.io.IOException;
  * <li>I/O operations may block, and should never be called on the main application
  * thread.
  * </ul>
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
  */
 public interface TagTechnology extends Closeable {
     /**
@@ -158,6 +161,8 @@ public interface TagTechnology extends Closeable {
      * <p>Only one {@link TagTechnology} object can be connected to a {@link Tag} at a time.
      * <p>Applications must call {@link #close} when I/O operations are complete.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @see #close()
      * @throws TagLostException if the tag leaves the field
      * @throws IOException if there is an I/O failure, or connect is canceled
@@ -172,6 +177,8 @@ public interface TagTechnology extends Closeable {
      * from the main application thread. A blocked call will be canceled with
      * {@link IOException} by calling {@link #close} from another thread.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @see #connect()
      * @see #close()
      * @throws TagLostException if the tag leaves the field
@@ -185,6 +192,8 @@ public interface TagTechnology extends Closeable {
      * <p>Also causes all blocked I/O operations on other thread to be canceled and
      * return with {@link IOException}.
      *
+     * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+     *
      * @see #connect()
      */
     public void close() throws IOException;
@@ -195,6 +204,7 @@ public interface TagTechnology extends Closeable {
      * <p>Returns true if {@link #connect} has completed, and {@link #close} has not been
      * called, and the {@link Tag} is not known to be out of range.
      * <p>Does not cause RF activity, and does not block.
+     *
      * @return true if I/O operations should be possible
      */
     public boolean isConnected();