From 39cf3a445e507f219ecc8a476f6038f095d9d520 Mon Sep 17 00:00:00 2001 From: Nick Pelly Date: Mon, 7 Feb 2011 17:04:21 +0900 Subject: [PATCH] Document NFC permissions. Change-Id: Ib1b1625058c9c673692f3fbcb3546ec7c2d54a07 --- core/java/android/nfc/NfcAdapter.java | 11 +++++++++-- core/java/android/nfc/tech/IsoDep.java | 10 +++++++++- core/java/android/nfc/tech/MifareClassic.java | 23 ++++++++++++++++++++++- core/java/android/nfc/tech/MifareUltralight.java | 9 +++++++++ core/java/android/nfc/tech/Ndef.java | 11 +++++++---- core/java/android/nfc/tech/NdefFormatable.java | 11 +++++++---- core/java/android/nfc/tech/NfcA.java | 5 +++++ core/java/android/nfc/tech/NfcB.java | 5 +++++ core/java/android/nfc/tech/NfcF.java | 5 +++++ core/java/android/nfc/tech/NfcV.java | 5 +++++ core/java/android/nfc/tech/TagTechnology.java | 10 ++++++++++ 11 files changed, 93 insertions(+), 12 deletions(-) diff --git a/core/java/android/nfc/NfcAdapter.java b/core/java/android/nfc/NfcAdapter.java index 297f15bea41e..b2ff6c4a9730 100644 --- a/core/java/android/nfc/NfcAdapter.java +++ b/core/java/android/nfc/NfcAdapter.java @@ -37,7 +37,6 @@ import android.util.Log; *

* Use the helper {@link #getDefaultAdapter(Context)} to get the default NFC * adapter for this Android device. - *

*/ 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. * + *

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 { * *

This method must be called from the main thread. * + *

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 { * *

This method must be called from the main thread. * - *

NOTE While foreground NDEF push is active standard tag dispatch is disabled. + *

NOTE: While foreground NDEF push is active standard tag dispatch is disabled. * Only the foreground activity may receive tag discovered dispatches via * {@link #enableForegroundDispatch}. * + *

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 { * *

This method must be called from the main thread. * + *

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 2a132f9a3329..9c3074ba4e2f 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}. * - *

Acquire a {@link IsoDep} object using {@link #get}. + *

Acquire an {@link IsoDep} object using {@link #get}. *

The primary ISO-DEP I/O operation is {@link #transceive}. Applications must * implement their own protocol stack on top of {@link #transceive}. *

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). + * + *

Note: 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 { *

Setting a longer timeout may be useful when performing * transactions that require a long processing time on the tag * such as key generation. + * + *

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. * + *

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 3d513b7195a6..9a2f2bd5124b 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. *

  • {@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. * *

    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}. + * + *

    Note: 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. * + *

    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. * + *

    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. * + *

    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. * + *

    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. * + *

    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. * + *

    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. * + *

    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. * + *

    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. * + *

    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 6c8f725b13ff..87c8d993c611 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. + * + *

    Note: 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. * + *

    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. * + *

    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. * + *

    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 04674737229a..657eb64d9e7d 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. *

    @@ -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. * - *

    Note: - * Use of this class requires the {@link android.Manifest.permission#NFC} - * permission. + *

    Note: 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. * + *

    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. * + *

    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 f667b58a8cc7..bb2eb943d46d 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}. * - *

    Note: - * Use of this class requires the {@link android.Manifest.permission#NFC} - * permission. + *

    Note: 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 + *

    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. * + *

    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 93d85108c5b0..1843eaed24db 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; *

    Acquire a {@link NfcA} object using {@link #get}. *

    The primary NFC-A I/O operation is {@link #transceive}. Applications must * implement their own protocol stack on top of {@link #transceive}. + * + *

    Note: 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. * + *

    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 29246ee95074..22cb11dd4763 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; *

    Acquire a {@link NfcB} object using {@link #get}. *

    The primary NFC-B I/O operation is {@link #transceive}. Applications must * implement their own protocol stack on top of {@link #transceive}. + * + *

    Note: 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. * + *

    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 27d1b57b4dab..e0ebbe82c4e9 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; *

    Acquire a {@link NfcF} object using {@link #get}. *

    The primary NFC-F I/O operation is {@link #transceive}. Applications must * implement their own protocol stack on top of {@link #transceive}. + * + *

    Note: 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. * + *

    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 99dc31836e49..fe721c88b048 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; *

    Acquire a {@link NfcV} object using {@link #get}. *

    The primary NFC-V I/O operation is {@link #transceive}. Applications must * implement their own protocol stack on top of {@link #transceive}. + * + *

    Note: 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. * + *

    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 be6ccd0da8fd..be5cbd210d86 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; *

  • I/O operations may block, and should never be called on the main application * thread. * + * + *

    Note: 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 { *

    Only one {@link TagTechnology} object can be connected to a {@link Tag} at a time. *

    Applications must call {@link #close} when I/O operations are complete. * + *

    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. * + *

    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 { *

    Also causes all blocked I/O operations on other thread to be canceled and * return with {@link IOException}. * + *

    Requires the {@link android.Manifest.permission#NFC} permission. + * * @see #connect() */ public void close() throws IOException; @@ -195,6 +204,7 @@ public interface TagTechnology extends Closeable { *

    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. *

    Does not cause RF activity, and does not block. + * * @return true if I/O operations should be possible */ public boolean isConnected(); -- 2.11.0