NFC documentation overhaul. (74fe6c6b) · Commits · e / os / android_frameworks_base

core/java/android/nfc/NfcAdapter.java

+48 −25

Original line number	Diff line number	Diff line
		@@ -33,10 +33,11 @@ import android.os.ServiceManager;
		import android.util.Log;

		/**
		* Represents the device's local NFC adapter.
		* Represents the local NFC adapter.
		* <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";
		@@ -359,14 +360,13 @@ public final class NfcAdapter {

		/**
		* Return true if this NFC Adapter has any features enabled.
		* <p>
		* If this method returns false, then applications should request the user
		* turn on NFC tag discovery in Settings.
		* <p>
		* If this method returns false, the NFC hardware is guaranteed not to
		* perform or respond to any NFC communication.
		*
		* @return true if this NFC Adapter is enabled to discover new tags
		* <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.
		*
		* @return true if this NFC Adapter has any features enabled
		*/
		public boolean isEnabled() {
		try {
		@@ -414,17 +414,24 @@ public final class NfcAdapter {
		}

		/**
		* Enables foreground dispatching to the given Activity. This will force all NFC Intents that
		* match the given filters to be delivered to the activity bypassing the standard dispatch
		* mechanism. If no IntentFilters are given all the PendingIntent will be invoked for every
		* dispatch Intent.
		* Enable foreground dispatch to the given Activity.
		*
		* <p>This will give give priority to the foreground activity when
		* dispatching a discovered {@link Tag} to an application.
		*
		* <p>Activities must call {@link #disableForegroundDispatch} in
		* their {@link Activity#onPause} callback.
		*
		* <p>a null set of intent filters will cause the forground activity
		* to receive all tags.
		*
		* This method must be called from the main thread.
		* <p>This method must be called from the main thread, and
		* only when the activity is in the foreground (resumed). *
		*
		* @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
		* @throws IllegalStateException
		* @throws IllegalStateException if the Activity is not currently in the foreground
		*/
		public void enableForegroundDispatch(Activity activity, PendingIntent intent,
		IntentFilter[] filters, String[][] techLists) {
		@@ -450,13 +457,16 @@ public final class NfcAdapter {
		}

		/**
		* Disables foreground activity dispatching setup with
		* {@link #enableForegroundDispatch}.
		* Disable foreground dispatch to the given activity.
		*
		* <p>This must be called before the Activity returns from
		* it's <code>onPause()</code> or this method will throw an IllegalStateException.
		* <p>After calling {@link #enableForegroundDispatch}, an activity
		* must call this method before its {@link Activity#onPause} callback
		* completes.
		*
		* <p>This method must be called from the main thread.
		*
		* @param activity the Activity to disable dispatch to
		* @throws IllegalStateException if the Activity has already been paused
		*/
		public void disableForegroundDispatch(Activity activity) {
		ActivityThread.currentActivityThread().unregisterOnActivityPausedListener(activity,
		@@ -484,13 +494,22 @@ public final class NfcAdapter {
		}

		/**
		* Enable NDEF message push over P2P while this Activity is in the foreground. For this to
		* function properly the other NFC device being scanned must support the "com.android.npp"
		* NDEF push protocol.
		* Enable NDEF message push over P2P while this Activity is in the foreground.
		*
		* <p>For this to function properly the other NFC device being scanned must
		* support the "com.android.npp" NDEF push protocol. Support for this
		* protocol is currently optional for Android NFC devices.
		*
		* <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.
		* Only the foreground activity may receive tag discovered dispatches via
		* {@link #enableForegroundDispatch}.
		*
		* @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
		* @throws OperationNotSupportedException if this Android device does not support NDEF push
		*/
		public void enableForegroundNdefPush(Activity activity, NdefMessage msg) {
		if (activity == null \|\| msg == null) {
		@@ -510,13 +529,17 @@ public final class NfcAdapter {
		}

		/**
		* Disables foreground NDEF push setup with
		* {@link #enableForegroundNdefPush}.
		* Disable NDEF message push over P2P.
		*
		* <p>This must be called before the Activity returns from
		* it's <code>onPause()</code> or this method will throw an IllegalStateException.
		* <p>After calling {@link #enableForegroundNdefPush}, an activity
		* must call this method before its {@link Activity#onPause} callback
		* completes.
		*
		* <p>This method must be called from the main thread.
		*
		* @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
		*/
		public void disableForegroundNdefPush(Activity activity) {
		ActivityThread.currentActivityThread().unregisterOnActivityPausedListener(activity,

core/java/android/nfc/Tag.java

+86 −26

Original line number	Diff line number	Diff line
		@@ -16,6 +16,7 @@

		package android.nfc;

		import android.content.Context;
		import android.nfc.tech.IsoDep;
		import android.nfc.tech.MifareClassic;
		import android.nfc.tech.MifareUltralight;
		@@ -33,27 +34,69 @@ import android.os.Parcelable;
		import java.util.Arrays;

		/**
		* Represents a (generic) discovered tag.
		* Represents an NFC tag that has been discovered.
		* <p>
		* A tag is a passive NFC element, such as NFC Forum Tag's, MIFARE class Tags,
		* Sony FeliCa Tags, etc.
		* {@link Tag} is an immutable object that represents the state of a NFC tag at
		* the time of discovery. It can be used as a handle to {@link TagTechnology} classes
		* to perform advanced operations, or directly queried for its ID ({@link #getId} and the
		* set of technologies it contains ({@link #getTechList}). Arrays passed to and
		* returned by this class are not cloned, so be careful not to modify them.
		* <p>
		* Tag's have a type and usually have a UID.
		* A new tag object is created every time a tag is discovered (comes into range), even
		* if it is the same physical tag. If a tag is removed and then returned into range, then
		* only the most recent tag object can be successfully used to create a {@link TagTechnology}.
		*
		* <h3>Tag Dispatch</h3>
		* When a tag is discovered, a {@link Tag} object is created and passed to a
		* single application via the {@link NfcAdapter#EXTRA_TAG} extra in a
		* {@link Context#startActivity} {@link android.content.Intent}. A four stage dispatch is used to select the
		* most appropriate application to handle the tag. The Android OS executes each stage in order,
		* and completes dispatch as soon as a single matching application is found. If there are multiple
		* matching applications found at any one stage then the Android Activity Chooser dialog is shown
		* to allow the user to select the application.
		* <h4>1. Foreground activity dispatch</h4>
		* A foreground activity that has called {@link NfcAdapter#enableForegroundDispatch} is
		* given priority. See the documentation on {#link NfcAdapter#enableForegroundDispatch} for
		* its usage.
		* <h4>2. NDEF data dispatch</h4>
		* If the tag contains NDEF data, then {@link Context#startActivity} is called with
		* {@link NfcAdapter#ACTION_NDEF_DISCOVERED} and a data URI determined from the
		* first NDEF Record in the first NDEF Message in the Tag. This allows NDEF tags to be given
		* priority dispatch to applications that can handle the content.
		* See {@link NfcAdapter#ACTION_NDEF_DISCOVERED} for more detail. If the tag does not contain
		* NDEF data, or if no application is registered
		* for {@link NfcAdapter#ACTION_NDEF_DISCOVERED} with a matching data URI then dispatch moves
		* to stage 3.
		* <h4>3. Tag Technology dispatch</h4>
		* {@link Context#startActivity} is called with {@link NfcAdapter#ACTION_TECH_DISCOVERED} to
		* dispatch the tag to an application that can handle the technologies present on the tag.
		* Technologies are defined as sub-classes of {@link TagTechnology}, see the package
		* {@link android.nfc.tech}. The Android OS looks for an application that can handle one or
		* more technologies in the tag. See {@link NfcAdapter#ACTION_TECH_DISCOVERED for more detail.
		* <h4>4. Fall-back dispatch</h4>
		* If no application has been matched, then {@link Context#startActivity} is called with
		* {@link NfcAdapter#ACTION_TAG_DISCOVERED}. This is intended as a fall-back mechanism.
		* See {@link NfcAdapter#ACTION_TAG_DISCOVERED}.
		*
		* <p>
		* {@link Tag} objects are passed to applications via the {@link NfcAdapter#EXTRA_TAG} extra
		* in {@link NfcAdapter#ACTION_TAG_DISCOVERED} intents. A {@link Tag} object is immutable
		* and represents the state of the tag at the time of discovery. It can be
		* directly queried for its UID and Type, or used to create a {@link TagTechnology} using the
		* static <code>get()</code> methods on the varios tech classes.
		* <i>The Tag dispatch mechanism was designed to give a high probability of dispatching
		* a tag to the correct application without showing the user an Application Chooser dialog.
		* This is important for NFC interactions because they are very transient - if a user has to
		* move the Android device to choose an application then the connection is broken.</i>
		*
		* <h3>NFC Tag Background</h3>
		* An NFC tag is a passive NFC device, powered by the NFC field of this Android device while
		* it is in range. Tag's can come in many forms, such as stickers, cards, key fob, or
		* even embedded in a more sophisticated device.
		* <p>
		* Tags can have a wide range of capabilities. Simple tags just offer read/write semantics,
		* and contain some one time
		* programmable areas to make read-only. More complex tags offer math operations
		* and per-sector access control and authentication. The most sophisticated tags
		* contain operating environments such as Javacard, allowing complex interactions with the
		* applets executing on the tag. Use {@link TagTechnology} classes to access a broad
		* range of capabilities available in NFC tags.
		* <p>
		* A {@link Tag} can be used to create a {@link TagTechnology} only while the tag is in
		* range. If it is removed and then returned to range, then the most recent
		* {@link Tag} object (in {@link NfcAdapter#ACTION_TAG_DISCOVERED}) should be used to create a
		* {@link TagTechnology}.
		* <p>This is an immutable data class. All properties are set at Tag discovery
		* time and calls on this class will retrieve those read-only properties, and
		* not cause any further RF activity or block. Note however that arrays passed to and
		* returned by this class are not cloned, so be careful not to modify them.
		*/
		public final class Tag implements Parcelable {
		/package/ final byte[] mId;
		@@ -149,21 +192,35 @@ public final class Tag implements Parcelable {

		/**
		* Get the Tag Identifier (if it has one).
		* <p>Tag ID is usually a serial number for the tag.
		*
		* @return ID, or null if it does not exist
		* <p>The tag identifier is a low level serial number, used for anti-collision
		* and identification.
		* <p> Most tags have a stable unique identifier
		* (UID), but some tags will generate a random ID every time they are discovered
		* (RID), and there are some tags with no ID at all (the byte array will be zero-sized).
		* <p> The size and format of an ID is specific to the RF technology used by the tag.
		* <p> This function retrieves the ID as determined at discovery time, and does not
		* perform any further RF communication or block.
		* @return ID as byte array, never null
		*/
		public byte[] getId() {
		return mId;
		}

		/**
		* Returns technologies present in the tag that this implementation understands,
		* or a zero length array if there are no supported technologies on this tag.
		*
		* The elements of the list are the names of the classes implementing the technology.
		*
		* Get the technologies available in this tag, as fully qualified class names.
		* <p>
		* A technology is an implementation of the {@link TagTechnology} interface,
		* and can be instantiated by calling the static <code>get(Tag)</code>
		* method on the implementation with this Tag. The {@link TagTechnology}
		* object can then be used to perform advanced, technology-specific operations on a tag.
		* <p>
		* Android defines a mandatory set of technologies that must be correctly
		* enumerated by all Android NFC devices, and an optional
		* set of proprietary technologies.
		* See {@link TagTechnology} for more details.
		* <p>
		* The ordering of the returned array is undefined and should not be relied upon.
		* @return an array of fully-qualified {@link TagTechnology} class-names.
		*/
		public String[] getTechList() {
		return mTechStringList;
		@@ -198,6 +255,9 @@ public final class Tag implements Parcelable {
		return mTagService;
		}

		/**
		* Human-readable description of the tag, for debugging.
		*/
		@Override
		public String toString() {
		StringBuilder sb = new StringBuilder("TAG ")

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

+53 −32

Original line number	Diff line number	Diff line
		@@ -24,18 +24,14 @@ import android.util.Log;
		import java.io.IOException;

		/**
		* A low-level connection to a {@link Tag} using the ISO-DEP technology, also known as
		* ISO1443-4.
		* Provides access to ISO-DEP (ISO 14443-4) properties and I/O operations on a {@link Tag}.
		*
		* <p>You can acquire this kind of connection with {@link #get}.
		* Use this class to send and receive data with {@link #transceive transceive()}.
		*
		* <p>Applications must implement their own protocol stack on top of
		* {@link #transceive transceive()}.
		*
		* <p class="note"><strong>Note:</strong>
		* Use of this class requires the {@link android.Manifest.permission#NFC}
		* permission.
		* <p>Acquire a {@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).
		*/
		public final class IsoDep extends BasicTagTechnology {
		private static final String TAG = "NFC";
		@@ -49,10 +45,13 @@ public final class IsoDep extends BasicTagTechnology {
		private byte[] mHistBytes = null;

		/**
		* Returns an instance of this tech for the given tag. If the tag doesn't support
		* this tech type null is returned.
		* Get an instance of {@link IsoDep} for the given tag.
		* <p>Does not cause any RF activity and does not block.
		* <p>Returns null if {@link IsoDep} was not enumerated in {@link Tag#getTechList}.
		* This indicates the tag does not support ISO-DEP.
		*
		* @param tag The tag to get the tech from
		* @param tag an ISO-DEP compatible tag
		* @return ISO-DEP object
		*/
		public static IsoDep get(Tag tag) {
		if (!tag.hasTech(TagTechnology.ISO_DEP)) return null;
		@@ -75,13 +74,13 @@ public final class IsoDep extends BasicTagTechnology {
		}

		/**
		* Sets the timeout of an IsoDep transceive transaction in milliseconds.
		* If the transaction has not completed before the timeout,
		* any ongoing {@link #transceive} operation will be
		* aborted and the connection to the tag is lost. This setting is applied
		* only to the {@link Tag} object linked to this technology and will be
		* reset when {@link IsoDep#close} is called.
		* The default transaction timeout is 300 milliseconds.
		* Set the timeout of {@link #transceive} in milliseconds.
		* <p>The timeout only applies to ISO-DEP {@link #transceive}, 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.
		* @param timeout timeout value in milliseconds
		*/
		public void setTimeout(int timeout) {
		try {
		@@ -102,29 +101,51 @@ public final class IsoDep extends BasicTagTechnology {
		}

		/**
		* Return the historical bytes if the tag is using {@link NfcA}, null otherwise.
		* Return the ISO-DEP historical bytes for {@link NfcA} tags.
		* <p>Does not cause any RF activity and does not block.
		* <p>The historical bytes can be used to help identify a tag. They are present
		* only on {@link IsoDep} tags that are based on {@link NfcA} RF technology.
		* If this tag is not {@link NfcA} then null is returned.
		* <p>In ISO 14443-4 terminology, the historical bytes are a subset of the RATS
		* response.
		*
		* @return ISO-DEP historical bytes, or null if this is not a {@link NfcA} tag
		*/
		public byte[] getHistoricalBytes() {
		return mHistBytes;
		}

		/**
		* Return the hi layer response bytes if the tag is using {@link NfcB}, null otherwise.
		* Return the higher layer response bytes for {@link NfcB} tags.
		* <p>Does not cause any RF activity and does not block.
		* <p>The higher layer response bytes can be used to help identify a tag.
		* They are present only on {@link IsoDep} tags that are based on {@link NfcB}
		* RF technology. If this tag is not {@link NfcB} then null is returned.
		* <p>In ISO 14443-4 terminology, the higher layer bytes are a subset of the
		* ATTRIB response.
		*
		* @return ISO-DEP historical bytes, or null if this is not a {@link NfcB} tag
		*/
		public byte[] getHiLayerResponse() {
		return mHiLayerResponse;
		}

		/**
		* Send data to a tag and receive the response.
		* <p>
		* This method will block until the response is received. It can be canceled
		* with {@link #close}.
		* <p>Requires {@link android.Manifest.permission#NFC} permission.
		* Send raw ISO-DEP data to the tag and receive the response.
		*
		* <p>Applications must only send the INF payload, and not the start of frame and
		* end of frame indicators. Applications do not need to fragment the payload, it
		* will be automatically fragmented and defragmented by {@link #transceive} if
		* it exceeds FSD/FSC limits.
		*
		* <p>This is an I/O operation and will block until complete. It must
		* 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 data bytes to send
		* @return bytes received in response
		* @throws IOException if the target is lost or connection closed
		* @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
		* @throws IOException if there is an I/O failure, or this operation is canceled
		*/
		public byte[] transceive(byte[] data) throws IOException {
		return transceive(data, true);

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

+204 −62

File changed.

Preview size limit exceeded, changes collapsed.

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

+72 −40

File changed.

Preview size limit exceeded, changes collapsed.