Document NFC permissions.

Change-Id: Ib1b1625058c9c673692f3fbcb3546ec7c2d54a07

Author: Nick Pelly

core/java/android/nfc/NfcAdapter.java

@@ -37,7 +37,6 @@
  * <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 boolean disable() {
      * 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 void enableForegroundDispatch(Activity activity, PendingIntent intent,
      *
      * <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 @@ void disableForegroundDispatchInternal(Activity activity, boolean force) {
      *
      * <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 void enableForegroundNdefPush(Activity activity, NdefMessage msg) {
      *
      * <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

core/java/android/nfc/tech/IsoDep.java

@@ -26,12 +26,15 @@
 /**
  * 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 IsoDep(Tag tag)
      * <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 byte[] getHiLayerResponse() {
      * 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

core/java/android/nfc/tech/MifareClassic.java

@@ -55,7 +55,7 @@
  * 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 @@
  * 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 int sectorToBlock(int sectorIndex) {
      * 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 boolean authenticateSectorWithKeyA(int sectorIndex, byte[] key) throws IO
      * 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 @@ private boolean authenticate(int sector, byte[] key, boolean keyA) throws IOExce
      * 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 byte[] readBlock(int blockIndex) throws IOException {
      * 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 void writeBlock(int blockIndex, byte[] data) throws IOException {
      * 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 void increment(int blockIndex, int value) throws IOException {
      * 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 void decrement(int blockIndex, int value) throws IOException {
      * 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 void transfer(int blockIndex) throws IOException {
      * 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 void restore(int blockIndex) throws IOException {
      * 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 {

core/java/android/nfc/tech/MifareUltralight.java

@@ -51,6 +51,9 @@
  * 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 int getType() {
      * 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 byte[] readPages(int pageOffset) throws IOException {
      * 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 void writePage(int pageOffset, byte[] data) throws IOException {
      * 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 {

core/java/android/nfc/tech/Ndef.java

@@ -44,7 +44,7 @@
  * 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 @@
  * 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 NdefMessage getNdefMessage() throws IOException, FormatException {
      * 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 boolean canMakeReadOnly() {
      * 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

core/java/android/nfc/tech/NdefFormatable.java

@@ -41,9 +41,8 @@
  * 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 NdefFormatable(Tag tag) throws RemoteException {
      * 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 void format(NdefMessage firstMessage) throws IOException, FormatException
      * 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

core/java/android/nfc/tech/NfcA.java

@@ -28,6 +28,9 @@
  * <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 short getSak() {
      * 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

core/java/android/nfc/tech/NfcB.java

@@ -28,6 +28,9 @@
  * <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 byte[] getProtocolInfo() {
      * 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

core/java/android/nfc/tech/NfcF.java

@@ -28,6 +28,9 @@
  * <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 byte[] getManufacturer() {
      * 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

core/java/android/nfc/tech/NfcV.java

@@ -28,6 +28,9 @@
  * <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 byte getDsfId() {
      * 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